Aller au contenu
Espace client
Documentation de l’API

API développeurs

Téléphonie programmable : endpoints SIP, numéros, appels, SMS, portabilité et dial plan en code.

69 routes documentées · spécification OpenAPI · essai interactif

Démarrer

La plateforme développeurs fait de la téléphonie programmable : endpoints SIP (téléphones, softphones, applications), numéros, appels, SMS, portabilité et dial plan en code (votre serveur décide, appel par appel, de ce qui se passe).

Dial plan en code

Un numéro (ou un endpoint) relié à une application déclenche un POST signé vers son voiceUrl. Votre serveur répond par une liste JSON d'instructions : play, say, gather, dial, record, pause, set, redirect, queue, conference, voicemail, transfer, hangup. Les instructions avec action rappellent cette adresse avec le résultat (digits, dial.status, recording).

[
  { "say": "Bonjour, tapez 1 pour le service commercial, 2 pour le support." },
  { "gather": { "numDigits": 1, "action": "https://exemple.fr/menu" } }
]

Signature : X-VoxNova-Signature: t=<horodatage>,v1=<hex> = HMAC-SHA256(secret de l'application, ".").

Erreurs

Code Signification
200, 201 Succès (201 : ressource créée)
400 Requête invalide : le champ error dit lequel et pourquoi (ex. number : format invalide)
401 Clé absente, invalide ou révoquée
403 Droits insuffisants, fonction non incluse dans l'offre, compte suspendu, clé en lecture seule
404 Ressource introuvable (ou appartenant à une autre entreprise)
409 Conflit (ex. numéro pris entre-temps, e-mail déjà utilisé)
429 Trop de requêtes : réessayez après le délai indiqué par l'en-tête Retry-After

Chaque erreur renvoie { "error": "message en français", "code": "BAD_REQUEST" }.

Envoyer un SMS

1. Envoyer

curl -X POST "https://api.hcloud.fr/api/v1/sms" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"0612345678","text":"Votre commande est prête.","tag":"commande-42"}'
Champ Requis Description
to oui Mobile du destinataire : 0612345678, 06 12 34 56 78 ou +33612345678 (mobiles français, 06 et 07)
text oui Message, 1 000 caractères au plus (voir « Crédits consommés »)
sender non Expéditeur affiché, 3 à 11 lettres ou chiffres (par défaut : celui de l’entreprise) ; refusé s’il est interdit
tag non Votre référence (100 caractères), renvoyée dans les statuts et le webhook
type non transactional (par défaut) ou marketing
channel non sms (par défaut), whatsapp, ou auto (WhatsApp si possible, sinon SMS)

Réponse immédiate : le message est mis en file et part en quelques secondes.

{ "id": "cmx…", "to": "+33612345678", "status": "queued", "segments": 1, "tag": "commande-42", "type": "transactional", "channel": null, "createdAt": "2026-11-17T09:00:00.000Z" }

Gardez l’id : il identifie le message dans le suivi et dans le webhook. Pour ne jamais envoyer deux fois le même SMS (coupure réseau, nouvel essai), ajoutez l’en-tête Idempotency-Key.

2. Suivre la remise

status Signification
queued En file d’envoi
sent Accepté par l’opérateur
delivered Remis sur le téléphone
failed Échec ; le motif est dans error (un SMS en échec n’est pas facturé)
  • Webhook (recommandé) : abonnez une adresse à l’événement sms.status (POST /api/v1/webhooks). Vous recevez { "event": "sms.status", "data": { "id", "to", "status", "tag", "segments", "sender", "error", "at" } } à chaque étape.
  • Interrogation : GET /api/v1/sms/{id} renvoie le message et ses étapes (events) ; GET /api/v1/sms?status=failed&since=…&tag=… liste les messages.

3. Crédits consommés

  • 1 SMS = 160 caractères ; au-delà, le message est découpé en parties de 153 caractères, chacune comptée (segments dans la réponse).
  • Avec ê, â, î, ô, û, ç minuscule ou un emoji, la limite tombe à 70 caractères (67 par partie). É, è, à, ù et € ne changent rien.
  • Ordre de décompte : forfait du mois, puis solde, puis (si l’entreprise y a droit) SMS au comptage, facturés à l’unité en fin de mois, dans la limite d’un éventuel plafond mensuel.
  • GET /api/v1/sms/balance : forfait du mois, solde et comptage (metered : tarif, consommation du mois, plafond restant).

4. Erreurs

Code error Que faire
400 Numéro invalide Vérifiez to. Un numéro valide mais qui n’est pas un mobile français (fixe, étranger) est accepté puis passe en failed avec le motif dans error
400 Crédits SMS insuffisants Forfait et solde épuisés, sans comptage : ajoutez des crédits
400 Plafond mensuel des SMS au comptage atteint Attendez le mois suivant ou faites relever le plafond
400 Option SMS et WhatsApp non activée L’option doit être activée sur le compte
400 Expéditeur invalide / Expéditeur « … » interdit 3 à 11 lettres ou chiffres, et pas un nom bloqué
401 / 403 Clé absente ou invalide

Un compte d’essai (sandbox) accepte les mêmes appels : rien n’est envoyé, le message passe « remis » et le webhook part comme en production.

Compatibilité Twilio

Une adresse dédiée reprend le format de l’API Twilio : un code écrit pour les bibliothèques Twilio (Node.js, PHP, Python…) fonctionne ici en changeant les identifiants et en ajoutant quelques lignes. Tout ce qui est disponible ici l’est aussi dans l’API habituelle.

Identifiants

POST /api/org/twilio-compat/token (ou panneau › Intégrations › Compatibilité Twilio) crée l’Account SID (AC…) et l’Auth Token, affiché une seule fois ; un nouvel appel remplace le jeton. Authentification Basic AccountSid:AuthToken, comme chez Twilio.

Adresses

Twilio Ici
https://api.twilio.com/2010-04-01/… /api/twilio/2010-04-01/…
https://verify.twilio.com/v2/… /api/twilio/verify/v2/…
https://lookups.twilio.com/v2/… /api/twilio/lookups/v2/…

Avec les bibliothèques Twilio

// Node.js : npm i twilio @voxnova/sdk
import twilio from 'twilio';
import { TwilioCompatHttpClient } from '@voxnova/sdk';
const client = twilio(ACCOUNT_SID, AUTH_TOKEN, { httpClient: new TwilioCompatHttpClient('https://api.exemple.fr') });
await client.messages.create({ to: '+33612345678', from: 'MaMarque', body: 'Bonjour' });
// PHP : composer require twilio/sdk voxnova/sdk
$client = new Twilio\Rest\Client(ACCOUNT_SID, AUTH_TOKEN, null, null, new VoxNova\Twilio\HttpClient('https://api.exemple.fr'));
$client->messages->create('+33612345678', ['from' => 'MaMarque', 'body' => 'Bonjour']);
# Python : pip install twilio
from twilio.rest import Client
from twilio.http.http_client import TwilioHttpClient
class VoxNova(TwilioHttpClient):
    def request(self, method, url, **kw):
        host, path = url.split('://', 1)[1].split('/', 1)
        prefix = {'api': '', 'verify': '/verify', 'lookups': '/lookups'}[host.split('.')[0]]
        return super().request(method, 'https://api.exemple.fr/api/twilio' + prefix + '/' + path, **kw)
client = Client(ACCOUNT_SID, AUTH_TOKEN, http_client=VoxNova())

Pris en charge

