Customer Lists

Customer Lists allow an advertiser to use first-party data to create an Audience Segment. The segment can be used to target or exclude a specific group of users.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
description	Audience Segment Description	O
name	Audience Segment name	R	375 characters max
retention_in_days	# of days to retain audience members	R	(Default retention is lifetime represented as 9999)
source_type	Data source type	R	FIRST_PARTY, ENGAGEMENT, PIXEL, MOBILE, FOOT_TRAFFIC_INSIGHTS
approximate_number_users	Approximate # of users in the segment	Read Only
status	Status of the segment	Read Only	ACTIVE
upload_status	Upload status of the segment	Read Only	NO_UPLOAD, PROCESSING, COMPLETE
targetable_status	Status of whether this segment can be targeted	Read Only	NOT_READY, TOO_FEW_USERS, READY

Create an Audience Segment

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"segments": [{"name": "all the sams in the world", "description": "all the sams in the world", "source_type": "FIRST_PARTY", "retention_in_days": 180, "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74"}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/segments"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57ae54d800ff0a4a5232b1a7210001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
  "segments": [
    {
      "sub_request_status": "success",
      "segment": {
        "updated_at": "2016-08-12T22:59:42.452Z",
        "created_at": "2016-08-12T22:59:42.405Z",
        "name": "all the sams in the world",
        "id": "5677923948298240",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "all the sams in the world",
        "status": "PENDING",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    }
  ]
}

This endpoint will create a Customer List segment within a specified ad account.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Segment Status

Upload Status	Description
NO_UPLOAD	Segment has been created but no uploads have been received yet
PROCESSING	Not all uploads to this segment have been processed so audience size might change
COMPLETE	All received uploads have been processed and matched. Audience size reflects segment size

Targetable Status	Description
NOT_READY	This segment won't work when used in targeting
TOO_FEW_USERS	This segment doesn't have enough users to target
READY	Segment is ready to target

Get All Audience Segments

curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57ae554a00ff0487459c8ac85c0001737e616473617069736300016275696c642d34363138393265642d312d31312d3200010103",
  "segments": [
    {
      "sub_request_status": "success",
      "segment": {
        "updated_at": "2016-08-12T21:11:01.325Z",
        "created_at": "2016-08-12T21:11:01.196Z",
        "name": "super duper sam 2",
        "id": "5689640350646272",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "all the sams in the world",
        "status": "PENDING",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    },
    {
      "sub_request_status": "success",
      "segment": {
        "updated_at": "2016-08-12T20:58:16.098Z",
        "created_at": "2016-08-12T20:58:16.036Z",
        "name": "super duper sam",
        "id": "5715031928864768",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "all the sams in the world",
        "status": "PENDING",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    }
  ]
}

This endpoint retrieves all Customer List segments within a specified ad account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get a specific Audience Segment

curl "https://adsapi.snapchat.com/v1/segments/{segment_id}"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5b3116c800ff0cfbb4758de4670001737e616473617069736300016275696c642d32636336303266382d312d3137382d300001015d",
  "segments": [
    {
      "sub_request_status": "SUCCESS",
      "segment": {
        "id": "5701023945457664",
        "updated_at": "2018-06-25T02:13:52.956Z",
        "created_at": "2018-03-09T00:57:57.462Z",
        "name": "Lookalike - Balance - hashed_emails_old_groupB",
        "ad_account_id": "3f539865-c001-4f5e-bd31-5ae129a4550a",
        "status": "ACTIVE",
        "targetable_status": "READY",
        "upload_status": "COMPLETE",
        "source_type": "LOOKALIKE",
        "retention_in_days": 180,
        "approximate_number_users": 11487000,
        "creation_spec": {
          "seed_segment_id": "5749764677173248",
          "country": "US",
          "type": "BALANCE"
        }
      }
    }
  ]
}

This endpoint retrieves the Snap Audience Segment with the corresponding segment id.

HTTP Request

GET https://adsapi.snapchat.com/v1/segments/{segment_id}

Parameters

Parameter	Default	Description
segment_id		Segment ID

Update an Audience Segment

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"segments":[{"id":"5603670370513719","name":"Honey Bear Segment 2019","organization_id":"1fdeefec-f502-4ca8-9a84-6411e0a51052","description":"A list of Honey bear lovers across the globe","retention_in_days":"60"}]}'
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/segments

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5dc3096800ff0c266ebe6eeaac0001737e616473617069736300016275696c642d65653836646631392d312d3330322d300001013a",
  "segments": [
    {
      "sub_request_status": "SUCCESS",
      "segment": {
        "id": "5603670370513719",
        "updated_at": "2019-11-06T17:56:57.053Z",
        "created_at": "2019-03-28T14:47:17.956Z",
        "name": "Honey Bear Segment 2019",
        "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
        "organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51052",
        "description": "A list of Honey bear lovers across the globe",
        "status": "PAUSED",
        "targetable_status": "TOO_FEW_USERS",
        "upload_status": "COMPLETE",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 60,
        "approximate_number_users": 500000,
        "visible_to": ["AdAccountEntity_22225ba6-7559-4000-9663-bace8adff5f1"]
      }
    }
  ]
}

This endpoint updates the Snap Audience Segment.

