Partner Integration

Configuring white-labelling

The Uberall app is available as a whitelabel and can be customised to match your corporate identity.

Please provide logos, CI colors and company information to your Partner Growth Manager at Uberall, so that we can configure your whitelabel app.

Accessing the application under your own domain

Once your whitelabel app is configured on Uberall’s side, it can be accessed under https://$WL_SUBDOMAIN/en/app/$WL_IDENTIFIER.

You can now set up a CNAME entry for the desired subdomain where your back office and/or your customers will access the app (ex. localisting.yourdomain.com) and point it to wl.uberall.com.

Let us know once it’s done, so we make sure that the app is available under that sub-domain.

Customising the sender address for mails sent by the app

Once you provided us with the desired sender email address that will be used for product emails, we will provide you with a set of CNAME entries that you can set up in your DNS. These ensure that emails are not marked as spam.

Adding a custom navigation header bar (optional)

For most use cases, our own navigation bar should be sufficient. If you have your own already built, with custom branding and functionality, you may provide Uberall with the following:

• HTML
• CSS
• JavaScript (if any)

Some considerations:

• Any JavaScript should be as minimal as possible. Only code required to work with the navigation bar should be included (e.g. code to toggle a dropdown open/closed)
• Everything should be namespaced
• Class names/IDs should be namespaced, e.g. “.CUSTOMERNAV_header-bar” to avoid conflicts with the rest of our application
• JavaScript should be encapsulated, and event listeners should explicitly only listen to events generated by the navigation bar

There are two ways to SSO in the platform

Basic SSO

The full guide is here Basic SSO. On the last step, you will need to login the user to your own domain to: https://$WL_SUBDOMAIN/en/app/$WL_IDENTIFIER?access_token=$ACCESSTOKEN

SAML 2.0 SSO

The guide is here. If you don't have access to the SSO settings tab, contact your partner success manager.

The SSO flow can also being used for impersonating a user, so the support can access the app via the "sight" of the specific user. This login won't be recognized as a user login.

For this you just need to send the boolean value "loginOnBehalf" with the first SSO call.

Email Example:

curl -X POST \
  https://uberall.com/api/users/login \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{"email":"user@email.com","loginOnBehalf":true}'

UserID Example:

curl -X POST \
  https://uberall.com/api/users/login \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{"userId":"12345","loginOnBehalf":true}'

Response:

{
    "status": "SUCCESS",
    "response": {
        "access_token": "$ACCESSTOKEN",
        "loginOnBehalf": true
    }
}

A successful impersonated login can be identified via the returned "loginOnBehalf" field in the response.

As with the SSO the returned access token needs to be passed to the white-labeled app URL.

Example: https://$WL_SUBDOMAIN/en/app/$WL_IDENTIFIER?access_token=$ACCESSTOKEN

A customer corresponds to a set of 3 objects on the Uberall platform: business, location and user.

Business

A business is linked to a product plan (defining the features, list of directories and countries available as per your contract) and can be seen as a “container” for locations. The common use case is that Businesses are not visible to your end customers (i.e., if your customer’s user role is LOCATION_MANAGER) and business’ data is not published on directories, so you can populate them as you wish (e.g. using the name and/or business identifier to store your internal ids and create a mapping between your system and Uberall).

Create Business

For more information see: Documentation: Business#create

Required fields: [city, name, streetAndNo, zip]

Example CURL request:

curl -X POST \
  https://uberall.com/api/businesses \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
    "identifier": "123-abc",
    "name": "Uberall",
    "streetAndNo": "Oranienburger Strasse 66",
    "zip": "10117",
    "city": "Berlin",
    "country": "DE",
    "productPlan": "123"
}'

Update business

For more information see: Documentation: Business#update

Example CURL request:

curl -X PATCH \
  https://uberall.com/api/businesses/$BUSINESS_ID \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
    "identifier": "123-abc",
    "name": "Uberall",
    "streetAndNo": "Oranienburger Strasse 66",
    "zip": "10117",
    "city": "Berlin",
    "country": "DE",
    "productPlan": "123"
}'

Location

A location corresponds to the physical location of your client’s business.

In the Uberall platform, the location object holds all the profile information that is distributed online. A location is linked to a business, and therefore associated to the business’s product plan. Changing the product plan of the business will hence automatically impact all locations under the business. If you wish that your customers are able to upgrade/downgrade individual locations, create a single location per business.

Create location with data

For more information see: Documentation: Location#create

Required fields: [city, name, street, zip, country, businessId]

Example CURL request:

curl -X POST \
  https://uberall.com/api/locations \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
    "name": "Uberall",
    "street": "Hussitenstrasse 32-33",
    "zip": "13355",
    "city": "Berlin",
    "country": "DE",
    "businessId": "123"
}'

Create empty location

For most of our partners, it is common practice to create businesses, locations and users in Uberall after a client orders the Uberall-based product. At that point in time, there oftentimes is no profile information available.

