API reference

Authentication

UserBridge protects and secures its API by enforcing bearer token authentication. A token is simply a long, cryptographically random string of numbers and letters. This is essentially an extremely secure password.

Tokens & apps

Tokens are generated for you in the Dashboard. Tokens do not belong to your account, but belong to an account "app". When you create your account, a "default app" is created for you and an API token is generated to grant API access to this app.

By defining multiple "apps" in the Dashboard, and creating API tokens for each app, you can gather users from different sources (websites/apps) into your UserBridge, whilst maintaining a link to the originating source.

Error handling

If an error occurs during the execution of an API request, all changes related to that request will be "rolled back". For example, an error that occurs during a single API call that attempts to changes data on 20 users would mean all 20 users would not be affected. This keeps your data safe and consistent.

HTTP headers

Your HTTP headers should be configured as follows:

Accept: application/json
Content-Type: application/json
UserBridge-Version: 20191101
UserBridge-AppKey: [YOUR APP KEY HERE]
Authorization: Bearer [YOUR API AUTH TOKEN HERE]
			

POST endpoints

Post data should be sent as a "payload" in the form of a single JSON string. Using the "app/users [POST]" as an example:

1. Example JSON request data

{
  "users": [
    {
      "client-user-id": "ABC123"
    }
  ]
}
			

2. URL encoded JSON request data

%7B%22users%22%3A%5B%7B%22client-user-id%22%3A%22ABC123%22%7D%5D%7D
			

3. And then POSTed to the endpoint:

POST https://userbridge.io/api/app/users
%7B%22users%22%3A%5B%7B%22client-user-id%22%3A%22ABC123%22%7D%5D%7D
			

GET endpoints

Parameters sent to GET endpoints should be sent using the single URL parameter "q", whose value is a single JSON encoded string, which must be URL encoded, for example:

1. The form of a GET request would look this this:

			
https://userbridge.io/api/app/users?q={"where":{"ub-user-id":{"value":"ABC123"}}}
			

2. And the correctly URL encoded GET request would look like this:

https://userbridge.io/api/app/users?q=%7B%22where%22%3A%7B%22ub-user-id%22%3A%7B%22value%22%3A%22ABC123%22%7D%7D%7D
			

Responses

The form an API response is the same for all GET and POST endpoints.

Example of a successful API response

{
  "success": true,
  "http_code": 200,
  "request_id": "6f25dd7511d63dba3bc8fcfc90b568f89dc87b89",
  "response": {
    "users": [
    	...
    ]
  }
}
			

Example of a failed API response

{
  "success": false,
  "http_code": 400,
  "request_id": "665c7d2e3526852c501f2965b4f6845c4d11e1e3",
  "error_code": "api_internal_error"
}
			

If you receive a failed API response there are two things you can do:

• Have a look at the API error codes and see if this gives you a clue of how to fix the problem.
• In the Dashbaord you can view the API logs and examine your request data.

test/ping [GET]

The test/ping [GET] endpoint exists to help with client integration and testing - it serves no functional purpose.

Request

GET URL: https://userbridge.io/api/test/ping
			

Response

{
    "success": true,
    "http_code": 200,
    "request_id": "5d2cc8c9b1a2bbfe6b8ea6567aad69c450fe5fe4",
    "response": {
        "message": "Looking good! Your bridge is the Millau Bridge"
    }
}
			

app/users [POST]

The "app/users [POST]" endpoint can perform a number of functions in a single call, for example:

• Store users in a UserBridge app
• Set and update user field data
• Store details about user sessions when the special field "session-user-agent" is set.

Request parameters

Example 1 - Basic user creation

This simple example will create a new user without setting any field data.

{
  "users": [
    { "client-user-id": "U0001" }
  ]
}
POST URL: https://userbridge.io/api/app/users
			

Example 2 - Creating multiple users

{
  "users": [
    { "client-user-id": "U0001" },
    { "client-user-id": "U0002" },
    { "client-user-id": "U0003" }
  ]
}
POST URL: https://userbridge.io/api/app/users
			

Example 3 - Setting user data

{
  "users": [
    {
      "client-user-id": "U0001",
      "data":{
        "email": { "value": "user0001@example.com" },
        "firstnames": { "value": "Isambard" },
        "lastnames": { "value": "Brunel" },
        "address-line-1": { "value": "123 Bridgers Way" },
        "address-city": { "value": "Portsmouth" }
      }
    }
  ]
}
POST URL: https://userbridge.io/api/app/users
			

app/fields [POST]

The "app/fields [POST]" endpoint is for creating fields via the API. However, it is generally recommended to create fields using the Dashboard.

