Allo

Ajouter des numeros

Par defaut, les numeros sont ajoutes a la file assignee au proprietaire de la cle API. Pour ajouter a la file d'un coequipier, envoyez user id ou email dans…

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

Cibler la file d'un coequipier

Par defaut, les numeros sont ajoutes a la file assignee au proprietaire de la cle API. Pour ajouter a la file d'un coequipier, envoyez user_id ou email dans le corps JSON. Le coequipier doit appartenir a la meme equipe que le proprietaire de la cle API.

  • user_id — l'emporte quand les deux sont fournis. Resolvez les ids des coequipiers via GET /v2/api/users.
  • email — utilise uniquement quand user_id est absent.

Si le coequipier n'a pas de file en cours, une nouvelle file est creee avec le proprietaire de la cle API comme creator_id et le coequipier comme assignee_id. Si l'utilisateur resolu n'est pas dans votre equipe, la reponse est 404 ASSIGNEE_NOT_FOUND.

Champs personnalisés

Chaque numéro peut porter custom_attributes : des valeurs pour les champs personnalisés des personnes de votre équipe, indexées par la key du champ. Listez les clés avec GET /v2/api/crm/attributes. Les valeurs sont écrites sur le contact du numéro, et le contact est créé si le numéro n'en a pas.

{
  "numbers": [
    {
      "number": "+12125550010",
      "name": "John",
      "custom_attributes": {
        "lead_source": "Webinar",
        "deal_size": "1200",
        "next_meeting": "2026-11-03"
      }
    }
  ]
}

Les valeurs sont des chaînes, au format du champ :

Type de champValeur
TEXTN'importe quel texte
NUMBERUn nombre, comme 1200 ou 12.5
DATEYYYY-MM-DD ou une date-heure ISO, ou un jour, un mois et une année à 4 chiffres séparés par /, - ou ., comme 03/04/2026
BOOLEANtrue/false, 1/0, yes/no, y/n ou oui/non, majuscules ou minuscules
DROPDOWNLe label ou la clé d'une des options du champ

Ordre des dates

03/04/2026 est le 3 avril en Europe et le 4 mars aux États-Unis. Envoyez date_order à côté de numbers pour préciser lequel : DAY_FIRST ou MONTH_FIRST. Il s'applique à tous les champs date de la requête.

{
  "date_order": "MONTH_FIRST",
  "numbers": [
    { "number": "+12125550010", "custom_attributes": { "next_meeting": "11/03/2026" } }
  ]
}

Sans date_order, chaque champ date est lu dans l'ordre que ses propres valeurs imposent : 13/04/2026 ne peut être que jour en premier, 04/13/2026 que mois en premier. Quand les valeurs ne tranchent pas, le pays de votre numéro décide : mois en premier pour les États-Unis, jour en premier partout ailleurs.

Les valeurs vides sont ignorées. Quand le contact existe déjà, seuls ses champs vides sont remplis : une valeur déjà renseignée est conservée.

Cet endpoint ne crée jamais de champ personnalisé. Créez-les d'abord avec POST /v2/api/crm/attributes.

Une clé qui ne correspond à aucun champ personnalisé de votre équipe, ou qui désigne un champ supprimé, est ignorée. Le numéro est tout de même ajouté avec ses attributs connus, et les clés inconnues sont listées dans ignored_custom_attributes : un tableau toujours présent d'entrées { "number", "keys" }, avec number au format E.164. Le tableau est vide quand aucune clé n'a été ignorée.

{
  "added": [{ "number_to": "+12125550010", "position": 0 }],
  "skipped": [],
  "ignored_custom_attributes": [
    { "number": "+12125550010", "keys": ["unknown_field"] }
  ]
}

Une clé connue avec une valeur inutilisable, c'est autre chose : le numéro n'est pas ajouté et revient dans skipped :

reasonSignification
INVALID_CUSTOM_ATTRIBUTE_VALUEUne valeur ne correspond pas au type de son champ : bientôt ou 31/02/2026 pour un champ DATE, une année à 2 chiffres comme 03/04/26, peut-être pour un champ BOOLEAN

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Corps

numbersobject[]requis

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

9 champs
numberstringrequis

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

Réponses

200Numbers appended
dataobject
3 champs
addedobject[]

Numbers that were successfully appended

12 champs
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 champs
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 champs
numberstring

The added number, in E.164 format

keysstring[]

The ignored custom_attributes keys

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