Audience List API

This post is also available in:

By using this API you can manage your Audience Lists programmatically.

You can:

list all of your Audience Lists
export all the data from your Audience List
create new Audience List
add new contacts to the Audience List
delete specific contacts from the Audience List
delete all content of the Audience List
archive/unarchive Audience List

General type of errors can be found here.

Endpoint URL

Depending on your account, select the appropriate endpoint URL.

If you are logging in at app.samba.ai –> choose the URL api.samba.ai
If you are logging in at enterprise.samba.ai –> choose the URL api.yottly.com

Your account ID can be found in the Settings section as part of your unique tracking script.

list

You can retrieve the entire list of all Audience Lists from your shop.

Method: GET

URI: https://api.samba.ai/shop/sambaId/audience-lists/list
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account

Query parameters:

archived – boolean
- true – only archived audience lists are returned
- false – only active audience lists are returned
- missing – all audience lists are returned

Response

JSON format – stream, one JSON object per line in this form

{"id": <uuid>, "name": <name>, "kind": <kind>, "archived": <boolean>, "createdAt": <milliseconds>, "size": <int>, "revision": <int>}

id – uuid of the audience list
name – name of the audience list
kind – type of the audience list, customerId or email
archived – true/false
createdAt – timestamp when the audience list was created
size – number of records in the audience list
revision – how many edits of the audience lists were made before

If no audience list exists nothing is returned.

ID of the Audience List

The endpoint /list returns the uuid of audience lists, which is necessary as input for manipulating audience lists using other endpoints. ID of the audience list can be also found in Samba.ai UI.

Example

curl 'http://api.samba.ai/shop/12345/audience-lists/list?archived=false'--header 'x-api-key: key'

