Getting Started

Umbel APIs provide a RESTful interface with lightweight JSON-formatted responses to ensure users can import and export data by using OAuth to allow both read and write access to users’ public and private data. This document provides information to developers on how to use the Umbel APIs.

Introduction

The most common actions you may want to do with the Umbel APIs are:

All Umbel API requests use the structure shown below:

URL: https://api.umbel.com/v1/<property>/<resource>

Method: GET/POST/DELETE

Content-Type: application/json

Authorization: Bearer <access_token>

<access_token> is the Authorization token.

Authorization

The steps listed below provide instructions on how to obtain the proper authorization credentials in order to use the Umbel APIs.

Obtain a Client ID

Only a single Client ID can be provided. Currently, we do not automate the Client ID assignment, so you need to contact support or your Client Partner in order to obtain one. Typically, a generic API user will be created for your account and a Client ID will be generated along with that API user. These will be your API credentials for authorization and API usage.

Access

Once you have your API username, password, and Client ID, you will be able to generate your access token. Using these credentials, POST to the Umbel API like this:

curl --request POST \
     --url 'https://auth.umbel.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{"grant_type": "password", "client_id": "<your_client_id>", "username": "<your_api_username>", "password": "<your_api_password>"}'

You should receive a response like the example below.

{
  "access_token": "7e523904dba9ba9b667d80acbeb856fa0ab11deb",
  "expires_in": 2592000,
  "session_id": null
}

Use the value returned for “access_token” in future requests to the Umbel API for up to 30 days. After 30 days, the access token will expire, and you will need to request another.

After generating the access token, you can interact with any of the Umbel APIs. The sample below shows you how to get information about a specific segment (iTunes brand) from the Umbel platform:

curl --request GET \
     --url 'https://api.umbel.com/v1/<property>/segments?name=iTunes' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'
[
  {
    "id":1029,
    "name":"iTunes",
    "type":"brand"
  }
]

Errors

Umbel’s REST API returns standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2XX range indicate success, codes in the 4XX range indicate an error, and codes in the 5XX range indicate an error with internal servers.

Pagination in API Results

Endpoints such as /segments/{id}/profiles may yield very large result sets—potentially millions of individual profiles in a collection. To handle this, the API will paginate the results, providing metadata in each response with a link of the next and previous page of the result set. Also included is the Umbel UUID of the first profile of the next result page, the first profile of the previous result page, and the total number of profiles contained in the present page of the result.

The size of the page is configured by a URL parameter called limit. The default value and maximum value of the limit is 1000 profiles per page.

Asynchronous Requests

Some API endpoints, notably /export, initiate long running jobs. When you POST a new export definition, you will receive an immediate response indicating that the definition was successfully received. However, the resulting data set may take some time to be made available. For these cases, Umbel provides webhook notifications, automated data pushing, or allows for simple status polling to take action when your data is ready. Details are provided in the export section below.

Read Only IDs & Other Fields

The schema for the JSON objects that are passed in to POST requests will frequently contain ID properties. As a developer, you do not need to specify these values. The ID is assigned by the Umbel platform and returned to you in the value returned from a successful POST or from a GET method. For example, you may specify a Facebook token when creating a profile. Umbel will retrieve the Facebook graph for that token during processing and later return a Facebook ID when you retrieve that profile.