Skip to content
AzimeaDocs
Dashboard

Create or update a contact

POST
/contacts
curl --request POST \
--url https://api.azimea.com/v1/contacts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "id": null, "externalId": "user_4821", "email": "emma.clarke@example.com", "firstName": "Emma", "lastName": "Clarke", "phone": "+447700900123", "city": "Manchester", "countryCode": "GB", "language": "en", "attributes": { "plan": "pro", "seats": 12 }, "consent": { "basis": "Subscribed", "proof": { "text": "Send me product news and offers from Notely.", "textVersion": "2", "locale": "en_GB", "ipAddress": "203.0.113.7", "givenAt": "2026-10-05T09:30:00+00:00" } }, "topics": { "product_news": true } }'

Writes one person from your own system. The contact is found by id, then externalId (your user id), then email, and created when none matches (an email is then required: audience.contact_email_required); a user id and an email that point at two different contacts are refused, never merged (409 audience.contact_identity_conflict). Fields left out stay as they are; attributes is a patch (a key sent is set, null removes it), and an unknown attribute key is created when the contact settings allow it, refused with audience.attribute_unknown otherwise. consent only moves up: Customer makes an existing customer, Subscribed needs proof.text (audience.consent_proof_required) and also brings back someone who unsubscribed, Unsubscribed stops marketing only; a bounce or a complaint is never lifted. topics turns topics on or off by key (topics.not_found, topics.archived). A store’s contact keeps the email, id and consent the store syncs (audience.contact_store_managed), except an unsubscribe, which is always honoured. A new contact counts toward the plan (audience.contact_limit_reached). Sending the same contact twice leaves it as the first call did, so retries are safe. Needs contacts:write.

Media typeapplication/json
object
id

Azimea’s id, if you have it. A contact is looked up by id first, then by externalId, then by email.

string format: guid
nullable
Example
null
externalId

Your own id for this person (your user id). It is the best way to find them again, at most 64 characters.

string
nullable 0 <= 64 characters
Example
user_4821
email

The email address. Required when the contact does not exist yet.

string
nullable
Example
emma.clarke@example.com
firstName

First name, at most 100 characters. Left out, the current value stays.

string
nullable 0 <= 100 characters
Example
Emma
lastName

Last name. Left out, the current value stays.

string
nullable 0 <= 100 characters
Example
Clarke
phone

Phone number. Left out, the current value stays.

string
nullable 0 <= 50 characters
Example
+447700900123
city

City. Left out, the current value stays.

string
nullable 0 <= 100 characters
Example
Manchester
countryCode

Two-letter country code (ISO 3166-1), such as GB.

string
nullable /^[A-Za-z]{2}$/
Example
GB
language

The language they read: a code such as en, or a locale such as en_GB (read as en).

string
nullable /^[A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})*$/
Example
en
attributes

Your custom fields, by key. A patch: a key you send is set, a key sent as null is removed, the others stay. Each key must be defined first.

object
key
additional properties
Example
{
"plan": "pro",
"seats": 12
}
consent

What the person agreed to. Left out, their consent stays as it is.

object
basis

Customer (an existing customer), Subscribed (they agreed to receive your emails, which needs proof) or Unsubscribed (they no longer want marketing).

string
Allowed values: Customer Subscribed Unsubscribed
Example
Subscribed
proof

Required with Subscribed: the words they agreed to. It is kept in the person’s consent history.

object
text

The exact words the person agreed to, such as the checkbox label.

string
nullable 0 <= 2000 characters
Example
Send me product news and offers from Notely.
textVersion

Your own label for that wording, such as 2, so you can tell which version they saw.

string
nullable 0 <= 64 characters
Example
2
locale

The language the text was shown in, such as en_GB.

string
nullable 0 <= 16 characters
Example
en_GB
ipAddress

The address they agreed from.

string
nullable
Example
203.0.113.7
givenAt

When they agreed. Now, when left out.

string format: date-time
nullable
Example
2026-10-05T09:30:00+00:00
Example
{
"text": "Send me product news and offers from Notely.",
"textVersion": "2",
"locale": "en_GB",
"ipAddress": "203.0.113.7",
"givenAt": "2026-10-05T09:30:00+00:00"
}
Example
{
"basis": "Subscribed",
"proof": {
"text": "Send me product news and offers from Notely.",
"textVersion": "2",
"locale": "en_GB",
"ipAddress": "203.0.113.7",
"givenAt": "2026-10-05T09:30:00+00:00"
}
}
topics

The person’s topic choices: topic key → true or false. Read the keys from GET /topics.

