Skip to content
AzimeaDocs
Dashboard

Create or update contacts in bulk

POST
/contacts/batch
curl --request POST \
--url https://api.azimea.com/v1/contacts/batch \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "contacts": [ { "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 } }, { "id": null, "externalId": null, "email": "not-an-address", "firstName": null, "lastName": null, "phone": null, "city": null, "countryCode": null, "language": null, "attributes": null, "consent": null, "topics": null } ] }'

Up to 1,000 contacts in one call, each written exactly as POST /contacts would and each refused on its own: one invalid contact does not stop the others. The answer lists every contact in the order sent, with its status (Created, Updated or Failed), its id or its errors (code, field, params), and the totals. More than 1,000 is refused with audience.batch_too_large. The whole batch counts as one call for the rate limit. Needs contacts:write.

Media typeapplication/json
object
contacts
required

The contacts to write, up to 1,000. Each is written exactly as POST /contacts would write it.

Array<object>
>= 1 characters
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
}
}
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
}
},
{
"id": null,
"externalId": null,
"email": "not-an-address",
"firstName": null,
"lastName": null,
"phone": null,
"city": null,
"countryCode": null,
"language": null,
"attributes": null,
"consent": null,
"topics": null
}
]
Example
{
"contacts": [
{
"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
}
},
{
"id": null,
"externalId": null,
"email": "not-an-address",
"firstName": null,
"lastName": null,
"phone": null,
"city": null,
"countryCode": null,
"language": null,
"attributes": null,
"consent": null,
"topics": null
}
]
}

Totals and one result per contact, in the order sent

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
created

How many contacts were created.

integer format: int32
updated

How many existing contacts were updated.

integer format: int32
failed

How many contacts were refused. The others were still written.

integer format: int32
results

One entry per contact, in the order you sent them.

Array<object>
object
index

The contact’s position in your request, starting at 0.

integer format: int32
status

Created, Updated or Failed.

string
Allowed values: Created Updated Failed
id

The contact’s Azimea id; null when it failed.

string format: guid
nullable
errors

Why the contact was refused; null when it was written.

Array<object>
nullable
object
code

A stable error code, listed in the error codes catalog.

string
field

The request field the problem is about; null when it is about the whole contact.

string
nullable
params

The numbers the code refers to (a minimum, a maximum), when there are any.

object
key
additional properties
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": {
"created": 1,
"updated": 0,
"failed": 1,
"results": [
{
"index": 0,
"status": "Created",
"id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
"errors": null
},
{
"index": 1,
"status": "Failed",
"id": null,
"errors": [
{
"code": "validation.email",
"field": "Email",
"params": null
}
]
}
]
},
"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

Too many requests for this key