Ressource Opérations Équivalent dans l’API habituelle
Messages créer (To, From, Body, StatusCallback), lire, lister POST /api/v1/sms (statusCallback)
Calls créer (To, From, Url ou Twiml, StatusCallback, Timeout), lire, lister, raccrocher (Status=completed), rediriger (Url, Twiml) POST /api/v1/calls (url, twiml, statusCallback), hangup, redirect
IncomingPhoneNumbers lister, lire, modifier (VoiceUrl, VoiceFallbackUrl, StatusCallback, FriendlyName) PATCH /api/v1/numbers/{number}
Recordings lister, lire, télécharger, supprimer /api/v1/recordings
Verify v2 Services, Verifications (sms, whatsapp), VerificationCheck, annulation /api/v1/verify
Lookups v2 PhoneNumbers (line_type_intelligence) GET /api/v1/lookup/{number}

TwiML (réponse de votre adresse vocale) : Say, Play, Pause, Gather (Say/Play imbriqués), Dial (numéro, Number, Client, Sip, Conference, Queue), Record, Redirect, Hangup, Reject, Enqueue, Message. Les requêtes vers votre adresse sont au format Twilio (CallSid, From, To, CallStatus, Digits, RecordingUrl…) et signées X-Twilio-Signature avec votre Auth Token : la fonction de vérification des bibliothèques Twilio fonctionne telle quelle. Les applications de l’API habituelle acceptent aussi le TwiML (format: "twiml", ou réponse XML).

Limites

Les codes d’erreur suivent ceux de Twilio (20003 authentification, 20404 introuvable, 21211 numéro invalide, 60200 et 60203 pour Verify…). Non pris en charge : MMS, Messaging Services, Conversations, Studio, Flex, TaskRouter, Video, et les SDK téléphone de Twilio (Voice SDK pour navigateur et mobiles) : utilisez le webphone. Lookups n’indique pas l’opérateur (carrier_name: null), peu fiable avec la portabilité.

Compte d’essai (sandbox)

Un compte d'essai est une entreprise fictive déjà équipée (4 utilisateurs, 4 postes, une file d’attente, un groupe d’appel, un standard vocal, des horaires, 2 numéros fictifs, des contacts et un historique d’appels). Il s'utilise exactement comme un vrai compte : mêmes routes, mêmes validations, mêmes réponses, mêmes webhooks. Mais rien ne sort de la plateforme :

  • aucun appel n'est passé ni reçu, aucun poste ne peut s'enregistrer ; un appel lancé par l'API apparaît dans le journal comme un appel fictif de 42 secondes ;
  • aucun SMS, aucun WhatsApp, aucun e-mail n'est envoyé : ils sont notés « remis » (statuts et webhooks compris) et visibles dans la console d'essai ;
  • aucun paiement réel : utilisez la carte de test 4242 4242 4242 4242 (date future, code au choix) ;
  • aucun vrai numéro : seuls les numéros fictifs de la plage réservée à la fiction, 01 99 00 00 00 à 01 99 00 99 99 (+33199000000 à +33199009999), peuvent être achetés, déclarés ou portés ;
  • aucune démarche n'est transmise à un opérateur ou à l'équipe : portabilité, identification, commande de services, paiement par virement se valident d'un clic dans la console d'essai ;
  • aucun téléphone de bureau n'est enregistré chez son constructeur, aucun enregistrement DNS n'est créé, aucun vrai domaine ne peut être pris (utilisez un domaine en .test).

Créer un compte d'essai

Depuis le panneau (administrateur) ou avec votre clé :

curl -X POST "https://api.hcloud.fr/api/org/sandboxes" -H "Authorization: Bearer vxk_…" -H "Content-Type: application/json" -d '{"name":"Mon intégration"}'

Réponse (la clé n'est affichée qu'une fois) :

{ "id": "…", "slug": "essai-…", "name": "Mon intégration", "sandbox": true, "apiKey": "vxk_test_…", "consoleUrl": "https://api.hcloud.fr/api/sandbox/console/o.…" }

POST /api/org/sandboxes/{id}/login-link ouvre son panneau ; trois comptes d'essai au plus ; DELETE /api/org/sandboxes/{id} le supprime.

La console d'essai

L'adresse consoleUrl (lien secret, sans connexion) affiche tout ce qui aurait eu lieu (e-mails avec leur texte, SMS, appels, enregistrements DNS…) et les démarches à valider :

Démarche Boutons
Portabilité Signer le mandat, Prise en charge, Fixer la date, Portage effectué (les numéros sont ajoutés au compte), Refuser
Identification Valider, Refuser
Commande de services Étape suivante (devis, commandé, planifié, actif), Annuler
Facture à régler (virement) Marquer payée
Appel entrant Simuler un appel (décroché ou manqué) sur un numéro du compte : journal des appels et webhook call.completed

Les mêmes actions existent en API, pour vos tests automatisés :

# état de la console
curl "https://api.hcloud.fr/api/sandbox/console/<jeton>/state"
# action : kind = porting | kyc | order | invoice ; action = sign | in_progress | schedule | done | reject | approve | next | cancel | paid
curl -X POST "https://api.hcloud.fr/api/sandbox/console/<jeton>/actions" -H "Content-Type: application/json" -d '{"kind":"porting","id":"<demande>","action":"sign"}'

Chaque étape déclenche les mêmes webhooks qu'en production (porting.status, sms.status…) : votre intégration se teste de bout en bout.

Simuler un appel entrant, remettre à zéro

# appel entrant simulé sur un numéro du compte d'essai (answered: false pour un appel manqué)
curl -X POST "https://api.hcloud.fr/api/sandbox/console/<jeton>/simulate" -H "Content-Type: application/json" -d '{"number":"+33199000000","from":"+33612345678","answered":true,"durationSec":35}'

POST …/sandboxes/{id}/reset remet le compte dans son état d'origine (données fictives recréées) en gardant la même clé et la même console : pratique entre deux séries de tests. Un compte d'essai sans aucune utilisation pendant 90 jours est supprimé.

Limites

  • L'assistant IA de création de scénarios n'est pas disponible (créez le scénario avec POST /api/centrex/flows).
  • Les appels ne pouvant pas avoir lieu, les statistiques ne contiennent que l'historique fictif et les appels lancés par l'API.
  • Un compte d'essai ne crée pas d'autre compte d'essai.

Avec une clé vxk_test_…, GET /api/v1/numbers/available ne propose que des numéros fictifs, POST /api/v1/numbers les attribue, et POST /api/v1/porting n'accepte que des numéros fictifs.

Référence complète, tirée du code de la plateforme : chaque champ indiqué est celui réellement vérifié par l’API.

SMS

Envoi de SMS (POST /api/v1/sms), suivi de remise (webhook `sms.status` ou GET /api/v1/sms/{id}), crédits : forfait du mois, solde, puis SMS au comptage. Voir le guide « Envoyer un SMS ».

GET/api/v1/sms#

Liste des SMS (filtres : status, to, tag, since)

Paramètres de requête

ChampTypeDétails
pageentier1 au moins · par défaut 1
pageSizeentier100 au plus
statustexte
totexte
tagtexte
sincetextedate et heure ISO 8601
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/sms" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "items": [
    {
      "id": "…",
      "to": "+33612345678",
      "text": "…"
    }
  ],
  "total": 1,
  "page": 1
}

Champs de la réponse

