Create or update a contact
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"), Headers = { { "Authorization", "Bearer <token>" }, }, Content = new StringContent("{ \"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 } }") { 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';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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}}'};
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 \ --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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”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 }}Responses
Section titled “Responses”The contact as stored, and whether it was created
object
true when the call worked, false when errors say why it did not.
The answer itself; null when the call failed.
object
The contact as it is now.
object
Azimea’s id for this contact.
The connected store the contact comes from; null for contacts your own systems made (the API or an import).
The contact’s email address.
First name.
Last name.
Phone number, as it was given.
City.
Two-letter country code (ISO 3166-1), such as GB.
What Azimea may send this person. See the consent statuses catalog for what each value allows.
true once the person has a paid order.
How many orders Azimea has recorded for them.
How much they have spent in total, from their orders.
When they last ordered; null if they never did.
When the person was created in their store; null for contacts that do not come from a store.
When Azimea last updated this contact from the store; null for contacts that do not come from a store.
true when they bought without a store account: known from orders only, missing from the store’s customer list.
Where the consent basis comes from, such as store_import, store_purchase, signup_form or api.
When the consent status last changed.
How the connected store collects consent: Explicit, Notice, OwnConsent or None. null until it is chosen.
true once the store has declared how it collects consent. Until then no marketing goes to anyone in it.
Free-form labels, added by a flow’s Tag step. Flows and segments can filter on them.
Your own fields, by key. Each value is stored as its field’s type.
object
When the person last opened an email. A mail privacy feature or a link scanner opening it does not count.
When the person last clicked a link. A scanner clicking does not count.
When the last campaign, flow or cart email went out to them.
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.
When the contact came into Azimea. What “new contacts” counts from.
When they last did something your company counts as a conversion.
true when the contact was created by this call, false when an existing one was updated.
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": { "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
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
Audience.contact_not_found: the id sent belongs to no contact
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
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