HTTP API v1

Introduction

L'API NoKYCNumber est organisée autour de REST. Nous utilisons des URLs orientées ressources prévisibles, acceptons et retournons des corps encodés en JSON, et utilisons des codes de réponse HTTP standard, l'authentification et les verbes.

URL de base

https://api.nokycnumber.com/v1/

Toutes les requêtes doivent être effectuées via HTTPS. Les appels en HTTP simple échoueront avec 301 Moved Permanently. Les requêtes sans authentification échoueront avec 401 Unauthenticated.

Convention JSON

• Toutes les requêtes avec un corps utilisent Content-Type: application/json. Les corps encodés en formulaire sont rejetés avec 415.
• Les horodatages sont retournés sous forme de chaînes ISO-8601 UTC (2026-04-26T14:23:00Z) et acceptés dans le même format.
• Les numéros de téléphone sont retournés en format E.164 avec un + initial (+33647189022) et formatés lisiblement dans display si pertinent.
• Les identifiants d'objets sont préfixés par leur ressource : num_, call_, sms_, vm_, whk_, evt_.

Authentification

Authentifiez-vous avec une clé bearer émise depuis votre panel sous Paramètres → Clés API. Deux types de clés existent :

• sk_live_… — secret côté serveur. Accès complet lecture/écriture. Ne jamais exposer dans le code client.
• pk_live_… — clé publique. Actuellement réservée ; non utilisée par aucun endpoint pour l'instant.

Format d'en-tête

Authorization: Bearer sk_live_5f3a8b2c4d1e9f6a7b8c2d1e9f6a7b8c
Content-Type: application/json
NoKYC-Version: 2026-04-01

Utilisez l'en-tête NoKYC-Version pour vous fixer à une version spécifique de l'API (voir Versionnement). Si omis, le défaut fixé de votre compte est utilisé.

Portées

Les clés sont émises avec l'une des trois portées :

Les clés peuvent être renouvelées à tout moment. Les anciennes clés restent valides 5 minutes après le renouvellement pour permettre un déploiement sans interruption.

Erreurs

L'API utilise des codes de statut HTTP conventionnels. 2xx signifie succès, 4xx signifie un problème avec votre requête, 5xx signifie que nous avons commis une erreur et nous voulons en être informés.

Enveloppe d'erreur

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter `country` is missing.",
    "param": "country",
    "request_id": "req_8a4c2f1e9b3d4a7c"
  }
}

Codes de statut

Types d'erreurs

• invalid_request_error — requête malformée, champs manquants, format invalide.
• authentication_error — problème de clé.
• authorization_error — problème de portée.
• rate_limit_error — ralentissez.
• api_error — erreur de notre côté. Réessayable.
• resource_error — l'état de la ressource empêche l'opération (ex. : appel depuis un numéro suspendu).
• upstream_error — l'opérateur ou le partenaire n'a pas répondu à temps.

Chaque réponse d'erreur inclut un request_id. Loggez-le toujours — c'est le seul moyen pour notre support de corréler votre appel avec notre trace interne.

Pagination

Les endpoints de liste utilisent une pagination par curseur en avant uniquement. Ils retournent jusqu'à limit objets (défaut 25, max 100) et un booléen has_more. Pour obtenir la page suivante, passez l'id du dernier objet en starting_after.

curl https://api.nokycnumber.com/v1/numbers?limit=10 \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "url": "/v1/numbers",
  "data": [
    { "id": "num_8a4c2f1e9b3d", "object": "number", "number": "+33647189022", … },
    { "id": "num_2k7m9p3w8x4t", "object": "number", "number": "+12025550143", … }
  ],
  "has_more": true,
  "next_cursor": "num_2k7m9p3w8x4t"
}

Les listes sont triées avec les objets les plus récemment créés en premier. La pagination en arrière via ending_before n'est pas supportée — utilisez le curseur à la place.

Idempotence

