PIpinterest
customer_lists

Create customer lists

Changed on

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

Request

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
}

Changes

  • v5b698c180678aRevision changes
    • breaking

      the request property type changed from string to no type

    • breaking

      the response's property type changed from string to no type for status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property became optional

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      the response optional property became read-only for the status

    • info

      added to the response property allOf list for the response status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      removed the PROCESSING enum value from the response property for the response status

    • info

      removed the READY enum value from the response property for the response status

    • info

      removed the TOO_SMALL enum value from the response property for the response status

    • info

      removed the UPLOADING enum value from the response property for the response status

    • info

      the response's property pattern ^\d+$ was added for the status

    • info

      added the success response with the status

  • v510f9eba4ad97Revision changes
    • warning

      removed the request property