Request parameters

Example 1 - creating a text field

In this example we create a new field called "customer-notes" which can hold large amounts of text.

{
  "fields":{
    "customer-notes":{ "type": "text_long"}
  }
}
POST URL: https://userbridge.io/api/app/fields
			

Example 2 - creating several fields

We can create multiple fields in a single call to the app/fields [POST] endpoint.

{
  "fields":{
    "signup-date": { "type": "datetime"},
    "terms-conditions-agreed": { "type": "boolean"},
    "customer-notes": { "type": "text_long"}
  }
}
POST URL: https://userbridge.io/api/app/fields
			

Example 3 - input casting #1

In this example we create a field called "registration-date" and define a "cast" that will convert dates in a particular textual format into the UserBridge date format (YYYY-MM-DD).

{
  "fields": {
    "registration-date": { "type": "date", "cast": {"input-format":"l, F j, Y"} }
  }
}
POST URL: https://userbridge.io/api/app/fields

{
  "users": [
    {
      "client-user-id": "U0001",
      "data": {
        "registration-date": { "value": "Tuesday, November 19, 2019" }
      }
    }
  ]
}
POST URL: https://userbridge.io/api/app/users
			

Example 4 - input casting #2

A simpler example - here we are setting values for the "terms-signed" field for 3 users at the same time. This example follows on from the previous example and we assume the "terms-signed" field now exists.

{
  "fields":{
    "terms-signed": { "type": "boolean", "cast": {"yes-values": ["sure!","si"],"no-values": ["nada","nope"],"empty-values": ["NA"] } }
  }
}
POST URL: https://userbridge.io/api/app/fields

{
  "users": [
    {
      "client-user-id": "U0001",
      "data": {
        "terms-signed": {"value": "sure!"}
      }
    },
    {
      "client-user-id": "U0002",
      "data": {
        "terms-signed": {"value": "nope"}
      }
    },
    {
      "client-user-id": "U0003",
      "data": {
        "terms-signed": {"value": "NA"}
      }
    }
  ]
}
POST URL: https://userbridge.io/api/app/users
			

app/users [GET]

The "app/users [GET]" endpoint will retrieve zero or more users based on search criteria.

Request parameters

Example 1 - no args

Calling the "app/users [GET]" endpoint with no arguments will return the first "page" of users based on default ordering and pagination.

GET: https://userbridge.io/api/app/users
			

Example 2 - filtering by fields

The examples below demonstrate how to search for users based on field values.

{
  "where": {
    "client-user-id": { "value": "user:0001" }
  }
}

{
  "where": {
    "ub-user-id": { "value": "R2JEXLJSDFKGUUXFUHNW" }
  }
}


{
  "where": {
    "firstnames": { "value": "Ada" },
    "lastnames": { "value": "Lovelace" }
  }
}
			

Example 3 - pagination

To be able to navigate and access large numbers of users, pagination can be used. In the example below, we are asking to retrieve the 6th "page" of results (NB: the first page is page 0) and that each "page" contains a maximum of 60 users.

{
  "page-size": 60,
  "page-number": 5
}
			

---

Response

{
  "success": true,
  "http_code": 200,
  "request_id": "6a28121425a2e427287e9ce61872315950725e4a",
  "response": {
    "requested-page": 0,
    "requested-page-size": 25,
    "app-user-count": 3,
    "fetch-user-count": 2,
    "page-user-count": 2,
    "page-count": 1,
    "users": [
      {
        "ub-user-id": "N7FHYHTKWU2TFJUTZH44",
        "client-user-id": "user:0001",
        "date-last-updated": "2020-01-09 22:18:41",
        "data": {
          "firstnames": {
            "value": "Jack",
            "date-updated": "2020-01-08 07:20:26",
            "version": "1"
          },
          "state": {
            "value": "ACTIVE",
            "date-updated": "2020-01-09 22:18:41",
            "version": "1"
          }
        }
      },
      {
        "ub-user-id": "QPF2NZ6YGUSF9AHCSSWP",
        "client-user-id": "user:0002",
        "date-last-updated": "2020-01-09 22:18:41",
        "data": {
          "firstnames": {
            "value": "Jill",
            "date-updated": "2019-12-29 16:26:28",
            "version": "1"
          },
          "state": {
            "value": "ACTIVE",
            "date-updated": "2020-01-09 22:18:41",
            "version": "1"
          }
        }
      }
    ]
  }
}
			

Trouble shooting

If you are having trouble with the API, the Error codes section will help you track down the root of the problem. In addition, you can login to your account and review your API call logs and inspect both the request and response data. If you are still having trouble, then contact customer support.

Error codes