Create or update contacts in bulk
using System.Net.Http.Headers;var client = new HttpClient();var request = new HttpRequestMessage{ Method = HttpMethod.Post, RequestUri = new Uri("https://api.azimea.com/v1/contacts/batch"), Headers = { { "Authorization", "Bearer <token>" }, }, Content = new StringContent("{ \"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 } ] }") { Headers = { ContentType = new MediaTypeHeaderValue("application/json") } }};using (var response = await client.SendAsync(request)){ response.EnsureSuccessStatusCode(); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine(body);}const url = 'https://api.azimea.com/v1/contacts/batch';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
The contacts to write, up to 1,000. Each is written exactly as POST /contacts would write it.
object
Azimea’s id, if you have it. A contact is looked up by id first, then by externalId, then by email.
Example
nullYour own id for this person (your user id). It is the best way to find them again, at most 64 characters.
Example
user_4821The email address. Required when the contact does not exist yet.
Example
emma.clarke@example.comFirst name, at most 100 characters. Left out, the current value stays.
Example
EmmaLast name. Left out, the current value stays.
Example
ClarkePhone number. Left out, the current value stays.
Example
+447700900123City. Left out, the current value stays.
Example
ManchesterTwo-letter country code (ISO 3166-1), such as GB.
Example
GBThe language they read: a code such as en, or a locale such as en_GB (read as en).
Example
enYour 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
Example
{ "plan": "pro", "seats": 12}What the person agreed to. Left out, their consent stays as it is.
object
Customer (an existing customer), Subscribed (they agreed to receive your emails, which needs proof) or Unsubscribed (they no longer want marketing).
Example
SubscribedRequired with Subscribed: the words they agreed to. It is kept in the person’s consent history.
object
The exact words the person agreed to, such as the checkbox label.
Example
Send me product news and offers from Notely.Your own label for that wording, such as 2, so you can tell which version they saw.
Example
2The language the text was shown in, such as en_GB.
Example
en_GBThe address they agreed from.
Example
203.0.113.7When they agreed. Now, when left out.
Example
2026-10-05T09:30:00+00:00Example
{ "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" }}The person’s topic choices: topic key → true or false. Read the keys from GET /topics.
object
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 } ]}Responses
Section titled “Responses”Totals and one result per contact, in the order sent
object
true when the call worked, false when errors say why it did not.
The answer itself; null when the call failed.
object
How many contacts were created.
How many existing contacts were updated.
How many contacts were refused. The others were still written.
One entry per contact, in the order you sent them.
object
The contact’s position in your request, starting at 0.
Created, Updated or Failed.
The contact’s Azimea id; null when it failed.
Why the contact was refused; null when it was written.
object
A stable error code, listed in the error codes catalog.
The request field the problem is about; null when it is about the whole contact.
The numbers the code refers to (a minimum, a maximum), when there are any.
object
An internal result number. Rely on the HTTP status code instead.
What went wrong, one entry per problem; empty when the call worked.
object
A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.
An English sentence for your logs. Do not show it to end users: it can change.
The numbers the message mentions (a minimum, a maximum), when there are any.
object
The same problems grouped by the request field they belong to; null when none is tied to a field.
object
object
A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.
An English sentence for your logs. Do not show it to end users: it can change.
The numbers the message mentions (a minimum, a maximum), when there are any.
object
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
object
true when the call worked, false when errors say why it did not.
The answer itself; null when the call failed.
An internal result number. Rely on the HTTP status code instead.
What went wrong, one entry per problem; empty when the call worked.
object
A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.
An English sentence for your logs. Do not show it to end users: it can change.
The numbers the message mentions (a minimum, a maximum), when there are any.
object
The same problems grouped by the request field they belong to; null when none is tied to a field.
object
object
A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.
An English sentence for your logs. Do not show it to end users: it can change.
The numbers the message mentions (a minimum, a maximum), when there are any.
object
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