Numéros de téléphone

Lister les provinces et leurs indicatifs régionaux actifs

Réponses

• 200Provinces et leurs indicatifs régionaux actifs.›

  Champ	Type	Description
  data[]obligatoire	object[]
  provinceobligatoire	string
  countryobligatoire	string
  area_codesobligatoire	string[]
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.phoneNumbers.areaCodes()
if (error) throw new Error(error.message)
console.log(data.data)

curl https://api.honkio.ca/v1/phone-numbers/area-codes \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Rechercher des numéros de téléphone canadiens disponibles à provisionner

Paramètres

Réponses

• 200Numéros disponibles. Un tableau simple, non enveloppé dans data.›

  Champ	Type	Description
  phone_numberobligatoire	string	E.164
  country_codeobligatoire	string
  area_codeobligatoire	string	Peut être null
  regionobligatoire	string	Province ou territoire, lorsque l’indicatif régional y correspond. Peut être null
  capabilitiesobligatoire	string[]
  monthly_cost_centsobligatoire	integer	Loyer récurrent en cents CAD, selon la catégorie (local ou sans frais) à laquelle ce numéro serait vendu.
  upfront_cost_centsobligatoire	integer	Le loyer du premier mois, facturé lors du provisionnement du numéro.
  activation_fee_centsobligatoire	integer	Frais d’activation uniques facturés avec le premier mois. Non remboursés à la libération.
  currencyobligatoire	string	Une valeur parmi : CAD
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 422VALIDATION_ERROR (details.area_codes énumère les indicatifs qui ne sont pas offerts) ou TOO_MANY_AREA_CODES.Le corps d’erreur standard.
• 429RATE_LIMITED : 30 recherches par minute et par compte, ou 100 requêtes par seconde.Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.
• 502NUMBER_SEARCH_FAILED : la recherche auprès de l’opérateur a échoué.Le corps d’erreur standard.

Exemple

const { data: available, error } = await honkio.phoneNumbers.search({ areaCodes: ['416', '647'], limit: 5 })
if (error) throw new Error(error.message)
for (const n of available) console.log(n.phone_number, n.monthly_cost_cents)

curl https://api.honkio.ca/v1/phone-numbers/search \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Lister les numéros de téléphone provisionnés du compte

Réponses

• 200Les numéros du compte, à l’exclusion des numéros libérés, des plus récents aux plus anciens. Non paginé.›

  Champ	Type	Description
  data[]obligatoire	object[]
  idobligatoire	string
  phone_numberobligatoire	string	E.164
  area_codeobligatoire	string
  regionobligatoire	string	Province ou territoire, lorsque l’indicatif régional y correspond. Peut être null
  capabilitiesobligatoire	string[]
  statusobligatoire	string	Une valeur parmi : ACTIVE | SUSPENDED | RELEASING | RELEASED
  monthly_cost_centsobligatoire	integer	Loyer récurrent en cents CAD.
  provisioned_atobligatoire	string	Format : date-time
  released_atobligatoire	string	Format : date-time Peut être null
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.phoneNumbers.list()
if (error) throw new Error(error.message)
for (const n of data.data) console.log(n.phone_number, n.status)

curl https://api.honkio.ca/v1/phone-numbers \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Provisionner (acheter) un numéro de téléphone

Corps de la requête

Réponses

• 201Le numéro provisionné.›

  Champ	Type	Description
  idobligatoire	string
  phone_numberobligatoire	string	E.164
  area_codeobligatoire	string
  regionobligatoire	string	Province ou territoire, lorsque l’indicatif régional y correspond. Peut être null
  capabilitiesobligatoire	string[]
  statusobligatoire	string	Une valeur parmi : ACTIVE | SUSPENDED | RELEASING | RELEASED
  monthly_cost_centsobligatoire	integer	Loyer récurrent en cents CAD.
  provisioned_atobligatoire	string	Format : date-time
  released_atobligatoire	string	Format : date-time Peut être null
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402INSUFFICIENT_BALANCE : le solde ne couvre pas le premier mois et les frais d’activation. Rien n’a été facturé ni commandé.Le corps d’erreur standard.
• 403NUMBER_LIMIT_REACHED (details contient limit et used), LIVE_KEY_REQUIRED (les clés de test ne peuvent pas provisionner) ou ACCOUNT_NOT_VERIFIED (le compte n’a pas vérifié de numéro mobile du propriétaire).Le corps d’erreur standard.
• 409CONFLICT (le numéro est déjà détenu) ou PURCHASE_IN_PROGRESS (un autre achat est en cours pour ce compte ; réessayez sous peu).Le corps d’erreur standard.
• 422NON_CANADIAN_NUMBER ou VALIDATION_ERROR.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500INTERNAL_ERROR : la facturation a échoué pour une raison autre que le solde.Le corps d’erreur standard.
• 501TOLLFREE_800_COMING_SOON : les numéros 1-800 ne sont pas encore offerts.Le corps d’erreur standard.
• 502PROVISIONING_FAILED : l’opérateur n’a pas provisionné le numéro. Le montant facturé est remboursé.Le corps d’erreur standard.