ChampTypeDétails
itemsliste de objet
items[].idtexte
items[].totexteNuméro E.164
items[].texttexte
items[].status"queued" | "sent" | "delivered" | "failed"queued : en file ; sent : accepté par l’opérateur ; delivered : remis ; failed : échec
items[].providerStatustexte ou nullDernier état du fournisseur : accepted, sent, delivered, hard_bounce…
items[].messageIdtexte ou nullIdentifiant de suivi du message chez l’opérateur SMS
items[].sendertexte ou null
items[].tagtexte ou null
items[].type"transactional" | "marketing" | null
items[].segmentsentierCrédits consommés
items[].channeltexte ou null
items[].errortexte ou null
items[].createdAttextedate et heure ISO 8601
items[].sentAttexte ou null
items[].deliveredAttexte ou null
items[].eventsliste de objet
items[].events[].statustexte
items[].events[].attextedate et heure ISO 8601
totalentier
pageentier
POST/api/v1/sms#

Envoyer un SMS : mis en file, part en quelques secondes ; statuts par webhook sms.status ou GET /api/v1/sms/{id}

Corps (JSON)

ChampTypeDétails
to requistexteMobile du destinataire : 0612345678, 06 12 34 56 78 ou +33612345678 (mobiles français, 06 et 07)
text requistexte160 caractères par SMS (153 par partie au-delà) ; 70 (67) avec ê, â, î, ô, û, ç minuscule ou un emoji — 1000 caractères au plus
sendertexteExpéditeur affiché (3 à 11 lettres/chiffres) ; refusé s’il figure sur une liste de blocage
tagtexteÉtiquette libre, renvoyée dans les statuts
type"transactional" | "marketing"par défaut "transactional"
channel"sms" | "whatsapp" | "auto"auto : WhatsApp si possible, sinon SMS — par défaut "sms"
inviteTexttextechannel whatsapp ou auto : SMS d’invitation envoyé si WhatsApp refuse un premier contact ({{whatsapp_lien}} y insère le lien) — 600 caractères au plus
statusCallbacktexteAdresse prévenue à chaque changement de statut de ce message (JSON signé : voir /api/v1/sms/callback-secret) — adresse web
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/sms" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+33612345678","text":"…"}'

Réponse

{
  "id": "…",
  "to": "+33612345678",
  "text": "…"
}

Champs de la réponse

ChampTypeDétails
idtexte
totexteNuméro E.164
texttexte
status"queued" | "sent" | "delivered" | "failed"queued : en file ; sent : accepté par l’opérateur ; delivered : remis ; failed : échec
providerStatustexte ou nullDernier état du fournisseur : accepted, sent, delivered, hard_bounce…
messageIdtexte ou nullIdentifiant de suivi du message chez l’opérateur SMS
sendertexte ou null
tagtexte ou null
type"transactional" | "marketing" | null
segmentsentierCrédits consommés
channeltexte ou null
errortexte ou null
createdAttextedate et heure ISO 8601
sentAttexte ou null
deliveredAttexte ou null
eventsliste de objet
events[].statustexte
events[].attextedate et heure ISO 8601
GET/api/v1/sms/{id}#

Un SMS et ses événements de remise (accepted, sent, delivered…)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant ou messageId du fournisseur
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/sms/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "to": "+33612345678",
  "text": "…"
}

Champs de la réponse

ChampTypeDétails
idtexte
totexteNuméro E.164
texttexte
status"queued" | "sent" | "delivered" | "failed"queued : en file ; sent : accepté par l’opérateur ; delivered : remis ; failed : échec
providerStatustexte ou nullDernier état du fournisseur : accepted, sent, delivered, hard_bounce…
messageIdtexte ou nullIdentifiant de suivi du message chez l’opérateur SMS
sendertexte ou null
tagtexte ou null
type"transactional" | "marketing" | null
segmentsentierCrédits consommés
channeltexte ou null
errortexte ou null
createdAttextedate et heure ISO 8601
sentAttexte ou null
deliveredAttexte ou null
eventsliste de objet
events[].statustexte
events[].attextedate et heure ISO 8601
GET/api/v1/sms/balance#

Crédits SMS : forfait du mois et solde à vie

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/sms/balance" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "monthlyLimit": 1,
  "monthlyUsed": 1,
  "monthlyLeft": 1
}

Champs de la réponse

ChampTypeDétails
monthlyLimitentierForfait du mois (remis à zéro chaque mois)
monthlyUsedentier
monthlyLeftentier
balanceentierSolde à vie (sans expiration), utilisé après le forfait du mois
availableentierForfait restant + solde
meteredobjetSMS au comptage : facturés à l’unité en fin de mois une fois le forfait et le solde épuisés
metered.enabledbooléen
metered.unitPriceCentsnombreTarif HT d’un SMS en centimes (5.8 = 0,058 €)
metered.capentier ou nullPlafond mensuel (null : sans plafond)
metered.monthUsedentier
metered.monthCentsentierMontant HT du mois
metered.leftentier ou nullSMS au comptage encore autorisés ce mois-ci
GET/api/v1/sms/callback-secret#

Secret de signature des rappels de statut propres à un message (statusCallback) : X-VoxNova-Signature: sha256=<HMAC-SHA256 du corps>

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/sms/callback-secret" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "secret": "…"
}

Champs de la réponse

ChampTypeDétails
secrettexte

Messagerie vocale

Messages vocaux : liste, transcription, écoute par lien signé, lu / non lu, suppression ; webhook `voicemail.new`.

GET/api/v1/voicemail#

Boîtes vocales et messages (filtres : extension, unread)

Paramètres de requête

ChampTypeDétails
extensiontexteIdentifiant ou numéro du poste
unreadbooléen
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/voicemail" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "boxes": [
    {
      "extensionId": "…",
      "number": "+33612345678",
      "name": "Julie Martin"
    }
  ],
  "unread": 1
}

Champs de la réponse

ChampTypeDétails
boxesliste de objet
boxes[].extensionIdtexte
boxes[].numbertexte
boxes[].nametexte
boxes[].emailtexte ou null
boxes[].unreadentier
boxes[].messagesliste de objet
boxes[].messages[].uuidtexte
boxes[].messages[].createdAttextedate et heure ISO 8601
boxes[].messages[].readbooléen
boxes[].messages[].foldertexte
boxes[].messages[].callerNametexte
boxes[].messages[].callerNumbertexte
boxes[].messages[].secondsentier
boxes[].messages[].transcripttexte ou nullTranscription (option IA)
unreadentier
GET/api/v1/voicemail/{ext}/{uuid}#

Un message

Paramètres de chemin

ChampTypeDétails
ext requistexteIdentifiant ou numéro du poste
uuid requistexteIdentifiant du message
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/voicemail/{ext}/{uuid}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "uuid": "…",
  "createdAt": "2026-12-01T09:00:00Z",
  "read": true
}

Champs de la réponse

ChampTypeDétails
uuidtexte
createdAttextedate et heure ISO 8601
readbooléen
foldertexte
callerNametexte
callerNumbertexte
secondsentier
transcripttexte ou nullTranscription (option IA)
DELETE/api/v1/voicemail/{ext}/{uuid}#

Supprimer un message

Paramètres de chemin

ChampTypeDétails
ext requistexteIdentifiant ou numéro du poste
uuid requistexteIdentifiant du message
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/voicemail/{ext}/{uuid}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/voicemail/{ext}/{uuid}/read#

Marquer lu / non lu

Paramètres de chemin

ChampTypeDétails
ext requistextePoste
uuid requistexteMessage

Corps (JSON)