{"id":"e09baf21-fd61-4f8a-8d83-6b2af2c2310d","name":"Audience list 1","kind":"email","archived":false,"createdAt":1650994318800,"createdBy":"user1@samba.ai","size":12345,"revision":5}
{"id":"9ec24dfe-cd29-4dea-a9b6-c145d3c8b537","name":"Audience list 2","kind":"customerId","archived":false,"createdAt":1726746967269,"createdBy":"user1@samba.ai","size":123,revision":1}
{"id":"a015df4b-47a1-40a3-b745-244e0e1f352b","name":"Audience list 3","kind":"email","archived":false,"createdAt":1726746958642,"createdBy":"user2@samba.ai","size":1234,"revision":1}

export

Returns all the data from selected Audience List.

Method: GET

URI: https://api.samba.ai/shop/sambaId/audience-lists/export/<uuid>
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account
<uuid> – ID of the audience list

Response

email/customerId – customer e-mail/customer ID

Each line contains one e-mail/customerId based on the kind of the Audience List.

Example

curl 'https://api.samba.ai/shop/12345/audience-lists/export/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'

--header'x-api-key: key'

"user1@samba.ai"
"user2@samba.ai"

create-new

This allows you to create a new Audience List.

Method: POST

URI: https://api.samba.ai/shop/sambaId/audience-lists/create-new
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account

Query parameters:

name
createdBy
kind ("email" or "customerId")

Body:

content-type: multipart/form-data
In the body there must be a part called “csv”, where the content = each line has a single e-mail/customerId, based on the kind of the Audience List.

Response

JSON format – statistics

{"id": <uuid>, "statistics": {"added": <int>, "invalid": <int>, "skipped": <int>, "duplicated": <int>}}

added – number on added contacts
invalid – number of invalid contacts
skipped – number of contacts that were already in the audience list
duplicated – number of contacts there were more than once in the csv file

In case of failure, ProblemDetails with one of the following codes is returned:

Unknown kind of the Audience List – 422
Exceeding the size limit of a single list – 409
Exceeding the size limit of all the lists – 409

Example

curl 'https://api.samba.ai/shop/12345/audience-lists/create-new?name=API-testing-create&createdBy=user1%40samba.ai&kind=email'

--header 'x-api-key: your-api-key'

--form 'csv=@"abcdefgh/API-testing-audience-list.csv"'

{"id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
"statistics": {
"added": 2,
"invalid": 1,
"skipped": 3,
"duplicated": 1}}

add-contacts

Allows you to add new contacts to an existing Audience List

Method: POST

URI: https://api.samba.ai/shop/sambaId/audience-lists/add-contacts/<uuid>
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account
<uuid> – ID of the audience list

Body:

content-type: multipart/form-data
In the body there must be a part called “csv“, where the content = each line has a single e-mail/customerId, based on the kind of the Audience List.

Response

JSON format – statistics

{"id": <uuid>, "statistics": {"added": <int>, "invalid": <int>, "skipped": <int>, "duplicated": <int>}}

added – number on added contacts
invalid – number of invalid contacts
skipped – number of contacts that were already in the audience list
duplicated – number of contacts there were more than once in the csv file

In case of failure, ProblemDetails with one of the following codes is returned:

Audience List not found – 404
Exceeding the size limit of a single list – 409
Exceeding the size limit of all the list – 409

Example

curl 'https://api.samba.ai/shop/12345/audience-lists/add-contacts/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'

--header 'x-api-key: key'

--form 'csv=@"abcdefgh/API-testing-audience-list2.csv"'

delete-specific

Allows you to remove selected contacts from the Audience List.

Method: POST

URI: https://api.samba.ai/shop/sambaId/audience-lists/delete-specific/<uuid>
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account
<uuid> – ID of the audience list

Body:

content-type – multipart/form-data
In the body there must be a part called “csv“, where the content = each line has a single e-mail/customerId, based on the kind of the Audience List.

Response

JSON format – statistics

{"statistics": {"deleted": <int>, "invalid": <int>, "skipped": <int>, "duplicated": <int>}}

deleted – number on deleted contacts
invalid – number of invalid contacts
skipped – number of contacts that were already in the audience list
duplicated – number of contacts there were more than once in the csv file

In case of failure, ProblemDetails with one of the following codes is returned:

Audience List not found – 404

Example

curl 'https://api.samba.ai/shop/12345/audience-lists/delete-specific/f81d4fae-7dec-11d0-a765-00a0c91e6bf6' \

--header 'x-api-key: key' \

--form 'csv=@"abcdefgh/API-testing-audience-list.csv"'

{
"statistics": {
"deleted": 2,
"invalid": 0,
"skipped": 0,
"duplicated": 0}
}

delete-content

Allows you to delete all contents of the Audience List

Method: DELETE

URI: https://api.samba.ai/shop/sambaId/audience-lists/delete-specific/<uuid>
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account
<uuid> – ID of the audience list

Response

JSON format – statistics

{"statistics": {"deleted": <int>, "invalid": <int>, "skipped": <int>, "duplicated": <int>}}

deleted – number on deleted contacts
invalid – number of invalid contacts
skipped – number of contacts that were already in the audience list
duplicated – number of contacts there were more than once in the csv file

In case of failure, ProblemDetails with one of the following codes is returned:

Audience List not found – 404

Example

curl --request DELETE 'https://api.samba.ai/shop/12345/audience-lists/delete-content/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'

--header 'x-api-key: key'

--form 'csv=@"abcdefgh/API-testing-audience.csv"'

{
"statistics": {
"deleted": 3,
"invalid": 1,
"skipped": 0,
"duplicated": 0}
}

set-archived

This allows you to archive or unarchive an Audience List.

Method: POST

URI: https://api.samba.ai/shop/sambaId/audience-lists/set-archived/<uuid>
Headers: X-Api-Key: your-api-key

sambaId – Samba ID of your account
your-api-key – Samba API key for your account
<uuid> – ID of the audience list

Query parameters:

archived – true (to archive) or false (to unarchive)

Response

If the list was archived and you used “<uuid>?archived=false“, this list is now unarchived.

If the list was not archived and you used “<uuid>?archived=true“, this list is now archived.

Example

curl --request POST 'https://api.samba.ai/shop/12345/audience-lists/set-archived/f81d4fae-7dec-11d0-a765-00a0c91e6bf6?archived=true' --header 'x-api-key: key'

This post is also available in:

Updated on June 11, 2025

Was this article helpful?

Yes No

list

Response

Example

export

Response

Example

create-new

Response

Example

add-contacts

Response

Example

delete-specific

Response

Example

delete-content

Response

Example

set-archived

Response

Example

Was this article helpful?

Related Articles