Les requêtes POST qui modifient l'état acceptent un en-tête Idempotency-Key. Nous dédupliquons sur la clé pendant 24 heures, retournant la réponse mise en cache pour les nouvelles tentatives. Utilisez un UUID par opération logique.

POST /v1/sms HTTP/1.1
Authorization: Bearer sk_live_…
Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e
Content-Type: application/json

{ "from": "num_8a4c2f1e9b3d", "to": "+33612345678", "body": "Hello" }

Rejouer la même clé avec un contenu de corps différent retourne 409 Conflict avec idempotency_key_mismatch.

Les clés d'idempotence ne sont pas obligatoires, mais fortement recommandées pour toute opération payante (appels, SMS, achats de numéros). Sans elles, une nouvelle tentative réseau peut vous facturer deux fois.

Limites de débit

Par défaut, chaque clé API est limitée à 100 requêtes par minute. Les clients à fort volume peuvent demander une augmentation via le support. Les limites s'appliquent par clé, pas par IP.

En-têtes de réponse

X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 73
X-Rate-Limit-Reset: 1745672460
Retry-After: 8

Lorsque vous dépassez la limite, vous recevez 429 Too Many Requests avec un en-tête Retry-After en secondes. Un backoff linéaire jusqu'à 4 tentatives est recommandé ; si ça persiste, demandez une limite plus élevée.

Tolérance aux pics

Le limiteur est un token bucket — les courtes rafales au-dessus de 100 req/min sont tolérées tant que la moyenne glissante sur 60 secondes reste sous le plafond.

Versionnement

Les versions API sont datées (2026-04-01). Les changements non rétrocompatibles sont publiés dans une nouvelle version datée ; les ajouts rétrocompatibles sont intégrés à la version actuelle. Fixez une version avec l'en-tête NoKYC-Version.

Compatibilité

• Nous supportons chaque version pendant au moins 24 mois après la sortie de la suivante.
• Les avis d'obsolescence sont envoyés par email aux propriétaires de compte 90 jours à l'avance.
• Un en-tête de réponse NoKYC-Deprecation vous avertit si vous utilisez une version obsolète.

Version actuelle : 2026-04-01.

Numéros

Un numéro représente une ligne téléphonique virtuelle que vous contrôlez. Les numéros sont liés à un pays et à un type (mobile ou landline) et portent une période de facturation.

curl https://api.nokycnumber.com/v1/numbers?country=fr&type=mobile \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "data": [
    {
      "id": "num_8a4c2f1e9b3d",
      "object": "number",
      "number": "+33647189022",
      "display": "+33 6 47 18 90 22",
      "country": "fr",
      "type": "mobile",
      "tier": "standard",
      "status": "active",
      "billing_period": "yearly",
      "renews_at": "2027-04-26T11:23:00Z",
      "ai_enabled": true,
      "created_at": "2026-04-26T11:23:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl "https://api.nokycnumber.com/v1/numbers/available?country=fr&type=mobile&tier=premium&limit=5" \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "data": [
    { "id": "navail_2k7m9p3w8x4t", "number": "+33611112222", "display": "+33 6 11 11 22 22", "tier": "premium", "pattern": "double-repeat", "price_usd_per_month": 11.98 },
    { "id": "navail_4n2v8j1q6h7y", "number": "+33612345678", "display": "+33 6 12 34 56 78", "tier": "premium", "pattern": "sequential",    "price_usd_per_month": 11.98 }
  ],
  "expires_at": "2026-04-26T11:33:00Z"
}

curl https://api.nokycnumber.com/v1/numbers \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e" \
  -d '{
    "available_id":   "navail_2k7m9p3w8x4t",
    "billing_period": "yearly",
    "addons":         ["ai-pickup"]
  }'

{
  "id": "num_8a4c2f1e9b3d",
  "object": "number",
  "number": "+33611112222",
  "display": "+33 6 11 11 22 22",
  "country": "fr",
  "type": "mobile",
  "tier": "premium",
  "status": "active",
  "billing_period": "yearly",
  "renews_at": "2027-04-26T11:23:00Z",
  "ai_enabled": true,
  "created_at": "2026-04-26T11:23:00Z"
}

