Search

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 audience

Only HTTP POST requests properly authenticated will return valid status code. Each audience 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 audiences. 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 audience

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

Request body for a new Android segment

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

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

Sample audience 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 audience creation response
{
  "id": 123456789,
  "name": "Historical Purchasers",
  "companyId": 456,
  "platform": "android"
  "status" : "active"
}

Step 4 - Uploading / Updating a device ID list for an audience

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

API route

https://public-api.adikteev.com/companies/YOUR_COMPANY_ID/segments/YOUR_AUDIENCE_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 audience 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 audience 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'

Using IDFV instead of IDFA for iOS audiences

The API also supports IDFV device identifiers for the iOS platform only. Using IDFV instead of IDFA for iOS audiences is recommended to maximize reach using probabilistic retargeting methods. To use this feature, send an HTTP POST request to the dedicated route documented below and make sure that the request body contains a raw text file with only unhashed iOS IDFVs separated by line break characters.

API Route

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

 

[Optional] Step 5 - Listing existing audiences

Sending an HTTP GET request properly authenticated to the following endpoint allows you to review the list of audiences already created

API route

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

Mandatory headers

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

Sample audience renaming using cURL

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

[Optional] Step 6 - Renaming an existing audience

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

API route

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

Mandatory headers

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

Sample audience renaming using cURL

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

[Optional] Step 7 - Deleting an audience manually

Sending an HTTP DELETE request properly authenticated allows to delete an audience previously created. 

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

API route

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

Mandatory header

  • authorization: Bearer YOUR_ACCESS_TOKEN

Sample audience deletion using cURL

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

Sample successful audience deletion response

true

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request