Targeting a teammate's queue
By default, numbers are appended to the queue assigned to the API key owner. To append to a teammate's queue, send user_id or email in the JSON body. The teammate must belong to the same team as the API key owner.
user_id— wins when both are provided. Resolve teammate ids viaGET /v2/api/users.email— used only whenuser_idis absent.
If the teammate has no current queue, one is created with the API key owner recorded as creator_id and the teammate as assignee_id. If the resolved user isn't on your team, the response is 404 ASSIGNEE_NOT_FOUND.
Custom fields
Each number can carry custom_attributes: values for your team's person custom fields, keyed by field key. List the keys with GET /v2/api/crm/attributes. The values are written on the contact behind the number, and the contact is created if the number has none.
{
"numbers": [
{
"number": "+12125550010",
"name": "John",
"custom_attributes": {
"lead_source": "Webinar",
"deal_size": "1200",
"next_meeting": "2026-11-03"
}
}
]
}
Values are strings, written in the field's format:
| Field type | Value |
|---|---|
TEXT | Any text |
NUMBER | A number, such as 1200 or 12.5 |
DATE | YYYY-MM-DD or an ISO date-time, or a day, month and 4-digit year separated by /, - or ., such as 03/04/2026 |
BOOLEAN | true/false, 1/0, yes/no, y/n or oui/non, in any case |
DROPDOWN | The label or key of one of the field's options |
Date order
03/04/2026 is 3 April in Europe and 4 March in the US. Send date_order next to numbers to say which one you mean: DAY_FIRST or MONTH_FIRST. It applies to every date field in the request.
{
"date_order": "MONTH_FIRST",
"numbers": [
{ "number": "+12125550010", "custom_attributes": { "next_meeting": "11/03/2026" } }
]
}
Without date_order, each date field is read in the order its own values settle: 13/04/2026 can only be day first, 04/13/2026 only month first. When the values don't settle it, the country of your phone number decides: month first for the US, day first everywhere else.
Blank values are ignored. When the contact already exists, only its empty fields are filled: a value already set is kept.
Custom fields are never created by this endpoint. Create them first with POST /v2/api/crm/attributes.
A key that matches none of your team's custom fields, or names a deleted field, is ignored. The number is still added with its known attributes, and the unknown keys are listed in ignored_custom_attributes: an always-present array of { "number", "keys" } entries, with number in E.164 format. The array is empty when no key was ignored.
{
"added": [{ "number_to": "+12125550010", "position": 0 }],
"skipped": [],
"ignored_custom_attributes": [
{ "number": "+12125550010", "keys": ["unknown_field"] }
]
}
A known key with an unusable value is different: the number is not added and comes back in skipped:
reason | Meaning |
|---|---|
INVALID_CUSTOM_ATTRIBUTE_VALUE | A value does not fit its field type: soon or 31/02/2026 for a DATE field, a 2-digit year such as 03/04/26, maybe for a BOOLEAN field |