Sign in

v29

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-06-042661,1122.5 MB
customer_lists

Create customer lists

Create a customer list from your records (hashed or plain-text email addresses, or hashed MAIDs or IDFAs).

A customer list is one of the four types of Pinterest audiences: for more information, see Audience targeting or the Audiences section of the ads management guide.

Please review our requirements for what type of information is allowed when uploading a customer list.

When you create a customer list, the system scans the list for existing Pinterest accounts; the list must include at least 100 Pinterest accounts. Your original list will be deleted when the matching process is complete. The filtered list – containing only the Pinterest accounts that were included in your starting list – is what will be used to create the audience.

To use your customer list after creating it, convert it into a customer list audience by passing the CUSTOMER_LIST audience type at the create audience endpoint.

post/ad_accounts/{ad_account_id}/customer_lists

Path parameters

ad_account_idstring required

Request body

is_ncaboolean

Whether the list was uploaded for new customer acquisition (expanded matching). Immutable after creation.

list_type'EMAIL' | 'IDFA' | 'MAID' | 'LR_ID' | 'DLX_ID' | 'HASHED_PINNER_ID'

User list type

namestring required

Customer list name.

recordsstring

Records list. Can be any combination of emails, MAIDs, or IDFAs. Emails must be lowercase and can be plain text or hashed using SHA1, SHA256, or MD5. MAIDs and IDFAs must be hashed with SHA1, SHA256, or MD5.

Example request

{
  "list_type": "EMAIL",
  "name": "The Glengarry Glen Ross leads",
  "records": "email1@pinterest.com,email2@pinterest.com,..<more records>"
}

Response

The request has succeeded.

ad_account_idstring

Associated ad account ID.

created_timenumber

Creation time. Unix timestamp in seconds.

exceptionsobject

Customer list errors.

idstring required

Customer list ID.

is_ncaboolean

Whether the list was uploaded for new customer acquisition (expanded matching). Immutable after creation.

namestring required

Customer list name.

num_batchesnumber

Total number of list updates. List creation counts as one batch. Each Append or Remove API call counts as another. List creation via the Ads Manager UI could result in more than one batch since the UI breaks up large lists.

num_removed_user_recordsnumber

Number of removed user records. In a Remove API call, this counter increases even if the user is not found in the list.

num_uploaded_user_recordsnumber

Number of uploaded user records. In an Append API call, this counter increases even if the uploaded user is already in the list.

status'PROCESSING' | 'READY' | 'TOO_SMALL' | 'UPLOADING'

Customer list status. TOO_SMALL means the list has fewer than 100 Pinterest users.

typestring

Always customerlist.

updated_timenumber

Last update time. Unix timestamp in seconds.

Example response

{
  "ad_account_id": "549756359984",
  "created_time": 1452208622,
  "id": "643",
  "name": "The Glengarry Glen Ross leads",
  "num_batches": 2,
  "num_uploaded_user_records": 11,
  "status": "PROCESSING",
  "type": "customerlist",
  "updated_time": 1461269616
}