curl https://api.nokycnumber.com/v1/numbers/num_8a4c2f1e9b3d \
  -H "Authorization: Bearer sk_live_…"

curl -X DELETE https://api.nokycnumber.com/v1/numbers/num_8a4c2f1e9b3d \
  -H "Authorization: Bearer sk_live_…"

Appels

Un appel est une session vocale unique émise depuis l'un de vos numéros. Les appels sortants sont passés via POST /v1/calls ; les appels entrants sont mirrorés vers votre webhook et récupérables via l'API.

curl https://api.nokycnumber.com/v1/calls \
  -H "Authorization: Bearer sk_live_…" \
  -d '{
    "from": "num_8a4c2f1e9b3d",
    "to":   "+33612345678",
    "callerid_mask": "rotate"
  }'

{
  "id": "call_2k7m9p3w8x4t",
  "object": "call",
  "from": "num_8a4c2f1e9b3d",
  "from_e164": "+33647189022",
  "to": "+33612345678",
  "status": "ringing",
  "direction": "outbound",
  "started_at": "2026-04-26T11:24:01Z",
  "answered_at": null,
  "ended_at": null,
  "duration_sec": 0,
  "recording_url": null,
  "cost_usd": null
}

Messages SMS

Envoyez et récupérez des SMS. Les messages longs sont auto-segmentés selon les règles GSM-03.38 / UCS-2 ; la réponse indique le nombre réel de segments pour la facturation.

curl https://api.nokycnumber.com/v1/sms \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e" \
  -d '{
    "from": "num_8a4c2f1e9b3d",
    "to":   "+33612345678",
    "body": "Bonjour. Your code is 482917."
  }'

{
  "id": "sms_4n2v8j1q6h7y",
  "object": "sms",
  "from_e164": "+33647189022",
  "to": "+33612345678",
  "body": "Bonjour. Your code is 482917.",
  "direction": "outbound",
  "segments": 1,
  "status": "queued",
  "created_at": "2026-04-26T11:24:50Z",
  "delivered_at": null,
  "cost_usd": 0.012
}

Messageries vocales

Les messageries vocales sont stockées, transcrites et traduites automatiquement. Les URLs audio sont pré-signées et expirent 1 heure après leur émission.

{
  "id": "vm_5p3w8x4t9k2m",
  "object": "voicemail",
  "number_id": "num_8a4c2f1e9b3d",
  "from_e164": "+33612345678",
  "received_at": "2026-04-26T11:25:42Z",
  "duration_sec": 27,
  "audio_url": "https://files.nokycnumber.com/vm/5p3w8x4t9k2m.mp3?expires=1745676342&sig=…",
  "transcript": {
    "text": "Bonjour, c'est Marc. Rappelez-moi quand vous pouvez.",
    "language": "fr",
    "translation_en": "Hello, this is Marc. Call me back when you can.",
    "summary": "Marc asks for a callback.",
    "sentiment": "neutral"
  }
}

Configuration IA

Chaque numéro peut faire tourner un agent IA qui décroche les appels à votre place, filtre les appelants inconnus, résume les messageries vocales ou traduit les conversations en direct. Configurez par numéro via la sous-ressource IA.

{
  "object": "ai_config",
  "number_id": "num_8a4c2f1e9b3d",
  "addons": ["ai-pickup", "ai-summary"],
  "auto_pickup": {
    "enabled": true,
    "after_rings": 4,
    "script": "I'm unavailable right now. Leave your name, the reason for the call, and a callback number.",
    "language": "auto",
    "voice": "neutral_fr"
  },
  "screening": { "enabled": false },
  "translator": { "enabled": false, "target_language": "en" },
  "voicemail_summary": { "enabled": true, "include_sentiment": true }
}

Voix

Voix disponibles : neutral_en, neutral_fr, neutral_es, neutral_de, neutral_jp, warm_en, warm_fr. Voix clonées sur mesure pour les entreprises sur demande.