ChampTypeDétails
read requisbooléen
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/voicemail/{ext}/{uuid}/read" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"read":true}'

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/voicemail/{ext}/{uuid}/url#

Lien d’écoute signé (5 min, lecture en continu) ; marque le message lu

Paramètres de chemin

ChampTypeDétails
ext requistextePoste
uuid requistexteMessage
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/voicemail/{ext}/{uuid}/url" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "url": "https://exemple.fr/webhook",
  "expiresIn": 1
}

Champs de la réponse

ChampTypeDétails
urltexte
expiresInentier

Portabilité

Demande de portabilité de numéros, suivi des états (webhook `porting.status`), mandat à signer, documents, annulation.

GET/api/v1/porting#

Demandes de portabilité (filtres : status, number)

Paramètres de requête

ChampTypeDétails
pageentier1 au moins · par défaut 1
pageSizeentier100 au plus
statustexte
numbertexte
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/porting" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "items": [
    {
      "id": "…",
      "status": "AWAITING_SIGNATURE",
      "statusLabel": "…"
    }
  ],
  "total": 1,
  "page": 1
}

Champs de la réponse

ChampTypeDétails
itemsliste de objet
items[].idtexte
items[].status"AWAITING_SIGNATURE" | "SUBMITTED" | "IN_PROGRESS" | "SCHEDULED" | "DONE" | "REJECTED" | "CANCELLED"AWAITING_SIGNATURE : mandat à signer ; SUBMITTED : reçue ; IN_PROGRESS : en traitement ; SCHEDULED : date de portage fixée ; DONE : numéros portés (ajoutés au compte) ; REJECTED : refusée ; CANCELLED : annulée
items[].statusLabeltexte
items[].numbersliste de texte
items[].numberType"FIXE" | "MOBILE"
items[].holderNametexte
items[].sirettexte ou null
items[].addresstexte ou null
items[].currentOperatortexte
items[].operatorsliste de objetOpérateur actuel de chaque numéro (bases de portabilité)
items[].riotexte ou null
items[].desiredDatetexte ou nulldate et heure ISO 8601
items[].scheduledAttexte ou nullDate de portage fixée — date et heure ISO 8601
items[].contactNametexte
items[].contactEmailtexte
items[].contactPhonetexte ou null
items[].notestexte
items[].messagetexte ou nullMessage de l’équipe (motif de refus, précisions)
items[].mandateSignedbooléen
items[].awaitingSignaturebooléen
items[].filesliste de objet
items[].files[].indexentier
items[].files[].nametexte
items[].files[].sizeentier
items[].files[].typetexte
items[].historyliste de objet
items[].history[].attexte
items[].history[].statustexte
items[].history[].notetexte ou null
items[].createdAttextedate et heure ISO 8601
items[].updatedAttextedate et heure ISO 8601
totalentier
pageentier
POST/api/v1/porting#

Demander la portabilité de numéros (JSON avec documents en base64, ou multipart : champ data + fichiers)

Corps (JSON)

ChampTypeDétails
numbers requisliste de texteNuméros à porter (01 23 45 67 89, +33…), 200 au plus
numberType"FIXE" | "MOBILE"par défaut "FIXE"
holderName requistexteTitulaire de la ligne chez l’opérateur actuel
sirettexte14 chiffres (professionnels)
addresstexte
currentOperatortexteFacultatif : relevé automatiquement dans les bases de portabilité
riotexteObligatoire pour les mobiles : 12 caractères (3179 depuis la ligne). La clé est vérifiée pour un numéro unique.
desiredDatetextedate et heure ISO 8601
contactName requistexte
contactEmail requistextee-mail
contactPhonetexte
notestexte
documentsliste de objetFacture récente, mandat signé… (PDF, PNG, JPEG, WebP ; 10 Mo). Inutiles quand le mandat est signé en ligne (`GET /api/v1/porting/config` : esign). — 5 éléments au plus
documents[].name requistexte
documents[].type requistexte
documents[].content requistexteContenu en base64
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/porting" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["…"],"holderName":"Julie Martin","contactName":"Julie Martin","contactEmail":"julie.martin@exemple.fr"}'

Réponse

{
  "id": "…",
  "status": "AWAITING_SIGNATURE",
  "statusLabel": "…"
}

Champs de la réponse

ChampTypeDétails
idtexte
status"AWAITING_SIGNATURE" | "SUBMITTED" | "IN_PROGRESS" | "SCHEDULED" | "DONE" | "REJECTED" | "CANCELLED"AWAITING_SIGNATURE : mandat à signer ; SUBMITTED : reçue ; IN_PROGRESS : en traitement ; SCHEDULED : date de portage fixée ; DONE : numéros portés (ajoutés au compte) ; REJECTED : refusée ; CANCELLED : annulée
statusLabeltexte
numbersliste de texte
numberType"FIXE" | "MOBILE"
holderNametexte
sirettexte ou null
addresstexte ou null
currentOperatortexte
operatorsliste de objetOpérateur actuel de chaque numéro (bases de portabilité)
riotexte ou null
desiredDatetexte ou nulldate et heure ISO 8601
scheduledAttexte ou nullDate de portage fixée — date et heure ISO 8601
contactNametexte
contactEmailtexte
contactPhonetexte ou null
notestexte
messagetexte ou nullMessage de l’équipe (motif de refus, précisions)
mandateSignedbooléen
awaitingSignaturebooléen
filesliste de objet
files[].indexentier
files[].nametexte
files[].sizeentier
files[].typetexte
historyliste de objet
history[].attexte
history[].statustexte
history[].notetexte ou null
createdAttextedate et heure ISO 8601
updatedAttextedate et heure ISO 8601
GET/api/v1/porting/{id}#

Une demande : état, historique, documents

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/porting/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "status": "AWAITING_SIGNATURE",
  "statusLabel": "…"
}

Champs de la réponse

ChampTypeDétails
idtexte
status"AWAITING_SIGNATURE" | "SUBMITTED" | "IN_PROGRESS" | "SCHEDULED" | "DONE" | "REJECTED" | "CANCELLED"AWAITING_SIGNATURE : mandat à signer ; SUBMITTED : reçue ; IN_PROGRESS : en traitement ; SCHEDULED : date de portage fixée ; DONE : numéros portés (ajoutés au compte) ; REJECTED : refusée ; CANCELLED : annulée
statusLabeltexte
numbersliste de texte
numberType"FIXE" | "MOBILE"
holderNametexte
sirettexte ou null
addresstexte ou null
currentOperatortexte
operatorsliste de objetOpérateur actuel de chaque numéro (bases de portabilité)
riotexte ou null
desiredDatetexte ou nulldate et heure ISO 8601
scheduledAttexte ou nullDate de portage fixée — date et heure ISO 8601
contactNametexte
contactEmailtexte
contactPhonetexte ou null
notestexte
messagetexte ou nullMessage de l’équipe (motif de refus, précisions)
mandateSignedbooléen
awaitingSignaturebooléen
filesliste de objet
files[].indexentier
files[].nametexte
files[].sizeentier
files[].typetexte
historyliste de objet
history[].attexte
history[].statustexte
history[].notetexte ou null
createdAttextedate et heure ISO 8601
updatedAttextedate et heure ISO 8601
POST/api/v1/porting/{id}/cancel#

Annuler une demande (états : mandat à signer, reçue, en cours ; plus possible une fois la date de portage fixée)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/porting/{id}/cancel" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "status": "AWAITING_SIGNATURE",
  "statusLabel": "…"
}

