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.

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.

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

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

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

 

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

 

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

{
"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: