Below is an instructional guide detailing the process for onboarding audience data and segment files to the LiveIntent platform using the LiveIntent Audience API. 

Obtain an access token

All requests to the API must contain a valid access token. To obtain the access token, you will need a username and password, which can be provided to you by your LiveIntent Account Manager.

An example login request to obtain an access token looks as follows:

 # replace your username and password

curl -X POST 'https://merlin.liveintent.com/login' -d '{

  "username": "[email protected]",

  "password": "secret"

}' --header 'Content-Type: application/json'

The response will contain the access token in the token field. 

# example response

{

  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImYzYzM3Y2EzNzAyZjExZTlhNjc5MDI0MmFjMTIwMDA2IiwidXNlcm5hbWUiOiJtaWFAZXhhbXBsZS5jb20iLCJhY2Nlc3NUb2tlbiI6ImY4ZTU0ODU2MDA0YThjZjJlNTI0OTVhZGIzMzAyYTk1YzQzMTdmY2IiLCJpYXQiOjE1NTcxNjg3MjUsImV4cCI6MTU1NzI1NTEyNX0.cI7_wHROc_gkhDAhQ3xFy6ferqfOr7avU_TYpEtOjKE",

  "username": "[email protected]",

  "userId": "f3c37ca3702f11e9a6790242ac120006",

  "refreshToken": "dc0487e9c4ed00b0caa92270a94b2f435d1c61b6"

}

Prepare the file 

You will make a single request to upload a single large file of hashed email addresses.

To get started, create a .txt, .csv, or .zip file containing a single column with each row containing a single identifier. Make sure the identifiers are not surrounded by quotes or other special characters. 

Save the file and record the path to its location.

Obtain a presigned URL

With your access token, make a request to the audience/upload endpoint to obtain a presigned URL containing information about the action you are about to perform with your audience.

You may use the LiveIntent Audience API to create a new segment, add hashed emails to an existing segment, or remove hashed emails from an existing segment.

For example, to add all hashes of file add.sha2.txt to audience 160019, you would make a request like the following: 

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImYzYzM3Y2EzNzAyZjExZTlhNjc5MDI0MmFjMTIwMDA2IiwidXNlcm5hbWUiOiJtaWFAZXhhbXBsZS5jb20iLCJhY2Nlc3NUb2tlbiI6ImY4ZTU0ODU2MDA0YThjZjJlNTI0OTVhZGIzMzAyYTk1YzQzMTdmY2IiLCJpYXQiOjE1NTcxNjg3MjUsImV4cCI6MTU1NzI1NTEyNX0.cI7_wHROc_gkhDAhQ3xFy6ferqfOr7avU_TYpEtOjKE' -d '{

  "filename": "add.sha2.txt",

  "action": "add",

  "type": "sha2"

}' 'https://merlin.liveintent.com/audience/upload/160019'

The response would look like this:

{

  "requestId": "1557157064.754512",

  "output": {

    "presignedURI": "https://liveaudience-uploader.s3.amazonaws.com/upload/2019-01-01/160019'/add/61f288f4de4fd1acb888783b/add.sha2.txt?x-amz-meta-action=add&x-amz-meta-type=sha2&x-amz-meta-filename=add.sha2.txt&x-amz-meta-advertiser-id=5634&x-amz-meta-segment-id=160019'&x-amz-meta-unique-segment-id=93954&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJL2OWONMYNAUZPAA%2F20190506%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190506T153744Z&X-Amz-SignedHeaders=host%3Bx-amz-meta-action%3Bx-amz-meta-type%3Bx-amz-meta-filename%3Bx-amz-meta-advertiser-id%3Bx-amz-meta-segment-id%3Bx-amz-meta-unique-segment-id&X-Amz-Expires=3600&X-Amz-Signature=72f09a367bab016158c426797b1c41cbad30b181f65a985da35c08de98133a13"

  }

}

Upload the file

With the presigned URL from the previous step, you are now ready to upload the file. Make a PUT request to the presigned URL and provide the path to your file as an argument.

For example, to upload the file add.sha2.txt you would call the endpoint as follows:

curl -i -X PUT -T add.sha2.txt "https://liveaudience-uploader.s3.amazonaws.com/upload/2019-01-01/2000008860'/add/61f288f4de4fd1acb888783b/add.sha2.txt?x-amz-meta-action=add&x-amz-meta-type=sha2&x-amz-meta-filename=add.sha2.txt&x-amz-meta-advertiser-id=5634&x-amz-meta-segment-id=2000008860'&x-amz-meta-unique-segment-id=93954&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJL2OWONMYNAUZPAA%2F20190506%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190506T153744Z&X-Amz-SignedHeaders=host%3Bx-amz-meta-action%3Bx-amz-meta-type%3Bx-amz-meta-filename%3Bx-amz-meta-advertiser-id%3Bx-amz-meta-segment-id%3Bx-amz-meta-unique-segment-id&X-Amz-Expires=3600&X-Amz-Signature=72f09a367bab016158c426797b1c41cbad30b181f65a985da35c08de98133a13"

If you receive a status code of 200, your file has successfully been uploaded!