Champs de la réponse

ChampTypeDétails
idtexte
status"AWAITING_SIGNATURE" | "SUBMITTED" | "IN_PROGRESS" | "SCHEDULED" | "DONE" | "REJECTED" | "CANCELLED"AWAITING_SIGNATURE : mandat à signer ; SUBMITTED : reçue ; IN_PROGRESS : en traitement ; SCHEDULED : date de portage fixée ; DONE : numéros portés (ajoutés au compte) ; REJECTED : refusée ; CANCELLED : annulée
statusLabeltexte
numbersliste de texte
numberType"FIXE" | "MOBILE"
holderNametexte
sirettexte ou null
addresstexte ou null
currentOperatortexte
operatorsliste de objetOpérateur actuel de chaque numéro (bases de portabilité)
riotexte ou null
desiredDatetexte ou nulldate et heure ISO 8601
scheduledAttexte ou nullDate de portage fixée — date et heure ISO 8601
contactNametexte
contactEmailtexte
contactPhonetexte ou null
notestexte
messagetexte ou nullMessage de l’équipe (motif de refus, précisions)
mandateSignedbooléen
awaitingSignaturebooléen
filesliste de objet
files[].indexentier
files[].nametexte
files[].sizeentier
files[].typetexte
historyliste de objet
history[].attexte
history[].statustexte
history[].notetexte ou null
createdAttextedate et heure ISO 8601
updatedAttextedate et heure ISO 8601
GET/api/v1/porting/{id}/files/{index}#

Télécharger un document

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
index requistextePosition du document
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/porting/{id}/files/{index}" \
  -H "Authorization: Bearer vxk_…"
GET/api/v1/porting/{id}/sign#

Lien de signature du mandat (état AWAITING_SIGNATURE)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/porting/{id}/sign" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "url": "https://exemple.fr/webhook"
}

Champs de la réponse

ChampTypeDétails
urltexteadresse web
GET/api/v1/porting/config#

Mandat signé en ligne (esign) et limites des documents

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/porting/config" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "esign": true,
  "documents": {}
}

Champs de la réponse

ChampTypeDétails
esignbooléen
documentsobjet
GET/api/v1/porting/operator#

Opérateur actuel d’un numéro (bases de portabilité)

Paramètres de requête

ChampTypeDétails
number requistexte
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/porting/operator" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "operator": "…",
  "inProgress": true
}

Champs de la réponse

ChampTypeDétails
operatortexte ou null
inProgressbooléen ou null

Webhooks

Événements signés : `call.completed`, `sms.status`, `porting.status`. En-têtes `X-VoxNova-Event` et `X-VoxNova-Signature: sha256=<hmac-sha256 du corps avec le secret>`.

GET/api/v1/webhooks#

Webhooks de l’entreprise

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/webhooks" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "id": "…",
    "url": "https://exemple.fr/webhook",
    "events": [
      "call.completed"
    ]
  }
]

Champs de la réponse

ChampTypeDétails
idtexte
urltexteadresse web
eventsliste de "call.completed" | "voicemail.new" | "sms.status" | "porting.status" | "number.assigned" | "invoice.created" | "invoice.paid"
enabledbooléen
lastStatustexte ou null
secrettexteFourni une seule fois, à la création
POST/api/v1/webhooks#

Créer un webhook (le secret de signature est renvoyé une fois)

Corps (JSON)

ChampTypeDétails
url requistexteadresse web
eventsliste de "call.completed" | "voicemail.new" | "sms.status" | "porting.status" | "number.assigned" | "invoice.created" | "invoice.paid"
enabledbooléen
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/webhooks" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemple.fr/webhook"}'

Réponse

{
  "id": "…",
  "url": "https://exemple.fr/webhook",
  "events": [
    "call.completed"
  ]
}

Champs de la réponse

ChampTypeDétails
idtexte
urltexteadresse web
eventsliste de "call.completed" | "voicemail.new" | "sms.status" | "porting.status" | "number.assigned" | "invoice.created" | "invoice.paid"
enabledbooléen
lastStatustexte ou null
secrettexteFourni une seule fois, à la création
PATCH/api/v1/webhooks/{id}#

Modifier

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant

Corps (JSON)

ChampTypeDétails
url requistexteadresse web
eventsliste de "call.completed" | "voicemail.new" | "sms.status" | "porting.status" | "number.assigned" | "invoice.created" | "invoice.paid"
enabledbooléen
Exemple
curl -X PATCH "https://api.hcloud.fr/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemple.fr/webhook"}'

Réponse

{
  "id": "…",
  "url": "https://exemple.fr/webhook",
  "events": [
    "call.completed"
  ]
}

Champs de la réponse

ChampTypeDétails
idtexte
urltexteadresse web
eventsliste de "call.completed" | "voicemail.new" | "sms.status" | "porting.status" | "number.assigned" | "invoice.created" | "invoice.paid"
enabledbooléen
lastStatustexte ou null
secrettexteFourni une seule fois, à la création
DELETE/api/v1/webhooks/{id}#

Supprimer

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen

Appels

GET/api/v1/call-context/{token}#

Contexte d’un appel passé par un scénario : fiche CRM, variables (code tapé, client identifié…), appelant, numéro appelé. Pour un softphone intégré à votre logiciel (webphone : option resolveContext).

Paramètres de chemin

ChampTypeDétails
token requistexteJeton de l’appel (en-tête SIP X-VX-Ctx reçu par le softphone)
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/call-context/{token}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "token": "…",
  "caller": "+33612345678",
  "did": "…"
}

Champs de la réponse

ChampTypeDétails
tokentexte
callertexte
didtexte
crmUrltexte ou null
openOnAnswerbooléen
varsobjet
POST/api/v1/callbacks#

Demander à être rappelé (file d’attente ou poste)

Corps (JSON)

ChampTypeDétails
phone requistexte6 à 25 caractères
nametexte100 caractères au plus
notetexte300 caractères au plus
targetType requis"queue" | "extension"
targetId requistexte
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/callbacks" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+33612345678","targetType":"queue","targetId":"…"}'

Réponse

{}
GET/api/v1/callbacks/{id}#

État d’une demande de rappel

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/callbacks/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}
GET/api/v1/calls#

Appels en cours

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/calls" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}
POST/api/v1/calls#

Passer un appel programmable

Corps (JSON)

ChampTypeDétails
to requistexteEndpoint (numéro interne ou id) ou numéro de téléphone
fromtexteUn de vos numéros (présentation)
applicationId requistexte
urltexteRemplace voiceUrl pour cet appel — adresse web
timeoutentierpar défaut 30
varsobjetVariables transmises à chaque webhook (vars)
statusCallbacktextePrévenue à la fin de cet appel (remplace statusCallbackUrl de l’application) — adresse web
twimltexteInstructions TwiML en ligne (<Response>…</Response>), à la place d’une adresse
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/calls" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+33612345678","applicationId":"…"}'

Réponse

{
  "callId": "…",
  "status": "…"
}

Champs de la réponse

ChampTypeDétails
callIdtexte
statustexte
GET/api/v1/calls/{id}#

État d’un appel (en cours ou terminé)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/calls/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}
POST/api/v1/calls/{id}/hangup#

Raccrocher

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/calls/{id}/hangup" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/calls/{id}/redirect#

Reprendre la main (nouvelles instructions)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant

Corps (JSON)

