Skip to main content
POST
Create a contact

Authorizations

Authorization
string
header
required

An API key (utk_live_...) or an app's OAuth access token (uto_...).

Headers

Idempotency-Key
string

Any 1 to 255 printable ASCII characters, without a space at either end. The answer to the first request with a key is kept for 24 hours per credential: the same request again gets it back (Idempotent-Replayed: true), another request with the key is 409 PUB-002-002, and while the first still runs 409 PUB-002-003. A server error is not kept, and a request that never answered frees its key after 2 minutes: a retry with the key then runs again.

Maximum string length: 255

Body

application/json
email
string<email>
required

The address; stored lowercased.

Maximum string length: 320
name
string | null
Maximum string length: 120
attributes
object | null

Text details, each a name of up to 64 characters and a text value of up to 500, at most 128 KB in all. A list or a nested object is refused (CNT-001-010).

externalId
string | null

Your own user id for the person, unique in the organization.

Maximum string length: 256
listIds
string<uuid>[] | null

Lists to put the contact on, at most 100. Ids that aren't the organization's lists are skipped.

Maximum array length: 100

Response

Created.

id
string<uuid>
required
email
string<email>
required

The address, lowercased. It never changes.

name
string | null
required
attributes
object
required

Text details, each a name of up to 64 characters and a text value of up to 500; {} when there are none.

externalId
string | null
required

Your own user id for the person (what identify sends); unique in the organization.

source
string | null
required

What made the contact when no person added it: identify (a verified identity with an email) or hubspot (a HubSpot workflow action). Null for one added in Usertick, by import or through the API.

unsubscribedAt
string<date-time> | null
required

When the contact unsubscribed (or was unsubscribed); null while subscribed. A contact is never subscribed again.

Example:

"2026-09-30T10:00:00.000Z"

listIds
string<uuid>[]
required

The lists the contact is on.

createdAt
string<date-time>
required
Example:

"2026-09-30T10:00:00.000Z"

updatedAt
string<date-time> | null
required
Example:

"2026-09-30T10:00:00.000Z"

Last modified on November 8, 2026