Skip to navigation

Create Contact List

Creates a List (static_list) and, optionally, adds contacts to it. You cannot create a View with this API.

Adding the initial contacts is not atomic with creating the List. The List is created first. Then the contacts are added. membership_result shows the result for the contacts: contacts that were invalid or whose write failed are listed by URI. To retry failed contacts, send them to Add Contacts to Static List. That operation is idempotent.

A List name that is taken returns 409. The name match ignores case, accents, and leading and trailing spaces. The limit is 25 Lists and Views for each user, including Views that a CSV import creates.

If the request returns a 500 error or times out, the List may still exist. Before you retry, use List Contact Lists to check for the List. Then send any missing contacts to Add Contacts to Static List, which is safe to repeat. A retry of this request with the same name returns 409.

Required scopes

contacts:write

Authentication

AuthorizationBearer
OAuth 2.0
OR
AuthorizationBearer
Personal Access Token

Request

This endpoint expects an object.
namestringRequiredformat: "^\s*\S(?:[\s\S]{0,253}\S)?\s*$"
The name of the List. Leading and trailing whitespace is removed. The result must contain 1 to 255 characters. It must not match the name of another List. The match ignores case, accents, and leading and trailing spaces.
contactslist of stringsOptional
Contacts to add to the new List, as contact URIs. Maximum 500. A contact that appears more than once is added once.

Response headers

Locationstringformat: "uri"
Canonical URI of the created List.

Response

Created
resourceobject

The created static_list, with the result of adding the initial contacts.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error