Skip to main content
POST
Create Engage list

Authorizations

Authorization
string
header
required

Partner OAuth2 flows for integration API access tokens. Claude MCP custom connectors use authorization code with PKCE S256.

Scopes

engage.lists:write

Create and update engagement lists and members.

Headers

X-Organization-Id
string<uuid>

Active organization UUID. Required for authenticated requests when the principal has access to multiple organizations.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Query Parameters

organizationId
string<uuid>

Read-only convenience alias for X-Organization-Id. Legacy subscriberId query param is also accepted.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Body

application/json
name
string
required
Required string length: 1 - 300
description
string
sourceType
enum<string>
Available options:
manual,
persona,
account
accountId
string<uuid>
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
ownerUserId
string<uuid>

Organization user that owns the list. Required for client-credential tokens; user tokens default to the authenticated user.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
contactIds
string<uuid>[]
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
externalContacts
object[]
accountIds
string<uuid>[]
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
accountTypes
string[]
accountStatuses
string[]
accountRelationshipStatuses
string[]
contactTags
string[]

Contact-level filter matching any selected contact tag (case-insensitive). Combined with other dynamic criteria using dynamicFilterOperator. Send an empty array to clear.

accountTags
string[]
accountTagCategories
string[]

Account-level filter: tag category keys from the organization account_types.tag_category_map.

engagementStatuses
string[]

Contact-level filter on relationship-map contact_status (e.g. Contacted, Not Contacted, Actively Engaged, Ghosting). Always AND’d with account filters.

requireFirstDegreeConnection
boolean

When true, only contacts who are LinkedIn 1st-degree connections of the list owner (from cached linkedin_relations) are included. Always AND’d with other filters.

accountOwnerIds
string<uuid>[]
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
sourcePersona
string[]
dynamicFilterOperator
enum<string>
default:and
Available options:
and,
or

Response

Created list.

list
object
required