object
key
additional properties
boolean
Example
{
"product_news": true
}
Example
{
"id": null,
"externalId": "user_4821",
"email": "emma.clarke@example.com",
"firstName": "Emma",
"lastName": "Clarke",
"phone": "+447700900123",
"city": "Manchester",
"countryCode": "GB",
"language": "en",
"attributes": {
"plan": "pro",
"seats": 12
},
"consent": {
"basis": "Subscribed",
"proof": {
"text": "Send me product news and offers from Notely.",
"textVersion": "2",
"locale": "en_GB",
"ipAddress": "203.0.113.7",
"givenAt": "2026-10-05T09:30:00+00:00"
}
},
"topics": {
"product_news": true
}
}

The contact as stored, and whether it was created

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

object
contact

The contact as it is now.

object
id

Azimea’s id for this contact.

string format: guid
storeId

The connected store the contact comes from; null for contacts your own systems made (the API or an import).

string format: guid
nullable
email

The contact’s email address.

string
firstName

First name.

string
nullable
lastName

Last name.

string
nullable
phone

Phone number, as it was given.

string
nullable
city

City.

string
nullable
countryCode

Two-letter country code (ISO 3166-1), such as GB.

string
nullable
consentStatus

What Azimea may send this person. See the consent statuses catalog for what each value allows.

string
Allowed values: Unknown SoftOptIn Subscribed Unsubscribed Bounced Complained CheckoutStarted PendingConfirmation
isPayingCustomer

true once the person has a paid order.

boolean
orderCount

How many orders Azimea has recorded for them.

integer format: int32
totalSpent

How much they have spent in total, from their orders.

number format: decimal
lastOrderAt

When they last ordered; null if they never did.

string format: date-time
nullable
sourceCreatedAt

When the person was created in their store; null for contacts that do not come from a store.

string format: date-time
nullable
lastSyncedAt

When Azimea last updated this contact from the store; null for contacts that do not come from a store.

string format: date-time
nullable
fromOrders

true when they bought without a store account: known from orders only, missing from the store’s customer list.

boolean
consentSource

Where the consent basis comes from, such as store_import, store_purchase, signup_form or api.

string
nullable
consentUpdatedAt

When the consent status last changed.

string format: date-time
nullable
storeConsentMode

How the connected store collects consent: Explicit, Notice, OwnConsent or None. null until it is chosen.

string
nullable
Allowed values: Explicit Notice OwnConsent None
marketingDeclared

true once the store has declared how it collects consent. Until then no marketing goes to anyone in it.

boolean
tags

Free-form labels, added by a flow’s Tag step. Flows and segments can filter on them.

Array<string>
nullable
attributes

Your own fields, by key. Each value is stored as its field’s type.

object
key
additional properties
lastOpenAt

When the person last opened an email. A mail privacy feature or a link scanner opening it does not count.

string format: date-time
nullable
lastClickAt

When the person last clicked a link. A scanner clicking does not count.

string format: date-time
nullable
lastEmailedAt

When the last campaign, flow or cart email went out to them.

string format: date-time
nullable
language

The language they read, as a lowercase two-letter code (en, ro). It picks the language version of a campaign they get; null when not known.

string
nullable
addedAt

When the contact came into Azimea. What “new contacts” counts from.

string format: date-time
nullable
lastConversionAt

When they last did something your company counts as a conversion.

string format: date-time
nullable
created

true when the contact was created by this call, false when an existing one was updated.

boolean
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": true,
"value": {
"contact": {
"id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
"storeId": null,
"email": "emma.clarke@example.com",
"firstName": "Emma",
"lastName": "Clarke",
"phone": "+447700900123",
"city": "Manchester",
"countryCode": "GB",
"consentStatus": "Subscribed",
"isPayingCustomer": false,
"orderCount": 0,
"totalSpent": 0,
"lastOrderAt": null,
"sourceCreatedAt": null,
"lastSyncedAt": null,
"fromOrders": false,
"consentSource": "api",
"consentUpdatedAt": "2026-10-05T09:30:00+00:00",
"storeConsentMode": null,
"marketingDeclared": false,
"tags": [
"trial"
],
"attributes": {
"plan": "pro",
"seats": 12
},
"lastOpenAt": null,
"lastClickAt": null,
"lastEmailedAt": null,
"language": "en",
"addedAt": "2026-10-05T09:30:00+00:00",
"lastConversionAt": null
},
"created": true
},
"status": 0,
"errors": [],
"fieldErrors": null
}

Validation failed: see errors[].code and fieldErrors

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": false,
"value": null,
"status": 5,
"errors": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
],
"fieldErrors": {
"email": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
]
}
}

Missing or invalid API key

The key lacks the contacts:write permission

Audience.contact_not_found: the id sent belongs to no contact

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Examplegenerated
{
"isSuccess": true,
"value": "example",
"status": 1,
"errors": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
],
"fieldErrors": {
"additionalProperty": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
]
}
}

Too many requests for this key