ChampTypeDétails
urltexte
applicationIdtexte
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/calls/{id}/redirect" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemple.fr/webhook","applicationId":"…"}'

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
GET/api/v1/calls/live#

Appels en cours (détail par canal)

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/calls/live" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "online": true,
  "calls": [
    {}
  ]
}

Champs de la réponse

ChampTypeDétails
onlinebooléen
callsliste de objet
GET/api/v1/cdr#

Journal des appels

Paramètres de requête

ChampTypeDétails
pageentier1 au moins · par défaut 1
pageSizeentierde 1 à 100 · par défaut 25
sincetextedate et heure ISO 8601
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/cdr" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}
POST/api/v1/click-to-call#

Clic pour appeler : le poste sonne, puis le numéro est appelé au décroché (droits du poste)

Corps (JSON)

ChampTypeDétails
to requistexteNuméro à appeler (chiffres, +, *, #)
extensiontextePoste qui sonne : identifiant ou numéro interne (ou « user »)
usertexteUtilisateur dont le poste sonne : identifiant ou e-mail (au lieu de « extension »)
autoAnswerbooléenDécroché automatique du poste (applications VoxNova, téléphones de bureau compatibles) — par défaut false
labeltexteNom affiché sur le poste qui sonne
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/click-to-call" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"0612345678"}'

Réponse

{
  "callId": "…",
  "status": "ringing",
  "extension": "…"
}

Champs de la réponse

ChampTypeDétails
callIdtexteUUID
status"ringing" | "dialing" | "in_progress" | "completed" | "not_answered" | "failed"
extensiontexte
totexte
durationSecentier
hangupCausetexte
GET/api/v1/click-to-call/{id}#

État : ringing (le poste sonne), dialing (numéro composé), in_progress, completed, not_answered, failed

Paramètres de chemin

ChampTypeDétails
id requistextecallId renvoyé au lancement
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/click-to-call/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "callId": "…",
  "status": "ringing",
  "extension": "…"
}

Champs de la réponse

ChampTypeDétails
callIdtexteUUID
status"ringing" | "dialing" | "in_progress" | "completed" | "not_answered" | "failed"
extensiontexte
totexte
durationSecentier
hangupCausetexte
DELETE/api/v1/click-to-call/{id}#

Raccrocher (qu’il sonne encore ou soit en cours)

Paramètres de chemin

ChampTypeDétails
id requistextecallId renvoyé au lancement
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/click-to-call/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "callId": "…",
  "cancelled": true
}

Champs de la réponse

ChampTypeDétails
callIdtexte
cancelledbooléen

Applications

GET/api/v1/applications#

Liste des applications

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/applications" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "id": "…",
    "name": "Julie Martin",
    "format": "json"
  }
]

Champs de la réponse

ChampTypeDétails
idtexte
nametexte
format"json" | "twiml"
voiceUrltexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
signingSecrettexte
createdAttextedate et heure ISO 8601
POST/api/v1/applications#

Créer une application

Corps (JSON)

ChampTypeDétails
name requistexte
voiceUrl requistexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
format"json" | "twiml"json : requêtes JSON signées X-VoxNova-Signature ; twiml : requêtes au format Twilio (formulaire, X-Twilio-Signature). Les réponses TwiML (XML) sont acceptées dans les deux cas. — par défaut "json"
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/applications" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Julie Martin","voiceUrl":"https://exemple.fr/webhook"}'

Réponse

{
  "id": "…",
  "name": "Julie Martin",
  "format": "json"
}

Champs de la réponse

ChampTypeDétails
idtexte
nametexte
format"json" | "twiml"
voiceUrltexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
signingSecrettexte
createdAttextedate et heure ISO 8601
GET/api/v1/applications/{id}#

Détail

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/applications/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "name": "Julie Martin",
  "format": "json"
}

Champs de la réponse

ChampTypeDétails
idtexte
nametexte
format"json" | "twiml"
voiceUrltexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
signingSecrettexte
createdAttextedate et heure ISO 8601
PATCH/api/v1/applications/{id}#

Modifier

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant

Corps (JSON)

ChampTypeDétails
name requistexte
voiceUrl requistexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
format"json" | "twiml"json : requêtes JSON signées X-VoxNova-Signature ; twiml : requêtes au format Twilio (formulaire, X-Twilio-Signature). Les réponses TwiML (XML) sont acceptées dans les deux cas. — par défaut "json"
Exemple
curl -X PATCH "https://api.hcloud.fr/api/v1/applications/{id}" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Julie Martin","voiceUrl":"https://exemple.fr/webhook"}'

Réponse

{
  "id": "…",
  "name": "Julie Martin",
  "format": "json"
}

Champs de la réponse

ChampTypeDétails
idtexte
nametexte
format"json" | "twiml"
voiceUrltexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
signingSecrettexte
createdAttextedate et heure ISO 8601
DELETE/api/v1/applications/{id}#

Supprimer (les numéros reliés sont détachés)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/applications/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/applications/{id}/secret#

Nouvelle clé de signature

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/applications/{id}/secret" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "name": "Julie Martin",
  "format": "json"
}

Champs de la réponse

ChampTypeDétails
idtexte
nametexte
format"json" | "twiml"
voiceUrltexteadresse web
fallbackUrltexte ou null
statusCallbackUrltexte ou null
signingSecrettexte
createdAttextedate et heure ISO 8601

Audio

GET/api/v1/audio#

Fichiers audio

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/audio" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {}
]
POST/api/v1/audio#

Envoyer un fichier audio (multipart, champ file)

Corps (multipart/form-data)

ChampTypeDétails
filefichier
nametexte
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/audio" \
  -H "Authorization: Bearer vxk_…" \
  -F "file=@fichier" \
  -F "name=…"

Compte

GET/api/v1/account#

Compte, limites et utilisation

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/account" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}
POST/api/v1/login-links#

Lien de connexion automatique au panneau de votre entreprise (usage unique, 60 s)

Corps (JSON)

ChampTypeDétails
usertexteE-mail ou identifiant d’un utilisateur du client (défaut : son administrateur)
nexttextePage d’arrivée dans le panneau : chemin relatif (ex. /admin)
ttlSecondsentierde 10 à 900 · par défaut 60
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/login-links" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"user":"…","next":"…","ttlSeconds":60}'

Réponse

{
  "url": "https://exemple.fr/webhook",
  "expiresAt": "2026-12-01T09:00:00Z",
  "expiresIn": 1
}

Champs de la réponse

ChampTypeDétails
urltexteAdresse à usage unique : ouvre le panneau connecté
expiresAttextedate et heure ISO 8601
expiresInentier
userobjet
user.idtexte
user.emailtexte
user.roletexte
GET/api/v1/usage#

Consommation du mois en cours (numéros, minutes)

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/usage" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}

Consultation de numéro

GET/api/v1/lookup/{number}#

Consulter un numéro : validité, pays, type de ligne (mobile, fixe, VoIP, gratuit, surtaxé, objets connectés), formats national et international

Calculé à partir du plan de numérotation, sans service extérieur ni enregistrement. L’opérateur n’est pas indiqué (carrier: null) : avec la portabilité, l’opérateur d’origine ne dit pas qui exploite le numéro.

Paramètres de chemin

ChampTypeDétails
number requistexteNuméro (national ou E.164 encodé : %2B33…)
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/lookup/{number}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "input": "…",
  "valid": true,
  "number": "+33612345678"
}

Champs de la réponse

