Référence de l’API

Groupes de contacts

Regrouper des contacts et envoyer des diffusions de groupe.

get/v1/contact-groups

Lister les groupes de contacts

Permissioncontact_groups:r

Nécessite contact_groups:r.

Paramètres

Paramètre	Type	Description
`limit`requête	integer	Minimum : 1 Maximum : 100 Par défaut : 50
`offset`requête	integer	Minimum : 0 Par défaut : 0
`search`requête	string	Filtrer par nom de groupe (insensible à la casse, correspondance partielle)

Réponses

200Une page de groupes, du plus récent au plus ancien, chacun avec ses membres.

Champ	Type	Description
`total`obligatoire	integer	Nombre total d’enregistrements correspondants.
`limit`obligatoire	integer
`offset`obligatoire	integer
`data[]`obligatoire	object[]
`id`obligatoire	string
`name`obligatoire	string
`description`obligatoire	string	Peut être null
`member_count`obligatoire	integer
`members[]`obligatoire	object[]
`id`obligatoire	string	L’identifiant du contact.
`phone_number`obligatoire	string	Peut être null
`name`obligatoire	string	Peut être null
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	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.
422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.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

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

post/v1/contact-groups

Créer un groupe de contacts

Permissioncontact_groups:w

Nécessite contact_groups:w.

Corps de la requête

Champ	Type	Description
`name`obligatoire	string	Au plus 100 caractères
`description`	string	Au plus 500 caractères

Réponses

201Le groupe.

Champ	Type	Description
`id`obligatoire	string
`name`obligatoire	string
`description`obligatoire	string	Peut être null
`member_count`obligatoire	integer
`members[]`obligatoire	object[]
`id`obligatoire	string	L’identifiant du contact.
`phone_number`obligatoire	string	Peut être null
`name`obligatoire	string	Peut être null
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	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.
409CONTACT_GROUP_ALREADY_EXISTS : ce nom est déjà utilisé.Le corps d’erreur standard.
422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.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

curl -X POST https://api.honkio.ca/v1/contact-groups \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "..."
  }'

get/v1/contact-groups/{id}

Obtenir un groupe de contacts avec ses membres

Permissioncontact_groups:r

Nécessite contact_groups:r.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Réponses

200Le groupe, avec ses membres.

Champ	Type	Description
`id`obligatoire	string
`name`obligatoire	string
`description`obligatoire	string	Peut être null
`member_count`obligatoire	integer
`members[]`obligatoire	object[]
`id`obligatoire	string	L’identifiant du contact.
`phone_number`obligatoire	string	Peut être null
`name`obligatoire	string	Peut être null
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	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.
404CONTACT_GROUP_NOT_FOUND.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

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

patch/v1/contact-groups/{id}

Mettre à jour un groupe de contacts

Permissioncontact_groups:m

Nécessite contact_groups:m.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Corps de la requête

Champ	Type	Description
`name`	string	Au plus 100 caractères
`description`	string	Au plus 500 caractères

Réponses

200Le groupe mis à jour.

Champ	Type	Description
`id`obligatoire	string
`name`obligatoire	string
`description`obligatoire	string	Peut être null
`member_count`obligatoire	integer
`members[]`obligatoire	object[]
`id`obligatoire	string	L’identifiant du contact.
`phone_number`obligatoire	string	Peut être null
`name`obligatoire	string	Peut être null
`created_at`obligatoire	string	Format : date-time
`updated_at`obligatoire	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 lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
404CONTACT_GROUP_NOT_FOUND.Le corps d’erreur standard.
409CONTACT_GROUP_ALREADY_EXISTS : ce nom est déjà utilisé.Le corps d’erreur standard.
422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.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

curl -X PATCH https://api.honkio.ca/v1/contact-groups/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Patients due for a recall visit"
  }'

delete/v1/contact-groups/{id}

Supprimer un groupe de contacts

Permissioncontact_groups:d

Nécessite contact_groups:d.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Réponses

204Supprimé. Ses contacts sont conservés.
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 lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production ; KEY_FENCED lorsque la modification assouplirait les restrictions d’autorisation et de blocage de la clé appelante elle-même. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
404CONTACT_GROUP_NOT_FOUND.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

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

post/v1/contact-groups/{id}/members

Ajouter un membre à un groupe de contacts

Permissioncontact_groups:m

Fournissez soit contact_id (fiche Contact existante), soit phone_number (créé automatiquement s’il n’existe pas).

Nécessite contact_groups:m.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Corps de la requête

Champ	Type	Description
`contact_id`	string
`phone_number`	string

Réponses

