Skip to main content
POST
curl
Phone numbers. A number that starts with + and a country code keeps that country. A Korean mobile number without a country code, such as 010-2938-4756, is saved as a Korean (+82) number. There is no country field, so write numbers from other countries with their + country code. First seen date. Send firstSeenAt (RFC 3339, not in the future, 2000-01-01 or later) to set the date the contact is shown as first seen, for example the day the person joined your service. It applies to a new contact and to an existing one, and it replaces the stored date every time you send it. Leave it out to keep the date as it is.

Authorizations

Authorization
string
header
required

A key generated from Settings → Developers, sent as Authorization: Bearer dr_live_<12 hex chars>_<64 hex chars>. Keys carry explicit scopes — each endpoint states the one it requires. The full key is shown exactly once at generation time and cannot be retrieved again; only the keyId prefix is shown afterward. A revoked key fails auth on its very next request.

Headers

Idempotency-Key
string
required

A unique client-generated string (≤ 255 characters) identifying this attempt. See "Idempotency" above.

Maximum string length: 255

Body

application/json
email
string
required

The contact's email address. Surrounding spaces are removed and letters lower-cased; it must be a plain ASCII address.

Maximum string length: 320
Example:

"person@example.com"

name
string | null

Replaces the stored name when non-empty. Omitted, null or empty leaves it alone.

Maximum string length: 200
Example:

"Ada Lee"

company
string | null

Replaces the stored company when non-empty. Omitted, null or empty leaves it alone.

Maximum string length: 200
Example:

"Example Inc"

phone
string | null

Replaces the stored phone when non-empty. A number that starts with + and a country code keeps that country. A Korean mobile number without a country code, such as 010-2938-4756, is saved as a Korean (+82) number; there is no country field, so write any other country's number with its + country code. A number that cannot be parsed is kept as you sent it. Omitted, null or empty leaves it alone.

Maximum string length: 32
Example:

"+82 10 2938 4756"

firstSeenAt
string<date-time>

The date the contact is shown as first seen, for example the day the person joined your service: RFC 3339 with an offset or Z, not in the future, 2000-01-01 or later. Replaces the stored date for a new and for an existing contact. Omitted leaves it alone (a new contact then gets the time of this call).

Example:

"2025-12-24T01:02:03Z"

tags
string[]

Names of tags you already have, at most 10. Any name that does not exist is 422 TAG_NOT_FOUND and nothing is written.

Maximum array length: 10
Example:

A marketing consent you collected. Omit it to give none.

Response

The contact already existed and was updated with what you sent (created: false).

id
string<uuid>
required

The contact's id.

email
string
required

The address as stored (trimmed, lower-cased).

created
boolean
required

true if this call created the contact, false if it already existed.

The marketing consent the contact has now. false after you sent marketing: true means it was not applied (the contact had unsubscribed or its address is suppressed).

tags
string[]
required

The tags this call applied, by stored name. Each one is on the contact now.