ChampTypeDétails
inputtexte
validbooléen
numbertexte ou null
countrytexte ou null
type"mobile" | "fixed" | "voip" | "tollfree" | "premium" | "shared_cost" | "m2m" | "unknown"
detailtexte
nationalFormattexte ou null
internationalFormattexte ou null
carriernull

Endpoints

GET/api/v1/endpoints#

Liste des endpoints SIP (état d’enregistrement)

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/endpoints" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "id": "…",
    "number": "+33612345678",
    "name": "Julie Martin"
  }
]

Champs de la réponse

ChampTypeDétails
idtexte
numbertexteNuméro interne (identifiant SIP)
nametexte
enabledbooléen
applicationIdtexte ou nullApplication qui route les appels émis par cet endpoint
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
sipobjet
sip.usernametexte
sip.authUsernametexte
sip.passwordtexte
sip.domaintexte
sip.servertexte
sip.portentier
sip.transportsliste de texte
sip.outboundProxytexte
webphoneobjet ou nullConfiguration prête pour @voxnova/webphone (softphone navigateur) : wsServers, uri, authorizationUser, password, realm, iceServers
webphone.wsServersliste de texte
webphone.uritexte
webphone.authorizationUsertexte
webphone.passwordtexte
webphone.realmtexte
webphone.displayNametexte
webphone.registerExpiresentier
webphone.iceServersliste de objet
registrationsliste de objet
registrations[].usertexte
registrations[].agenttexte
registrations[].iptexte
registrations[].porttexte
registrations[].statustexte
registrations[].contacttexte
POST/api/v1/endpoints#

Créer un endpoint SIP

Corps (JSON)

ChampTypeDétails
numbertextePar défaut : premier numéro libre à partir de 1000 — format ^\d{2,6}$
name requistexte
applicationIdtexte ou null
passwordtextePar défaut : généré — 12 caractères au moins
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
enabledbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/endpoints" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Julie Martin"}'

Réponse

{
  "id": "…",
  "number": "+33612345678",
  "name": "Julie Martin"
}

Champs de la réponse

ChampTypeDétails
idtexte
numbertexteNuméro interne (identifiant SIP)
nametexte
enabledbooléen
applicationIdtexte ou nullApplication qui route les appels émis par cet endpoint
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
sipobjet
sip.usernametexte
sip.authUsernametexte
sip.passwordtexte
sip.domaintexte
sip.servertexte
sip.portentier
sip.transportsliste de texte
sip.outboundProxytexte
webphoneobjet ou nullConfiguration prête pour @voxnova/webphone (softphone navigateur) : wsServers, uri, authorizationUser, password, realm, iceServers
webphone.wsServersliste de texte
webphone.uritexte
webphone.authorizationUsertexte
webphone.passwordtexte
webphone.realmtexte
webphone.displayNametexte
webphone.registerExpiresentier
webphone.iceServersliste de objet
registrationsliste de objet
registrations[].usertexte
registrations[].agenttexte
registrations[].iptexte
registrations[].porttexte
registrations[].statustexte
registrations[].contacttexte
GET/api/v1/endpoints/{id}#

Détail avec identifiants SIP et enregistrements

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant ou numéro interne
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/endpoints/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "number": "+33612345678",
  "name": "Julie Martin"
}

Champs de la réponse

ChampTypeDétails
idtexte
numbertexteNuméro interne (identifiant SIP)
nametexte
enabledbooléen
applicationIdtexte ou nullApplication qui route les appels émis par cet endpoint
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
sipobjet
sip.usernametexte
sip.authUsernametexte
sip.passwordtexte
sip.domaintexte
sip.servertexte
sip.portentier
sip.transportsliste de texte
sip.outboundProxytexte
webphoneobjet ou nullConfiguration prête pour @voxnova/webphone (softphone navigateur) : wsServers, uri, authorizationUser, password, realm, iceServers
webphone.wsServersliste de texte
webphone.uritexte
webphone.authorizationUsertexte
webphone.passwordtexte
webphone.realmtexte
webphone.displayNametexte
webphone.registerExpiresentier
webphone.iceServersliste de objet
registrationsliste de objet
registrations[].usertexte
registrations[].agenttexte
registrations[].iptexte
registrations[].porttexte
registrations[].statustexte
registrations[].contacttexte
PATCH/api/v1/endpoints/{id}#

Modifier

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant ou numéro interne

Corps (JSON)

ChampTypeDétails
numbertextePar défaut : premier numéro libre à partir de 1000 — format ^\d{2,6}$
name requistexte
applicationIdtexte ou null
passwordtextePar défaut : généré — 12 caractères au moins
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
enabledbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
Exemple
curl -X PATCH "https://api.hcloud.fr/api/v1/endpoints/{id}" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Julie Martin"}'

Réponse

{
  "id": "…",
  "number": "+33612345678",
  "name": "Julie Martin"
}

Champs de la réponse

ChampTypeDétails
idtexte
numbertexteNuméro interne (identifiant SIP)
nametexte
enabledbooléen
applicationIdtexte ou nullApplication qui route les appels émis par cet endpoint
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
sipobjet
sip.usernametexte
sip.authUsernametexte
sip.passwordtexte
sip.domaintexte
sip.servertexte
sip.portentier
sip.transportsliste de texte
sip.outboundProxytexte
webphoneobjet ou nullConfiguration prête pour @voxnova/webphone (softphone navigateur) : wsServers, uri, authorizationUser, password, realm, iceServers
webphone.wsServersliste de texte
webphone.uritexte
webphone.authorizationUsertexte
webphone.passwordtexte
webphone.realmtexte
webphone.displayNametexte
webphone.registerExpiresentier
webphone.iceServersliste de objet
registrationsliste de objet
registrations[].usertexte
registrations[].agenttexte
registrations[].iptexte
registrations[].porttexte
registrations[].statustexte
registrations[].contacttexte
DELETE/api/v1/endpoints/{id}#

Supprimer

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant ou numéro interne
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/endpoints/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/endpoints/{id}/disconnect#

Déconnecter les appareils enregistrés

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/endpoints/{id}/disconnect" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/endpoints/{id}/password#

Générer un nouveau mot de passe SIP (déconnecte les appareils)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/endpoints/{id}/password" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "number": "+33612345678",
  "name": "Julie Martin"
}

Champs de la réponse

ChampTypeDétails
idtexte
numbertexteNuméro interne (identifiant SIP)
nametexte
enabledbooléen
applicationIdtexte ou nullApplication qui route les appels émis par cet endpoint
voicemailbooléen
callerIdtexte ou null
permission"INTERNAL" | "NATIONAL" | "INTERNATIONAL"
recordCallsbooléen
forwardobjet
forward.alwaystexte ou null
forward.busytexte ou null
forward.noAnswertexte ou null
forward.noAnswerSecondsentier
sipobjet
sip.usernametexte
sip.authUsernametexte
sip.passwordtexte
sip.domaintexte
sip.servertexte
sip.portentier
sip.transportsliste de texte
sip.outboundProxytexte
webphoneobjet ou nullConfiguration prête pour @voxnova/webphone (softphone navigateur) : wsServers, uri, authorizationUser, password, realm, iceServers
webphone.wsServersliste de texte
webphone.uritexte
webphone.authorizationUsertexte
webphone.passwordtexte
webphone.realmtexte
webphone.displayNametexte
webphone.registerExpiresentier
webphone.iceServersliste de objet
registrationsliste de objet
registrations[].usertexte
registrations[].agenttexte
registrations[].iptexte
registrations[].porttexte
registrations[].statustexte
registrations[].contacttexte
GET/api/v1/endpoints/{id}/registrations#

