Custom Audiences API

  • Updated

Adikteev offers its expertise to target the best users depending on your campaign objectives.
If you prefer to use your own custom audiences, you can share them with Adikteev using this API.

 

Credentials

First, ask your Adikteev Account Manager to provide you client credentials to use Adikteev APIs, made of your email address and a password.

If you are already using Adikteev Reporting API, credentials for the Audiences API are the same.

 

Step 1 - Authenticating your API client

Adikteev API uses OAUTH2 protocol for authentication. To get your API access token, you must make a POST request to the token delivery endpoint :

API route

https://public-api.adikteev.com/token

Mandatory header

  • authorization: Basic cmVwb3J0aW5nX2Rhc2hib2FyZDo=

Request body 
Email and password must be replaced with your actual credentials from the previous step

username=YOUR_EMAIL&password=YOUR_PASSWORD&grant_type=password

If your email and password are recognized, you will receive a JSON response containing a token valid for 30 days.

Sample authentication request using cURL
curl -H 'authorization: Basic cmVwb3J0aW5nX2Rhc2hib2FyZDo='
--data 'username=hello@adikteev.com&password=mypassword&grant_type=password'
-X POST 'https://public-api.adikteev.com/token'
Sample successful authentication response
{
"access_token": "abcdef98765",
"token_type": "bearer",
"expires_in": 2592000
}

 

Step 2 - Fetching your company identifier

Your company ID in Adikteev platform is a required parameter for the next steps. In order to fetch it, you can send an HTTP GET request properly authenticated to this endpoint

API route

https://public-api.adikteev.com/profile

Mandatory headers

  • authorization: Bearer YOUR_ACCESS_TOKEN

The body of the API response will contain under the field company_id a numeric identifier that needs to be stored for reuse.

Sample profile fetching request using cURL

curl -H 'authorization: Bearer abcdef98765'
-X GET 'https://public-api.adikteev.com/profile'

Sample successful profile fetching response

{
"id": 123456789,
"email": "hello@adikteev.com",
"company_id": 456,
"role": "client"
}

 

Step 3 - Creating a new segment

Only HTTP POST requests properly authenticated will return valid status code. Each segment is specific to a platform (iOS or Android). If you want to run on both iOS and Android, you will need to create 2 different segments. Company ID and access token must be replaced with your actual credentials from the previous steps.

API route

https://public-api.adikteev.com/companies/YOUR_COMPANY_ID/segments

Mandatory headers

  • authorization: Bearer YOUR_ACCESS_TOKEN
  • content-type: application/json

Request body for a new iOS segment

{"name": "YOUR_SEGMENT_NAME", "platform": "ios"}

Request body for a new Android segment

{"name": "YOUR_SEGMENT_NAME", "platform": "android"}

When an API client successfully creates a new segment, the API will return a new segment ID which will be required for the next step.

Sample segment creation request using cURL
curl -H 'authorization: Bearer abcdef98765'
-H 'content-type: application/json'
--data '{"name":"Historical Purchasers","platform":"android"}'
-X POST 'https://public-api.adikteev.com/companies/456/segments'
Sample successful segment creation response
{
"id": 123456789,
"name": "Historical Purchasers",
"companyId": 456,
"platform": "android"
"status" : "active"
}

 

Step 4 - Uploading / Updating a device ID list for a segment

Only HTTP POST requests properly authenticated will return valid status code. Every upload of a device ID list for an existing segment will override and replace the previous device ID list uploaded for this segment.

API route

https://public-api.adikteev.com/companies/YOUR_COMPANY_ID/segments/YOUR_SEGMENT_ID/upload/plain

Mandatory header

  • authorization: Bearer YOUR_ACCESS_TOKEN

The request body must contain a flat file with only unhashed device advertising IDs (IDFA for iOS, Google Advertising ID for Android) separated by line break characters.


The API will return a successful HTTP response as soon as your authentication, company ID and segment ID are valid. The API will not return any HTTP error if your device ID list (request body) is incorrectly formatted. Please check the validity of your integration with your Adikteev Account Manager directly.

Sample valid device ID list for iOS (devices.txt)
7918C635-6549-417D-8FC4-032E9320EC12
2CB9A160-C694-4428-ACCA-E7F117DFDFB7
011DCBDC-EDED-4843-AB08-02E906E5B720
506C8F0E-4481-409F-BBC6-5F5E6507FE28
CA416D34-7C77-43CB-B8BB-91D637D82956
Sample segment upload / update request using cURL
curl -H 'authorization: Bearer abcdef98765' 
--data @devices.txt
-X POST 'https://public-api.adikteev.com/companies/456/segments/123456789/upload/plain'

 

(Optional) Step 5 - Renaming an existing segment

Sending an HTTP PUT request properly authenticated allows you to change the name of a segment previously created.

API route

https://public-api.adikteev.com/companies/YOUR_COMPANY_ID/segments/YOUR_SEGMENT_ID

Mandatory headers

  • authorization: Bearer YOUR_ACCESS_TOKEN
  • content-type: application/json

Sample segment renaming using cURL

curl -H 'authorization: Bearer abcdef98765' 
-H 'content-type: application/json'
--data '{"name":"My new segment name"}'
-X PUT 'https://public-api.adikteev.com/companies/456/segments/123456789'
Sample successful segment renaming response
{
"id": 123456789,
"name": "My new segment name",
"companyId": 456,
"platform": "android"
"status" : "active"
}

 

(Optional) Step 6 - Deleting a segment manually

Sending an HTTP DELETE request properly authenticated allows you to delete a segment previously created. 

Warning this action takes effect immediately, and can therefore stop all your campaigns if they were targeting the deleted segment. 

API route

https://public-api.adikteev.com/companies/YOUR_COMPANY_ID/segments/YOUR_SEGMENT_ID

Mandatory header

  • authorization: Bearer YOUR_ACCESS_TOKEN

Sample segment deletion using cURL

curl -H 'authorization: Bearer abcdef98765'
-X DELETE 'https://public-api.adikteev.com/companies/456/segments/123456789'

Sample successful segment deletion response

true

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request