--- title: "Create customer lists" method: POST path: "/ad_accounts/{ad_account_id}/customer_lists" tags: ["customer_lists"] --- # Create customer lists `POST /ad_accounts/{ad_account_id}/customer_lists` ## Request - Base URL: `https://api.pinterest.com/v5` - URL: `https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/customer_lists` - Auth: OAuth 2 - Authorization code: `https://www.pinterest.com/oauth/` - Token URL: `https://api.pinterest.com/v5/oauth/token` scopes: `ads:write` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](https://help.pinterest.com/en/business/article/audience-targeting) or the [Audiences](/docs/api-features/targeting-overview/) section of the ads management guide. **Please review our [requirements](https://help.pinterest.com/en/business/article/audience-targeting#section-13341) 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](https://developer.pinterest.com/docs/api/v5/audiences-create). ## Path parameters - `ad_account_id` string, required ## Request body - CustomerListCreate: Resource create operation model. - `is_nca` boolean: 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 - `name` string, required: Customer list name. - `records` string: 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. - `records_v2` CustomerListRecordRow[]: Multi-field record format. Array of objects with optional email, maid, ip_address, user_agent, external_id, hashed_pinner_id, hashed_phone_number, and liveramp_envelope per row. Provide exactly one of records or records_v2. - `email` string: Email address (plain or hashed with SHA1, SHA256, or MD5). - `external_id` string: External ID identifier (not hashed). - `hashed_phone_number` string: Hashed phone number (hashed with SHA1, SHA256, or MD5). - `hashed_pinner_id` string: Hashed pinner ID (hashed with SHA1, SHA256, or MD5). - `ip_address` string: IP address (not hashed). - `liveramp_envelope` string: LiveRamp envelope identifier (Base64-encoded, not hashed). - `maid` string: Mobile advertising ID (plain or hashed with SHA1, SHA256, or MD5). - `user_agent` string: User agent string (not hashed). ## Response `200` The request has succeeded. - CustomerList - `ad_account_id` string: Associated ad account ID. - `created_time` number: Creation time. Unix timestamp in seconds. - `exceptions` object: Customer list errors. - `id` string, required: Customer list ID. - `is_nca` boolean: Whether the list was uploaded for new customer acquisition (expanded matching). Immutable after creation. - `name` string, required: Customer list name. - `num_batches` number: Total number of list updates. List creation counts as one batch. Each [Append](/docs/redoc/#operation/ads_v3_customer_list_add_handler_PUT) or [Remove API](/docs/redoc/#operation/ads_v3_customer_list_remove_handler_PUT) 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_records` number: Number of removed user records. In a [Remove API](/docs/redoc/#operation/ads_v3_customer_list_remove_handler_PUT) call, this counter increases even if the user is not found in the list. - `num_uploaded_user_records` number: Number of uploaded user records. In an [Append API](/docs/redoc/#operation/ads_v3_customer_list_add_handler_PUT) 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. - `type` string: Always `customerlist`. - `updated_time` number: Last update time. Unix timestamp in seconds. ## Other responses - `201`: Resource create operation completed successfully. - `400`: The request could not be understood by the server due to unexpected data. - `401`: Authentication is required and has either failed or not been provided. - `403`: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. - `404`: The requested resource could not be found on this server. - `429`: The user has sent too many requests in a given amount of time and is being rate limited. - `default`: An unexpected error response. ## Changes - **2026-06-04** (v5) `b698c180678a`: 2 breaking, 28 info - the `list_type` request property type changed from `string` to no type - the `status` response's property type changed from `string` to no type for status `200` - added the new optional request property `is_nca` - added the new optional request property `records_v2` - …26 more - **2025-04-04** (v5) `10f9eba4ad97`: 1 warning - removed the request property `exceptions` - **2022-11-14** (v5) `e041d7b0cef0`: 1 breaking - for the `path` request parameter `ad_account_id`, the maxLength was decreased from `19` to `18` - **2022-09-07** (v5) `bd20b6eb152f`: 1 info - endpoint added [Operation history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/ad_accounts/:ad_account_id/customer_lists/post.md) --- [API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) - [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pinterest/apis/pinterest-rest-api/revisions/b698c180678a?raw)