Appareils enregistrés

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/endpoints/{id}/registrations" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "user": "…",
    "agent": "…",
    "ip": "…"
  }
]

Champs de la réponse

ChampTypeDétails
usertexte
agenttexte
iptexte
porttexte
statustexte
contacttexte
GET/api/v1/extensions#

Postes de l’entreprise (identifiant, numéro interne, nom, actif)

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/extensions" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "id": "…",
    "number": "+33612345678",
    "displayName": "Julie Martin"
  }
]

Champs de la réponse

ChampTypeDétails
idtexte
numbertexte
displayNametexte
enabledbooléen

Enregistrements

GET/api/v1/recordings#

Enregistrements (instruction record)

Paramètres de requête

ChampTypeDétails
pageentier1 au moins · par défaut 1
pageSizeentierde 1 à 100 · par défaut 25
callIdtexte
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/recordings" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}
DELETE/api/v1/recordings/{id}#

Supprimer

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/recordings/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
POST/api/v1/recordings/{id}/url#

Lien d’écoute signé (5 min, lecture en continu)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/recordings/{id}/url" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "url": "https://exemple.fr/webhook",
  "expiresIn": 1
}

Champs de la réponse

ChampTypeDétails
urltexte
expiresInentier

Journal

GET/api/v1/logs#

Journal des requêtes webhook (7 jours)

Paramètres de requête

ChampTypeDétails
pageentier1 au moins · par défaut 1
pageSizeentierde 1 à 100 · par défaut 25
callIdtexte
applicationIdtexte
errorsbooléen
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/logs" \
  -H "Authorization: Bearer vxk_…"

Réponse

{}

Numéros

GET/api/v1/numbers#

Vos numéros

Exemple
curl -X GET "https://api.hcloud.fr/api/v1/numbers" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "number": "+33612345678",
    "label": "…",
    "destType": "…"
  }
]

Champs de la réponse

ChampTypeDétails
numbertexte
labeltexte
destTypetexte ou null
routingobjet ou null
monthlyPriceCentsentier
POST/api/v1/numbers#

Acheter un numéro

Corps (JSON)

ChampTypeDétails
number requistexte
applicationIdtexte
labeltexte
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/numbers" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"number":"+33612345678"}'

Réponse

{
  "number": "+33612345678",
  "label": "…",
  "destType": "…"
}

Champs de la réponse

ChampTypeDétails
numbertexte
labeltexte
destTypetexte ou null
routingobjet ou null
monthlyPriceCentsentier
PATCH/api/v1/numbers/{number}#

Router vers une application ou un endpoint

Paramètres de chemin

ChampTypeDétails
number requistexteNuméro E.164 (encodé : %2B33…)

Corps (JSON)

ChampTypeDétails
applicationIdtexte ou null
endpointIdtexte ou null
labeltexte
Exemple
curl -X PATCH "https://api.hcloud.fr/api/v1/numbers/{number}" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"applicationId":"…","endpointId":"…","label":"…"}'

Réponse

{
  "number": "+33612345678",
  "label": "…",
  "destType": "…"
}

Champs de la réponse

ChampTypeDétails
numbertexte
labeltexte
destTypetexte ou null
routingobjet ou null
monthlyPriceCentsentier
DELETE/api/v1/numbers/{number}#

Résilier (retour au stock)

Paramètres de chemin

ChampTypeDétails
number requistexteNuméro E.164 (encodé : %2B33…)
Exemple
curl -X DELETE "https://api.hcloud.fr/api/v1/numbers/{number}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "ok": true
}

Champs de la réponse

ChampTypeDétails
okbooléen
GET/api/v1/numbers/available#

Numéros disponibles

Paramètres de requête

ChampTypeDétails
containstexte
limitentier
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/numbers/available" \
  -H "Authorization: Bearer vxk_…"

Réponse

[
  {
    "number": "+33612345678",
    "label": "…",
    "destType": "…"
  }
]

Champs de la réponse

ChampTypeDétails
numbertexte
labeltexte
destTypetexte ou null
routingobjet ou null
monthlyPriceCentsentier

Vérification

POST/api/v1/verify#

Envoyer un code de vérification (SMS, WhatsApp, ou WhatsApp sinon SMS)

Code à usage unique tiré au hasard, jamais renvoyé ni stocké en clair. Nouveau code si une vérification est en cours pour ce numéro. Limites : 1 envoi / 30 s et 5 / heure par numéro, 1 000 / heure par entreprise ; numéros surtaxés refusés. Compté comme un SMS transactionnel (étiquette verify).

Corps (JSON)

ChampTypeDétails
to requistexteNuméro du destinataire
channel"sms" | "whatsapp" | "auto"par défaut "sms"
codeLengthentierde 4 à 10 · par défaut 6
ttlSecondsentierde 60 à 1800 · par défaut 600
brandtexteNom affiché dans le message (défaut : votre entreprise) — 30 caractères au plus
locale"fr" | "en"par défaut "fr"
tagtexte100 caractères au plus
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/verify" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+33612345678"}'

Réponse

{
  "id": "…",
  "to": "+33612345678",
  "channel": "sms"
}

Champs de la réponse

ChampTypeDétails
idtexte
totexte
channel"sms" | "whatsapp" | "auto"
status"pending" | "approved" | "expired" | "failed" | "canceled"
attemptsLeftentier
sendsentier
tagtexte ou null
expiresAttextedate et heure ISO 8601
approvedAttexte ou nulldate et heure ISO 8601
createdAttextedate et heure ISO 8601
GET/api/v1/verify/{id}#

État d’une vérification (pending, approved, expired, failed, canceled)

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X GET "https://api.hcloud.fr/api/v1/verify/{id}" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "to": "+33612345678",
  "channel": "sms"
}

Champs de la réponse

ChampTypeDétails
idtexte
totexte
channel"sms" | "whatsapp" | "auto"
status"pending" | "approved" | "expired" | "failed" | "canceled"
attemptsLeftentier
sendsentier
tagtexte ou null
expiresAttextedate et heure ISO 8601
approvedAttexte ou nulldate et heure ISO 8601
createdAttextedate et heure ISO 8601
POST/api/v1/verify/{id}/cancel#

Annuler une vérification en cours

Paramètres de chemin

ChampTypeDétails
id requistexteIdentifiant
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/verify/{id}/cancel" \
  -H "Authorization: Bearer vxk_…"

Réponse

{
  "id": "…",
  "to": "+33612345678",
  "channel": "sms"
}

Champs de la réponse

ChampTypeDétails
idtexte
totexte
channel"sms" | "whatsapp" | "auto"
status"pending" | "approved" | "expired" | "failed" | "canceled"
attemptsLeftentier
sendsentier
tagtexte ou null
expiresAttextedate et heure ISO 8601
approvedAttexte ou nulldate et heure ISO 8601
createdAttextedate et heure ISO 8601
POST/api/v1/verify/check#

Contrôler le code saisi

Par identifiant de vérification, ou par numéro (dernière vérification en cours). valid: true une seule fois ; 5 essais au plus, ensuite status: failed.

Corps (JSON)

ChampTypeDétails
idtexte
totexte
code requistexte
Exemple
curl -X POST "https://api.hcloud.fr/api/v1/verify/check" \
  -H "Authorization: Bearer vxk_…" \
  -H "Content-Type: application/json" \
  -d '{"code":"…"}'

Réponse

""