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 when the special field "session-user-agent" is set.

Request parameters

key mandatory? type description
users yes array An array of request "user" objects
users[].your-user-id   string A string you have chosen that uniquely identify a user. For more information see Glossary of terms.
users[].our-user-id   string A string randomly generated by UserBridge that uniquely identifies a user. For more information see Glossary of terms.
users[].data   object An array containing "field" objects. Array items are "keyed" with the API field name
users[].data["email"]   array A "field" object "keyed" with the API field name, eg "email"
users[].data["email"].value   mixed The value to be set for this field, for this user

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

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 mandatory? type description
where   object An object containing a set of field query objects
where["email"].value   string The search text by which to filter by this field
page-size   integer The number of results to return in a single request
page-number   integer The page number / offset of the request results. 0 is the first page

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": {
    "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 The "Authorization" property is missing from the request headers.
header_auth_invalid Although the "Authorization" property is present in the header, it contains an incorrectly formatted value.
header_version_absent The request header is missing the "UserBridge-Version" property.
header_accept_absent Request header is missing the "Accept" property.
header_accept_notAllowed The header "Accept" property must have the value "application/json".
header_contentType_absent Request header is missing the "Content-Type" property.
header_contentType_notAllowed The header "Content-Type" property must have the value "application/json".
auth_token_forbidden The supplied auth token is either incorrect or has been "disabled".
auth_sslCert_forbidden If additional SSL certificate domain verification is enabled, this error occurs when the API caller cert domain does not match the expected value.
auth_unsecured_notAllowed This error occurs if attempting to call the API from unsecured (non-HTTPS) connections.
api_version_notAllowed The value specified for the header property "UserBridge-Version" is an invalid, unknown or deprecated version number.
api_request_invalid This error occurs if there is something wrong with the API URL format/path
api_context_absent The UserBridge API expects a format such as https://userbridge.io/api/[context]/[endpoint], eg: "https://userbridge.io/api/test/ping". This error is raised if no "context" part is present.
api_context_notAllowed The API context part contains an invalid value.
api_endPoint_invalid The API endpoint is invalid for the given context. The UserBridge API scheme follows the format: https://userbridge.io/api/[context]/[endpoint].
token_method_forbidden Typically this means that the authenticated token is set to "readonly", but was attempting to call a "POST" or "PUT" API method.
endpoint_data_invalid The JSON data sent to the API endpoint is either invalid JSON, or is missing mandatory properties/data/objects. Please check the endpoint documentation.
endpoint_data_forbidden This error occurs if the endpoint request is attempting to do something the auth token is not permitted to allow. For example, if an App auth token does not allowed SPI data and the API call is asking to return API data.
item_appFieldCreation_forbidden This error occurs when the "app/fields [POST]" endpoint is called using an App auth token which does not have permission to create Fields.
item_appField_absent This error occurs when attempting to set/update user data, but the given field name does not exist.
item_appField_forbidden The authenticated API token was attempting to write to either a PII or SPI field without the required permissions.
item_appField_notAllowed Occurs when attempting to create a field with a given name that is already in use.
item_appFieldType_absent Occurs when attempting to create a field, but no field "type" is supplied.
item_appFieldType_notAllowed Occurs when attempting to create a field, but the supplied field "type" is invalid.
item_appFieldName_invalid Occurs when attempting to create a field, but the given field name is not allowed (containing illegal characters or symbols).
item_appFieldCast_absent This error occurs when field input-casting is defined, but is missing additional mandatory configuration properties. Please check the "app/fields [POST]" endpoint documentation.
item_appFieldCast_invalid When attempting to write a value to a field with input-casting but the value could not be cast.
item_userId_forbidden This error occurs when attempting to update a user when "our-user-id" is given as an identifier, but the user could not be found.
item_appFieldValue_absent An attempt is made to set data on a user, but the "value" property is not present.
item_appFieldValue_invalid An attempt is made to set data on a user, but the value is not valid for the given field type or field configuration.
item_appFieldValue_notAllowed Occurs when writing data to a user field, but the field is configure to not allow the given value. For example, attempting to set "null" when the field is configure to not allow null values. Or attempting to write a value to a field with a locked value list which is not already in the value list.
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. Due to robust transaction handling, UserBridge will never leave data in an inconsistent state.