Skip to content
Azimea Docs

Create or update a contact

POST
/api/v1/contacts
curl --request POST \
  --url https://dashboard.azimea.com/api/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": null, "externalId": "user_4821", "email": "ana.popescu@example.com", "firstName": "Ana", "lastName": "Popescu", "phone": "+40721000000", "city": "Cluj-Napoca", "countryCode": "RO", "language": "ro", "attributes": { "plan": "pro", "seats": 12 }, "consent": { "basis": "Subscribed", "proof": { "text": "Send me product news and offers from Notely.", "textVersion": "2", "locale": "ro_RO", "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”
Media typeapplication/json
object
id
string format: guid
nullable
Example
null
externalId
string
nullable 0 <= 64 characters
Example
user_4821
email
string
nullable
Example
ana.popescu@example.com
firstName
string
nullable 0 <= 100 characters
Example
Ana
lastName
string
nullable 0 <= 100 characters
Example
Popescu
phone
string
nullable 0 <= 50 characters
Example
+40721000000
city
string
nullable 0 <= 100 characters
Example
Cluj-Napoca
countryCode
string
nullable /^[A-Za-z]{2}$/
Example
RO
language
string
nullable /^[A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})*$/
Example
ro
attributes
object
key
additional properties
Example
{
  "plan": "pro",
  "seats": 12
}
consent
One of:
object
basis
string
Allowed values: Customer Subscribed Unsubscribed
Example
Subscribed
proof
One of:
object
text
string
nullable 0 <= 2000 characters
Example
Send me product news and offers from Notely.
textVersion
string
nullable 0 <= 64 characters
Example
2
locale
string
nullable 0 <= 16 characters
Example
ro_RO
ipAddress
string
nullable
Example
203.0.113.7
givenAt
string format: date-time
nullable
Example
2026-10-05T09:30:00+00:00
topics
object
key
additional properties
boolean
Example
{
  "product_news": true
}
Example
{
  "id": null,
  "externalId": "user_4821",
  "email": "ana.popescu@example.com",
  "firstName": "Ana",
  "lastName": "Popescu",
  "phone": "+40721000000",
  "city": "Cluj-Napoca",
  "countryCode": "RO",
  "language": "ro",
  "attributes": {
    "plan": "pro",
    "seats": 12
  },
  "consent": {
    "basis": "Subscribed",
    "proof": {
      "text": "Send me product news and offers from Notely.",
      "textVersion": "2",
      "locale": "ro_RO",
      "ipAddress": "203.0.113.7",
      "givenAt": "2026-10-05T09:30:00+00:00"
    }
  },
  "topics": {
    "product_news": true
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

The contact as stored, and whether it was created

Media typeapplication/json
object
isSuccess
boolean
value
One of:
object
contact
object
id
string format: guid
storeId
string format: guid
nullable
email
string
firstName
string
nullable
lastName
string
nullable
phone
string
nullable
city
string
nullable
countryCode
string
nullable
consentStatus
string
Allowed values: Unknown SoftOptIn Subscribed Unsubscribed Bounced Complained CheckoutStarted PendingConfirmation
isPayingCustomer
boolean
orderCount
integer format: int32
totalSpent
number format: decimal
lastOrderAt
string format: date-time
nullable
sourceCreatedAt
string format: date-time
nullable
lastSyncedAt
string format: date-time
nullable
fromOrders
boolean
consentSource
string
nullable
consentUpdatedAt
string format: date-time
nullable
storeConsentMode
One of:
string
Allowed values: Explicit Notice OwnConsent None
marketingDeclared
boolean
tags
Array<string>
nullable
attributes
object
key
additional properties
lastOpenAt
string format: date-time
nullable
lastClickAt
string format: date-time
nullable
lastEmailedAt
string format: date-time
nullable
language
string
nullable
addedAt
string format: date-time
nullable
lastConversionAt
string format: date-time
nullable
created
boolean
status
integer format: int32
errors
Array<object>
object
code
string
message
string
params
object
key
additional properties
fieldErrors
object
key
additional properties
Array<object>
object
code
string
message
string
params
object
key
additional properties
Example
{
  "isSuccess": true,
  "value": {
    "contact": {
      "id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
      "storeId": null,
      "email": "ana.popescu@example.com",
      "firstName": "Ana",
      "lastName": "Popescu",
      "phone": "+40721000000",
      "city": "Cluj-Napoca",
      "countryCode": "RO",
      "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": "ro",
      "addedAt": "2026-10-05T09:30:00+00:00",
      "lastConversionAt": null
    },
    "created": true
  },
  "status": 0,
  "errors": [],
  "fieldErrors": null
}

400

Section titled “400”

Validation failed: see errors[].code and fieldErrors

Media typeapplication/problem+json
object
statusCode
integer format: int32
default: 400
message
string
default: One or more errors occurred!
errors
object
key
additional properties
Array<string>
Example
{
  "statusCode": 400,
  "message": "One or more errors occurred!"
}

401

Section titled “401”

Missing or invalid API key

403

Section titled “403”

The key lacks the contacts:write permission