201Le membre ajouté.
Champ Type Description
idobligatoire string
L’identifiant du contact.
phone_numberobligatoire string
nameobligatoire string
Peut être null
added_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 lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production ; KEY_FENCED lorsque la modification assouplirait les restrictions d’autorisation et de blocage de la clé appelante elle-même. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
404CONTACT_GROUP_NOT_FOUND ou CONTACT_NOT_FOUND.Le corps d’erreur standard.
409CONTACT_GROUP_MEMBER_EXISTS.Le corps d’erreur standard.
422VALIDATION_ERROR (ni contact_id ni phone_number), INVALID_PHONE_NUMBER ou CONTACT_HAS_NO_PHONE (le contact n’a pas de numéro de téléphone).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

curl -X POST https://api.honkio.ca/v1/contact-groups/ID/members \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "CONTACT_ID"
  }'

delete/v1/contact-groups/{id}/members/{contactId}

Retirer un membre d’un groupe de contacts

Permissioncontact_groups:m

Nécessite contact_groups:m.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string
`contactId`obligatoirechemin	string

Réponses

204Retiré du groupe. Le contact est conservé.
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 lorsqu’une clé de test tente de modifier un élément référencé par la liste d’autorisation ou de blocage d’une clé de production ; KEY_FENCED lorsque la modification assouplirait les restrictions d’autorisation et de blocage de la clé appelante elle-même. Aussi FORBIDDEN lorsque la clé ne dispose pas de la permission requise.Le corps d’erreur standard.
404CONTACT_GROUP_NOT_FOUND ou CONTACT_GROUP_MEMBER_NOT_FOUND.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

curl -X DELETE https://api.honkio.ca/v1/contact-groups/ID/members/CONTACT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/contact-groups/{id}/messages

Envoyer un SMS à tous les membres d’un groupe de contacts

Permissionmessages:w

Répond toujours 207, que le message ait été envoyé à tous les membres ou que tous aient échoué : vérifiez chaque entrée de results plutôt que le statut HTTP. Chaque résultat indique le numéro to du membre. Une diffusion réelle répétée avec la même Idempotency-Key dans les 24 heures renvoie le 207 enregistré de la première tentative, sans refaire les vérifications portant sur l’ensemble du groupe ni utiliser un autre créneau de diffusion quotidien. Une nouvelle tentative ultérieure avec cette clé refait les vérifications (et peut utiliser un créneau), mais n’envoie jamais de nouveau message à un membre déjà joint par la première tentative.

Nécessite messages:w.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string
`Idempotency-Key`en-tête	string	Au plus 128 caractères

Corps de la requête

Champ	Type	Description
`from`obligatoire	string	Numéro d’envoi (E.164, doit appartenir au compte)
`body`obligatoire	string	Jusqu’à 1 600 caractères et 10 parties SMS. Un corps plus long est refusé avec 422 MESSAGE_TOO_LONG avant qu’un seul membre ne reçoive de message. Au plus 1600 caractères
`skip_consent_check`	boolean

Réponses

207Toujours 207 : vérifiez chaque résultat, pas le statut. Une diffusion réelle répétée avec la même Idempotency-Key dans les 24 heures renvoie le résultat enregistré de la première tentative.

Champ	Type	Description
`group_id`obligatoire	string
`sent_to`obligatoire	integer	Membres qui n’ont pas échoué.
`failed`obligatoire	integer
`results[]`obligatoire	object[]
`to`obligatoire	string	Le numéro du membre.
`status`obligatoire	string	En minuscules : le statut du message (queued, sent, delivered, etc.), ou failed.
`message_id`	string	Absent lorsque l’envoi au membre a échoué avant qu’un message soit créé.
`error`	string	Un code d’erreur : la raison de l’échec pour ce membre, ou le error_code du message lui-même.

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402INSUFFICIENT_BALANCE : le solde ne couvre pas l’envoi. Aussi PAYMENT_REQUIRED lorsqu’une clé de production est utilisée avant la première recharge.Le corps d’erreur standard.
403FORBIDDEN (skip_consent_check avec une clé de production, ou la clé n’a pas l’autorisation messages:w), ACCOUNT_NOT_VERIFIED ou SENDING_PAUSED.Le corps d’erreur standard.
404CONTACT_GROUP_NOT_FOUND.Le corps d’erreur standard.
422VALIDATION_ERROR, BROADCAST_TOO_LARGE, MESSAGE_TOO_LONG ou LINK_SHORTENER_BLOCKED.Le corps d’erreur standard.
429BROADCAST_LIMIT_REACHED, DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED ou RECIPIENT_RATE_LIMITED, ou RATE_LIMITED au-delà de 100 requêtes par seconde.Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

cURL

curl -X POST https://api.honkio.ca/v1/contact-groups/ID/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX",
    "body": "Hello from HonkIO!"
  }'