How do I use the Universal Onboarding APIs?

A how-to guide for populating a list, forecasting the match rate, and placing a Universal Onboarding subscription

Overview

Universal Onboarding consists of a self-service user interface, but it can also be accessed programmatically via a set of APIs.  At a high level, the process to onboard data mimics the UI and can be broken down into four steps:

  1. Uploading a file with the records to onboard
  2. Creating a `list` from that file
  3. (Optional) Forecasting the match rate of the list 
  4. Creating a subscription to buy the matched data

Uploading a File

If you haven't done so already, you'll need to upload the file that containing the data that will be matched.  This is a two step process:

  1. Requesting an endpoint that the file can be uploaded to
  2. Uploading the file

Upload Endpoint Request

First you must request the endpoint that the file will be uploaded to.  To do so you need to make a POST request to the following API endpoint: /v1/uploads/{file_name}

{file_name} should be replaced with the name of the file.  The file name itself is arbitrary but it should be unique within your organization.

The API will return a response with the details of the endpoint to use for the file upload.

Example Response:

{
"path":"file123.csv",
"url":"https://narrative-file-upload-prod.s3.amazonaws.com/companyId%3D0/file123.csv?X-Amz-Security-Token={security_token}",
"expiry":"2021-02-02T13:40:04.543Z"
}

The security token from the response below has been removed for brevity.  The actual response will include a long string that acts as the security token and you should keep that string intact for the next step.

Uploading the File

To upload the file you can make a PUT to the url parameter from the response in the previous step (so long as the expiry date has not passed).  The body of the request should contain the properly encoded contents of the file you would like to upload.

Assuming you receive a 200 response code, your file has been uploaded and can now be referenced when creating a list in the subsequent step.

Creating a List

A list is an object in the Narrative Data Streaming Platform that can be used to filter subscriptions.  You can create a list that is backed by the file you uploaded in the previous step.  To do so make a POST request the following endpoint:  /v1/lists

The body of the request should take the following form:

{
name: "Example List",
description: "An example list",
source_file: "file123.csv"
}

The name and description parameters can be set at your discretion.  The source_file parameter should be the path parameter from the response you received when requesting and upload endpoint.

If the list has been created you'll receive a 200 response in the following format:

{
"id":123,
"name":"Example list",
"description":"An example list",
"created_at":"2021-02-02T13:10:06.139",
"count":1000,
"errors":0,
"tags":[],
"status":"pending"
}

The id parameter will be used to refer to the list in subsequent API calls.

Forecasting (Optional)

With the list created, you can now forecast the match rate.  

While this step is optional, the information returned as part of this request is useful in understanding how much data is available and the approximate cost of that data.  This information is useful when setting up your subscription which will be done in the following step.

The forecast can be retrieved by making a POST request to the following API endpoint: /v1/lists/{list_id}/forecast

The request body can be empty when making this request.

 The {list_id} parameter should be replaced with the id parameter received in the response when you created the list. 

The response to the forecasting API call comes in the following form:

{ 
"matched": 50,
"id_types":
[ { "id_type": "idfa",
"matched": 50,
"addressable": 75,
"pairs": 83,
"cost": { "value": 10.21, "currency": "USD" } }
]
}

The matched parameter refers to the number of unique IDs in your list that could be matched to an online identifier.  To calculate the match rate you would take the value of the matched parameter and divide it by the number of unique IDs in your list.

Values returned in the id_types parameter refer to the types of identifiers that can be mapped to your list, with approximate counts and cost.  These values are useful when setting up the subscription in the following step.

Creating a Subscription

Now that we have created our list and have our forecast the final step of the process is to create a subscription.  To do this we will make a POST request to the following endpoint with the details of the subscription which will include which list to use as part of the subscription and details about the budget being allocated:  /v1/subscriptions

The body of the request should be in the following form:

{
"name":"Subscription Foo",
"budget":{
"monthly":{"value":2000.0,"currency":"USD"}
},
"description":"A subscription for the purpose of foo",
"status":"active",
"data_packages":
[
{"id_mapping":
{
"id_types": { "left": [ "sha256_email" ], "right": [ "adid", "idfa" ],
"max_bid_price":{"value":1.00,"currency":"USD"}
}
}
]
}

If successful the API will return a 200 response and your subscription will be active. 

An active subscription will create charges that will be associated to your account's payment method!