Exemple

const { data: number, error } = await honkio.phoneNumbers.provision({ phoneNumber: '+1416XXXXXXX' })
if (error) throw new Error(error.message)
console.log(number.id, number.status)

curl -X POST https://api.honkio.ca/v1/phone-numbers \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX"
  }'

Obtenir un numéro de téléphone par identifiant

Paramètres

Réponses

• 200Le numéro, y compris s’il a été libéré.›

  Champ	Type	Description
  idobligatoire	string
  phone_numberobligatoire	string	E.164
  area_codeobligatoire	string
  regionobligatoire	string	Province ou territoire, lorsque l’indicatif régional y correspond. Peut être null
  capabilitiesobligatoire	string[]
  statusobligatoire	string	Une valeur parmi : ACTIVE | SUSPENDED | RELEASING | RELEASED
  monthly_cost_centsobligatoire	integer	Loyer récurrent en cents CAD.
  provisioned_atobligatoire	string	Format : date-time
  released_atobligatoire	string	Format : date-time Peut être null
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucune ressource correspondante sur ce compte.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.phoneNumbers.get('NUMBER_ID')
if (error) throw new Error(error.message)
console.log(data.phone_number, data.status)

curl https://api.honkio.ca/v1/phone-numbers/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Libérer (annuler) un numéro de téléphone

Paramètres

Réponses

• 204Libéré, ou déjà libéré chez l’opérateur.
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 404NOT_FOUND : aucun numéro correspondant sur ce compte, ou il a déjà été libéré.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.
• 502RELEASE_FAILED : l’opérateur n’a pas accepté la libération. Le numéro vous appartient toujours, inchangé ; réessayez.Le corps d’erreur standard.

Exemple

const { error } = await honkio.phoneNumbers.release('NUMBER_ID')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/phone-numbers/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Lister vos demandes d’allocation de numéros de téléphone

Réponses

• 200Les demandes d’allocation du compte, des plus récentes aux plus anciennes.›

  Champ	Type	Description
  data[]obligatoire	object[]
  idobligatoire	string
  requested_limitobligatoire	integer	Nombre total de numéros demandés, et non un incrément.
  limit_at_requestobligatoire	integer
  held_at_requestobligatoire	integer
  reasonobligatoire	string
  statusobligatoire	string	Une valeur parmi : PENDING | APPROVED | DENIED
  granted_limitobligatoire	integer	Peut être null
  staff_noteobligatoire	string	Peut être null
  decided_atobligatoire	string	Format : date-time Peut être null
  created_atobligatoire	string	Format : date-time
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
• 429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

curl https://api.honkio.ca/v1/phone-numbers/allowance-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Demander une allocation de numéros de téléphone plus élevée

Corps de la requête

Réponses

• 201La demande, en attente d’examen.›

  Champ	Type	Description
  idobligatoire	string
  requested_limitobligatoire	integer	Nombre total de numéros demandés, et non un incrément.
  limit_at_requestobligatoire	integer
  held_at_requestobligatoire	integer
  reasonobligatoire	string
  statusobligatoire	string	Une valeur parmi : PENDING | APPROVED | DENIED
  granted_limitobligatoire	integer	Peut être null
  staff_noteobligatoire	string	Peut être null
  decided_atobligatoire	string	Format : date-time Peut être null
  created_atobligatoire	string	Format : date-time
• 401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
• 402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
• 403LIVE_KEY_REQUIRED : les clés de test ne peuvent pas accéder ici aux ressources de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise par cette opération, ou lorsque le compte est suspendu ou fermé.Le corps d’erreur standard.
• 409ALLOWANCE_REQUEST_PENDING : une demande est déjà en attente.Le corps d’erreur standard.
• 422VALIDATION_ERROR, ou INVALID_ALLOWANCE_REQUEST lorsque requested_limit n’est pas supérieur à la limite actuelle.Le corps d’erreur standard.
• 429RATE_LIMITED : 3 requêtes par jour et par compte.Le corps d’erreur standard.
• 500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

curl -X POST https://api.honkio.ca/v1/phone-numbers/allowance-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_limit": 2,
    "reason": "..."
  }'