API reference

Endpoints Error codes

Overview

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
Authorization: Bearer [YOUR API AUTH TOKEN HERE]
			

Requests and responses

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": [
    {
      "your-user-id": "ABC123"
    }
  ]
}
			

2. URL encoded JSON request data


%7B%22users%22%3A%5B%7B%22your-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%22your-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":{"our-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%22our-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.

Endpoints

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

Explain "your-user-id" and "our-user-id"

Request parameters

key type description example
users array An array of request "user" objects example
users[].your-user-id string example
users[].our-user-id string example
users[].data object An array containing "field" objects. Array items are "keyed" with the API field name example
users[].data["email"] array A "field" object "keyed" with the API field name, eg "email" example
users[].data["email"].value mixed The value to be set for this field, for this user example

Example 1 - Basic user creation

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


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

Example 2 - Creating multiple users


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

Example 3 - Setting user data


{
  "users": [
    {
      "your-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

key type description example
fields array An array of "field" objects example
fields["email"].field object Definition of a "field", required if a new field is to be created "on the fly" example
fields["email"].field[].type string An optional field definition required if this field is to be created "on the fly" example
fields["email"].field[].cast object An optional "cast" definition that determins how input values are "cast" into the field value type example
users["email"].field[].cast.empty-values array A list of values that correspond to "empty" values. example
fields["email"].field[].cast.yes-values array (boolean fields only) A list of values that correspond to "yes" values. example
fields["email"].field[].cast.no-values array (boolean fields only) A list of values that correspond to "no" values. example
fields["email"].field[].cast.input-format string (date/datetime fields only) A date format pattern used to convert input dates. example

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": [
    {
      "your-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": [
    {
      "your-user-id": "U0001",
      "data": {
        "terms-signed": {"value": "sure!"}
      }
    },
    {
      "your-user-id": "U0002",
      "data": {
        "terms-signed": {"value": "nope"}
      }
    },
    {
      "your-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

key type description example
where object An object containing a set of field query objects example
where["email"].value string The search text by which to filter by this field example
page-size integer The number of results to return in a single request example
page-number integer The page number / offset of the request results. 0 is the first page example

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 URL: https://userbridge.io/api/user/fetch
			

Example 2 - filtering by fields

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


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

{
  "where": {
    "our-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": [
      {
        "our-user-id": "N7FHYHTKWU2TFJUTZH44",
        "your-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"
          }
        }
      },
      {
        "our-user-id": "QPF2NZ6YGUSF9AHCSSWP",
        "your-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"
          }
        }
      }
    ]
  }
}
			

Handling errors

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

Error Cause/Advice
header_auth_absent (coming soon)
header_auth_invalid (coming soon)
header_version_absent (coming soon)
header_accept_absent (coming soon)
header_accept_notAllowed (coming soon)
header_contentType_absent (coming soon)
header_contentType_notAllowed (coming soon)
auth_token_forbidden (coming soon)
auth_sslCert_forbidden (coming soon)
auth_unsecured_notAllowed (coming soon)
api_version_notAllowed (coming soon)
api_request_invalid (coming soon)
api_context_absent (coming soon)
api_context_notAllowed (coming soon)
api_endPoint_invalid (coming soon)
endpoint_data_invalid (coming soon)
endpoint_data_forbidden (coming soon)
item_appFieldCreation_forbidden (coming soon)
item_appField_absent (coming soon)
item_appField_notAllowed (coming soon)
item_appFieldType_absent (coming soon)
item_appFieldType_notAllowed (coming soon)
item_appFieldName_invalid (coming soon)
item_appFieldCast_absent (coming soon)
item_appFieldCast_invalid (coming soon)
item_userId_forbidden (coming soon)
item_appFieldValue_absent (coming soon)
item_appFieldValue_invalid (coming soon)
item_appFieldValue_notAllowed (coming soon)
item_appFieldValue_forbidden Occurs when importing a new user and attempting to set a value to a field more than once.
api_internal_error This error occurs when something unexpected happens. In this case, contact customer support.