Compte

Lire les données au niveau du compte : solde, statistiques d'utilisation, webhooks configurés.

{
  "object": "account",
  "email_hash": "9b3d4a7c8a4c2f1e",
  "balance_usd": 47.32,
  "default_country": "fr",
  "active_numbers": 3,
  "monthly_call_minutes": 412,
  "monthly_sms_segments": 1820,
  "created_at": "2026-04-12T09:15:00Z"
}

Webhooks

Abonnez-vous aux événements de votre compte ou de numéros spécifiques. Nous envoyons un événement JSON en POST vers votre endpoint et réessayons jusqu'à 5 fois avec un backoff exponentiel sur 24 heures.

Enveloppe d'événement

{
  "id": "evt_3d4a7c8a4c2f",
  "object": "event",
  "type": "sms.received",
  "created": "2026-04-26T11:25:42Z",
  "livemode": true,
  "data": { "object": { "id": "sms_…", … } },
  "request_id": "req_8a4c2f1e9b3d4a7c"
}

Vérification de signature

Chaque requête porte un en-tête X-NoKYC-Signature sous la forme t=<ts>,v1=<hex>. La signature est un HMAC-SHA256 de <ts>.<raw_body> avec le secret de signature de l'endpoint. Rejetez toute requête de plus de 5 minutes.

# Pseudocode
ts, v1 = parse(header)
if abs(now - ts) > 300: reject
expected = hmac_sha256(secret, f"{ts}.{body}")
if not constant_time_eq(expected, v1): reject

Points de terminaison

Types d'événements

Schémas d'objets

number

{
  "id":             "string · num_…",
  "object":         "string · constant \"number\"",
  "number":         "string · E.164",
  "display":        "string · pretty-printed",
  "country":        "string · ISO-2",
  "type":           "enum · mobile | landline",
  "tier":           "enum · standard | premium",
  "tier_pattern":   "string | null · double-repeat | sequential | mirror | round | …",
  "status":         "enum · active | paused | released",
  "billing_period": "enum · monthly | quarterly | yearly",
  "renews_at":      "string · ISO-8601 UTC",
  "auto_renew":     "boolean",
  "addons":         "array · ai-pickup | ai-screen | ai-summary | ai-trans",
  "ai_enabled":     "boolean",
  "metadata":       "object | null",
  "created_at":     "string · ISO-8601 UTC"
}

call

{
  "id":             "string · call_…",
  "object":         "string · constant \"call\"",
  "from":           "string · num_…",
  "from_e164":      "string · E.164",
  "to":             "string · E.164",
  "direction":      "enum · inbound | outbound",
  "status":         "enum · queued | ringing | in_progress | completed | failed | no_answer | busy",
  "started_at":     "string · ISO-8601 UTC",
  "answered_at":    "string | null",
  "ended_at":       "string | null",
  "duration_sec":   "integer",
  "recording_url":  "string | null · pre-signed, expires in 1h",
  "cost_usd":       "number | null"
}

sms

{
  "id":             "string · sms_…",
  "object":         "string · constant \"sms\"",
  "from":           "string · num_…",
  "from_e164":      "string · E.164",
  "to":             "string · E.164",
  "body":           "string",
  "media_urls":     "array · up to 5",
  "direction":      "enum · inbound | outbound",
  "segments":       "integer · 1–10",
  "status":         "enum · queued | sent | delivered | failed | undelivered",
  "failure_code":   "string | null",
  "created_at":     "string · ISO-8601 UTC",
  "delivered_at":   "string | null",
  "cost_usd":       "number | null"
}

SDK officiels

L'HTTP API est la source de vérité, mais ces SDK vous offrent des liaisons typées, des nouvelles tentatives, l'idempotence et la vérification des webhooks prêts à l'emploi.

• node npm install @nokycnumber/sdk
• python pip install nokycnumber
• go go get github.com/nokycnumber/sdk-go
• php composer require nokycnumber/sdk
• ruby gem install nokycnumber