To enable this, we have created the possibility to add empty locations. If a user is managing an empty location, she will automatically enter the application’s onboarding wizard to fill out all necessary profile attributes, so that all online listings can be claimed or created accordingly.

You can create the empty location by sending the special placeholder UB_INCOMPLETE for required fields (‘name’, ‘street’, ‘zip’, ‘city’) - the country should already be known and match the supported countries of the associated product plan.

Example CURL request:

curl -X POST \
  https://uberall.com/api/locations \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
    "name": "UB_INCOMPLETE",
    "street": "UB_INCOMPLETE",
    "zip": "UB_INCOMPLETE",
    "city": "UB_INCOMPLETE",
    "country": "DE",
    "businessId": "123"
}'

Update location

For more information see: Documentation: Location#update

Example cURL request:

curl -X PATCH \
  https://uberall.com/api/locations/$LOCATION_ID \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
    "name": "Uberall",
    "street": "Hussitenstrasse 32-33",
    "zip": "13355",
    "city": "Berlin",
    "country": "DE",
    "businessId": "123"
}'

User

A user corresponds to a person that has access to one or more locations by logging into the Uberall app.

We strongly recommend assigning "Small and Medium Business" (SMB) clients’ users the LOCATION_MANAGER role, as those are limited to managing location data and/or access the engage functionality (depending on the user features assigned to them). However, they cannot create new locations or cancel existing ones, and they also cannot create additional users. You can also populate the user identifier with your internal ids to e.g. map a customer in your system to a user in Uberall.

If you wish to remain the source of truth for customer data (i.e. Uberall user data such as name, email address, etc.), make sure to keep the data in Uberall up-to-date.

Additionally, in order for customers to be able to edit their information only in your system, this functionality needs to be hidden in the Uberall application. You can do so by not sending the feature USER_SELF_EDIT when creating the user.

Create LOCATION_MANAGER user

For more information see: Documentation: User#create

Example CURL request:

curl -X POST \
  https://uberall.com/api/users \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
   "identifier": "xyz",
   "email": "jane@mycompany.com",
   "salutation": "FEMALE",
   "firstname": "Jane",
   "lastname": "Smith",
   "status": "VERIFIED",
   "role": "LOCATION_MANAGER",
   "managedLocations": [213874],
   "preferredLanguage": "en",
   "emailSettings": [
       {"emailType": "DIGEST","frequency": "WEEKLY"},
       {"emailType": "UNREAD_REVIEW_NOTIFICATION","frequency": "ALWAYS"}
   ],
   "features": [
    "LOCATION_READ",
    "LOCATION_WRITE",
    "LISTINGS",
    "SUPPRESSION",
    "TRACKING",
    "INBOX",
    "INBOX_APPROVAL",
    "POSTING",
    "UPGRADE",
    "LOCATION_STATUS_CHANGE"
   ],
   "whitelabelInformationIdentifier": "reseller_whitelabel"
}'

Update user

For more information see: Documentation: User#update

Example CURL request:

curl -X PATCH \
  https://uberall.com/api/users/$USER_ID \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
   "firstname": "Jane",
   "lastname": "Changed"
}'

Add new location to existing user

If a customer manages several stores, she can possibly use the product for multiple locations. In this case, in the Uberall application, those multiple locations can be associated to a same user (LOCATION_MANAGER).

Example CURL request:

curl -X PATCH \
  https://uberall.com/api/users/$USER_ID \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
   "managedLocations": [213874, 256896],
}'

Below are a few scenarios of suggested customer provisioning flow (i.e. creating the needed structure containing business, location and user).

Regular Creation

The following flow should be used for new customers that were never passed onto the Uberall application. If the user already exists and you try to create a new one with the same values (identifier, name, mail, etc...), an error will be returned.

1. Create a business
2. Create a location
3. (if location data) – create normal location
4. (if no location data) – create empty location
5. Create a user
6. If location or user data changes, call corresponding update endpoints
7. Login as user to app via SSO

Partial creation

The following flow should be used if the customer already exists in Uberall (i.e. the corresponding user exists) and you want to create and add a new location to it.

1. Create a business
2. Create a location
3. (if location data) – create normal location
4. (if no location data) – create empty location
5. Add the new location to the existing user
6. If location or user data changes, call corresponding update endpoints
7. Login as user to app via SSO

Upgrade / Downgrade

The following flow should be used if the customer changes the subscription plan of her location.

Initial setup: map the customer-facing subscriptions to the Uberall product plans (Fetch list of product plans)

Change the subscription of the business containing the location (Change the product plan id via an Update business call)

Deactivation

The following flow should be used if the customer quits the subscription plan of her location.

Update the location status to INACTIVE:

Example CURL request:

curl -X PATCH \
  https://uberall.com/api/locations/$LOCATION_ID \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'privateKey: $pvtKey' \
  -d '{
    "status": "INACTIVE"
}'