Skip to content
Azimea Docs

Create or update contacts in bulk

POST
/api/v1/contacts/batch
curl --request POST \
  --url https://dashboard.azimea.com/api/v1/contacts/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "contacts": [ { "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 } }, { "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”
Media typeapplication/json
object
contacts
required
Array<object>
>= 1 characters
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
  }
}
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
    }
  },
  {
    "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": "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
      }
    },
    {
      "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”

200

Section titled “200”

Totals and one result per contact, in the order sent

Media typeapplication/json
object
isSuccess
boolean
value
One of:
object
created
integer format: int32
updated
integer format: int32
failed
integer format: int32
results
Array<object>
object
index
integer format: int32
status
string
Allowed values: Created Updated Failed
id
string format: guid
nullable
errors
Array<object>
nullable
object
code
string
field
string
nullable
params
object
key
additional properties
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": {
    "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
}

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