Skip to content
AzimeaDocs
Dashboard
POST
/contact-attributes
curl --request POST \
--url https://api.azimea.com/v1/contact-attributes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "key": "plan", "label": "Plan", "type": "Text", "description": "The subscription plan the person is on." }'

Defines a custom attribute before any contact carries it, so its type is fixed: a value is then stored as that type everywhere, and a rule like greater than 5000 means one thing in every segment. The key is lowercase letters, digits and underscores, starting with a letter, up to 40 characters (audience.attribute_key_invalid); a built-in field’s name is refused (audience.attribute_reserved), an existing key gives 409 audience.attribute_exists, and a company has at most 100 fields (audience.attribute_limit_reached). The label defaults to the key made readable. Needs contacts:write.

Media typeapplication/json
object
key

Required. Lowercase letters, digits and _, starting with a letter, at most 40 characters. A built-in field’s name is refused, and so is a key that already exists.

string
Example
plan
label

The name shown in the dashboard. Made from the key when left out.

string
nullable 0 <= 80 characters
Example
Plan
type

Required. How values are stored and compared. It cannot be changed afterwards.

string
Allowed values: Text Number Boolean Date DateTime TextList
Example
Text
description

A note for your team about what the field holds.

string
nullable 0 <= 300 characters
Example
The subscription plan the person is on.
Example
{
"key": "plan",
"label": "Plan",
"type": "Text",
"description": "The subscription plan the person is on."
}

The field as defined

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
key

The field’s key: lowercase letters, digits and _, starting with a letter, at most 40 characters. It never changes.

string
label

The name shown in the dashboard.

string
type

How values are stored and compared in segments. Fixed once the field exists.

string
Allowed values: Text Number Boolean Date DateTime TextList
description

A note for your team about what the field holds; null when none was written.

string
nullable
createdFrom

Where the field was made: the dashboard (Ui), the API (Api) or a file import (Csv).

string
Allowed values: Ui Api Csv
createdAt

When the field was created.

string format: date-time
archivedAt

When the field was archived; null while it is active. An archived field is hidden from pickers and keeps every stored value.

string format: date-time
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": true,
"value": {
"key": "plan",
"label": "Plan",
"type": "Text",
"description": "The subscription plan the person is on.",
"createdFrom": "Api",
"createdAt": "2026-10-05T09:30:00+00:00",
"archivedAt": 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