Audience API Integration

How to create and edit audiences dynamically via API

Audience Creation API
This API is used to create an audience on Kayzen platform. The API returns a unique audience id which can further be used for managing device IDs association with the audience

Endpoint

https://api-audience.kayzen.io/v1/au/create

Parameters (POST call)

Required

Description

apikey

Yes

Unique API key for your account/app/website. You can get this API key from Kayzen UI. Refer Generate Audience API Key

name

Yes

Audience name of your choice

Example- Audience Creation:

POST

{

"apikey": "a6fe3455b78ce22d8481614fa332f04ca198f",

"name" : "Audience_US_Male_Shoppers"

}

Response

The id of the audience that is created in Kayzen

{

"id": 72794

}

Audience List API

This API can be used to view and read the list of audiences

Endpoint

https://audience.kayzen.io/audiences

Request Body (GET call)

Required

Description

apikey

Yes

Unique API key for your account/app/website. You can get this API key from Kayzen UI. Refer Generate Audience API Key

page

No

This parameter is used for response pagination. Every page returns maximum of 30 audience ids and names


Response

{"data":[{"id":50451,"name":"Audience_Male"},{"id":66822,"name":"Aud_HNI"},{"id":67133,"name":"Aud_Shoppers"}],"meta":{"current_page":1,"total_pages":1,"total_entries":3}}

Example- Audience List:

https://audience.kayzen.io/audiences?apikey=a6fe3455b78ce228481614fac2332f4ca198f&page=2

Response

{"data":[{"id":50451,"name":"Audience_Male"},{"id":66822,"name":"Aud_HNI"},{"id":67133,"name":"Aud_Shoppers"}],"meta":{"current_page":1,"total_pages":1,"total_entries":3}}

Audience Association Edit API

This API can be used for managing device IDs associated with an audience . Device id's (GAID/IDFA) can be added/removed from audience

Note- Device Id's added but not deleted will expire after 6 months. Use Kayzen UI to change audience expiry

Endpoint

https://api-audience.kayzen.io/v1/au/listupdate

Parameters

Required

Description

api_key

Yes

Unique API key for your account/app/website. You can get this API key from Kayzen UI. Refer Generate Audience API Key

dl_id

Yes

Array of audience ids that are either created from Kayzen UI or via audience creation API

dpid

Yes

Array of device IDs. The value will be automatically interpreted as per the following matching sequence.

IDFA formatted as uppercase with hyphens: AAAAAA-BBBB-CCCC-11111-2222222222222

GAID formatted as lowercase with hyphens

SHA1 of GAID/IDFA is alphanumeric 40 characters

Comma separated list should be provided. Batch of 2000 devices as per API request. The audience can take upto 300 million device IDs through API's.
Raw ID's recommended Eg: ["59cfc45d-58a7-4873-99b3-9c037e449005", "27c85977-9148-4f3e-a897-57780273ee01"]

dl_action

Yes

ADD - add a device ID to an audience
REMOVE - remove a device ID from an audience

tracking_partner

Yes

The tracking partner which is editing the audience.
Reach out to Kayzen Customer Success Manager, if you are not sure of this value

Example- Audience Association

POST- ADD
https://api-audience.kayzen.io/v1/au/listupdate --data {"api_key":"a6fe3455b78ce22d8481614ac2332f04ca198f","dl_id":[1234],"dpid":["095c2198-5de4-432b-96eb-a8ae57259e","015c1298-5de4-432b-96eb-a8ae57259e"],"dl_action":"ADD","tracking_partner":"partner_name"}

POST- REMOVE
https://api-audience.kayzen.io/v1/au/listupdate --data {"api_key":"a6fe3455b78ce22d8481614ac2332f04ca198f","dl_id":[1234],"dpid":["095c2198-5de4-432b-96eb-a8ae57259e","015c1298-5de4-432b-96eb-a8ae57259e"],"dl_action":"REMOVE","tracking_partner":"partner_name"}

GET- ADD
https://api-audience.kayzen.io/v1/au/listupdate?api_key=a6fe3455b78ce22d8481614ac2332f04ca198f&dl_action=ADD&dl_id=1234&dpid=”095c2198-5de4-432b-96eb-a8ae57259e","015c1298-5de4-432b-96eb-a8ae57259e”&tracking_partner=partner_name

GET- REMOVE

https://api-audience.kayzen.io/v1/au/listupdate?api_key=a6fe3455b78ce22d8481614ac2332f04ca198f&dl_action=REMOVE&dl_id=1234&dpid=”095c2198-5de4-432b-96eb-a8ae57259e","015c1298-5de4-432b-96eb-a8ae57259e&tracking_partner=partner_name

Error codes

200 - OK

400 - Bad request. Error in the API request.