Attributes that can be updated

Attribute	Required
name	R
description	O
retention_in_days	R

HTTP Request

PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Adding Users

Users can be added to a segment at any time. The API supports matching via email, phone number or mobile identifier.

This endpoint will add users to the specified Customer List segment using either a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request, but this needs to happen via a LIST

Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.

Attributes

Attribute	Description	Required	Possible Values
id^	Segment ID	O
schema	List of one type of Schema	R	EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256
data	List of hashed identifiers	R	max 100,000 identifiers/request

^This field is here for legacy reasons and should be skipped for new implmentations

HTTP Request

POST https://adsapi.snapchat.com/v1/segments/{segment_id}/users

Parameters

Parameter	Default	Description
segment_id		Segment ID

Normalizing & Hashing

Each raw identifier (plain text email or mobile identifier) must be normalized before being hashed.

Normalizing Identifiers

Normalize email addresses by trimming leading and trailing whitespace and converting all characters to lowercase before hashing
Normalize mobile advertiser id by using all lowercase. Do not remove hyphens.
Normalize phone numbers by including the country code, remove any double 0 in front of the country code, if the number itself begins with a 0 this should be removed. Also exclude any non-numeric characters such as whitespace, parentheses, '+', or '-'.

Phone normalization example	Before normalization	After normalization	Action
US phone number example	001-234-567-8910	12345678910	00 of country code and '-' characters removed
UK phone number example	+44 844 412 4653	448444124653	Initial 0 of number, whitespaces and '+' character removed

Hashing Identifiers

Hash raw identifiers with lowercase hex SHA256 format.

Adding Users (Single-Key)

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"users":[{ "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}/users"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
  "users": [
    {
      "sub_request_status": "SUCCESS",
      "user": {
        "number_uploaded_users": 2
      }
    }
  ]
}

This example uses a single key/identifier per user.

Removing Users

Users can also be removed from the segment at any time. The API supports matching via email, phone number or mobile identifier. You can send a maximum of 100,000 identifiers / request.

This endpoint will remove users from the specified Customer List segment using a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request , but this needs to happen via a LIST.

Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.

Attributes

Attribute	Description	Required	Possible Values
id	Segment ID	R
schema	List of one type of Schema	R	EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256
data	List of hashed identifiers	R	max 100,000 identifiers/request

HTTP Request

DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/users

Parameters

Parameter	Default	Description
segment_id		Segment ID

Removing Users (Single-Key)

curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"users":[{"id": "5132209967071232", "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}/users"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
  "users": [
    {
      "sub_request_status": "SUCCESS",
      "user": {
        "number_uploaded_users": 2
      }
    }
  ]
}

This example uses a single key/identifier per user.

Remove All Users from a Segment

This endpoint allows you to remove all the users from a specified Customer List segment

HTTP Request

DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users

Parameters

Parameter	Default	Description
segment_id		Segment ID

Remove All Users

curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "58af318900ff0cb66aa3a103dd0001737e616473617069736300016275696c642d61666139346564352d312d34342d3000010109",
  "segments": [
    {
      "sub_request_status": "SUCCESS",
      "segment": {
        "id": "5769345128988888",
        "updated_at": "2017-02-23T19:01:30.080Z",
        "created_at": "2017-02-23T18:34:48.900Z",
        "name": "super duper sam",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d1111111d11",
        "description": "all the sams in the world",
        "status": "ACTIVE",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    }
  ]
}

Delete an Audience Segment

curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5b994e4900ff02dce52463d1020001737e616473617069736300016275696c642d33346634346232622d312d3230302d32000100",
  "segments": []
}

This endpoint will delete the Audience Segment with the corresponding segment id.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}

Parameters

Parameter	Default	Description
segment_id		Segment ID

Was this page helpful?

Yes

Attributes​

Create an Audience Segment​

HTTP Request​

Parameters​

Segment Status​

Get All Audience Segments​

HTTP Request​

Parameters​

Get a specific Audience Segment​

HTTP Request​

Parameters​

Update an Audience Segment​

Attributes that can be updated​

HTTP Request​

Parameters​

Adding Users​

Attributes​

HTTP Request​

Parameters​

Normalizing & Hashing​

Normalizing Identifiers​

Hashing Identifiers​

Adding Users (Single-Key)​

Removing Users​

Attributes​

HTTP Request​

Parameters​

Removing Users (Single-Key)​

Remove All Users from a Segment​

HTTP Request​

Parameters​

Remove All Users​

Delete an Audience Segment​

HTTP Request​

Parameters​

Attributes

Create an Audience Segment

HTTP Request

Parameters

Segment Status

Get All Audience Segments

HTTP Request

Parameters

Get a specific Audience Segment

HTTP Request

Parameters

Update an Audience Segment

Attributes that can be updated

HTTP Request

Parameters

Adding Users

Attributes

HTTP Request

Parameters

Normalizing & Hashing

Normalizing Identifiers

Hashing Identifiers

Adding Users (Single-Key)

Removing Users

Attributes

HTTP Request

Parameters

Removing Users (Single-Key)

Remove All Users from a Segment

HTTP Request

Parameters

Remove All Users

Delete an Audience Segment

HTTP Request

Parameters