Allo

Append numbers

Appends phone numbers to the Power Dialer queue assigned to the authenticated user. Creates the queue implicitly if none exists. Send user id or email to…

POST/v2/api/dialing-queues/current/numbers

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 via GET /v2/api/users.
  • email — used only when user_id is 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 typeValue
TEXTAny text
NUMBERA number, such as 1200 or 12.5
DATEYYYY-MM-DD or an ISO date-time, or a day, month and 4-digit year separated by /, - or ., such as 03/04/2026
BOOLEANtrue/false, 1/0, yes/no, y/n or oui/non, in any case
DROPDOWNThe 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:

reasonMeaning
INVALID_CUSTOM_ATTRIBUTE_VALUEA 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

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Body

numbersobject[]required

Numbers to append to the queue. Each entry requires a phone number; contact metadata is optional.

9 fields
numberstringrequired

Phone number in any format — will be normalized to E.164

namestring | null

First name (optional — used to create or match a contact)

last_namestring | null

Last name

companystring | null

Company name — matched by name within the team (case-insensitive). If no matching company exists, one is created automatically.

websitestring | null

Website URL

job_titlestring | null

Job title

emailsstring[]

Email addresses

addressesstring[]

Physical addresses

custom_attributesobject | null

Values for the team's existing person custom fields, keyed by field key (see [GET /v2/api/crm/attributes](/en/v2/api-reference/crm/list-attributes)). Values are strings: NUMBER as a number, DATE as YYYY-MM-DD, an ISO date-time, or 03/04/2026, 03-04-2026, 03.04.2026 (4-digit year, read with date_order), BOOLEAN as true/false, 1/0, yes/no, y/n or oui/non in any case, DROPDOWN as an option label or key. Blank values are ignored. Fields are never created: an unknown or deleted key is ignored (the number is still added with its known attributes) and reported in ignored_custom_attributes in the response, a value that does not fit the field type skips it with INVALID_CUSTOM_ATTRIBUTE_VALUE. On an existing contact, only empty fields are filled.

user_idstring | null

Optional. ID of a teammate whose queue should receive the numbers. The teammate must belong to the same team as the API key owner. Wins over email when both are provided. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users).

emailstring<email> | null

Optional. Email of a teammate whose queue should receive the numbers. Ignored when user_id is also supplied.

date_orderenum<string>

Optional. How to read numeric DATE values in custom_attributes such as 03/04/2026: DAY_FIRST (3 April) or MONTH_FIRST (4 March). Applies to every date field in the request. When absent, each date field is read in the order its values settle (a 13/04/2026 can only be day first); when none settle it, your phone number's country decides: month first for the US, day first everywhere else.

DAY_FIRSTMONTH_FIRST

Responses

200Numbers appended
dataobject
3 fields
addedobject[]

Numbers that were successfully appended

12 fields
number_tostring

E.164 destination phone number

positioninteger

Order within the queue (0-based)

created_atstring<date-time>
updated_atstring<date-time>
call_start_datestring<date-time> | null

When the user started calling this entry. null if the entry is still unassigned.

call_idstring | null

ID of the call placed for this entry (cll-*). null until a call is placed.

routing_resultenum<string>

Final routing outcome of the call placed for this entry.

FAILEDRECEIVEDBLOCKEDANSWEREDTRANSFERRED_BLANDTRANSFERRED_ELEVEN_LABSTRANSFERRED_EXTERNALFAILED_EXTERNALVOICEMAILCLOSED

sync_statusenum<string>

State of contact creation/sync for this entry.

NOT_SYNCEDPROCESSINGSYNCED

detected_outbound_voicemailboolean | null

Whether the call was detected as having reached a voicemail box.

not_reached_destination_reasonenum<string>

Why the call did not reach the contact (only set when applicable).

BUSYCALLEE_TEMPORARILY_UNAVAILABLERING_TIMEOUTNOT_IN_SERVICEDECLINEDNETWORK_ERROR

voicemail_leftboolean | null

Whether the user left a voicemail on this entry.

call_statusenum<string>

Status of this entry, derived from the call placed for it. QUEUED: no call yet, or the call is still in progress. SKIPPED: skipped in the Power Dialer with no call placed (if a call is placed for it later, the status follows that call). VOICEMAIL: the call reached a voicemail box. CONNECTED: the call was answered at route level (routing_result is ANSWERED), no voicemail was detected and no not_reached_destination_reason is set; this can over-report a real conversation. TRANSFERRED: the call was transferred. BUSY: the destination was busy. WRONG_NUMBER: the destination is not in service. NO_ANSWER: the call ended without an answer, including the other not_reached_destination_reason values and any other final route status (failed, blocked, closed, handled by call flow).

QUEUEDSKIPPEDVOICEMAILCONNECTEDTRANSFERREDNO_ANSWERBUSYWRONG_NUMBER

skippedobject[]

Numbers that were skipped (e.g. invalid format)

2 fields
numberstring

The raw input number that was skipped

reasonenum<string>

Why the number was skipped. UNKNOWN_CUSTOM_ATTRIBUTE (deprecated, no longer returned): unknown custom_attributes keys are now ignored and listed in ignored_custom_attributes. INVALID_CUSTOM_ATTRIBUTE_VALUE: a custom_attributes value does not fit its field type, including an impossible date (31/02/2026), a 2-digit year or an unknown yes/no word.

INVALID_PHONE_NUMBERUNKNOWN_CUSTOM_ATTRIBUTEINVALID_CUSTOM_ATTRIBUTE_VALUE

ignored_custom_attributesobject[]

Always present, empty when nothing was ignored. Added numbers whose custom_attributes had keys matching none of the team's active person custom fields. Those keys were dropped.

2 fields
numberstring

The added number, in E.164 format

keysstring[]

The ignored custom_attributes keys

400Queue limit reached or validation error
errorobject
6 fields
typestring
codestring
messagestring
retryableboolean
request_idstring
retry_after_secondsinteger | null
401
404Assignee not found
errorobject
6 fields
typestring
codestring
messagestring
retryableboolean
request_idstring
retry_after_secondsinteger | null
409Concurrent append conflict
errorobject
6 fields
typestring
codestring
messagestring
retryableboolean
request_idstring
retry_after_secondsinteger | null
429