HTTP API v1

Einführung

Die NoKYCNumber API ist um REST herum organisiert. Wir verwenden vorhersehbare ressourcenorientierte URLs, akzeptieren und geben JSON-kodierte Bodies zurück und verwenden Standard-HTTP-Antwortcodes, Authentifizierung und Verben.

Basis-URL

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

Alle Anfragen müssen über HTTPS erfolgen. Anfragen über einfaches HTTP schlagen mit 301 Moved Permanently fehl. Anfragen ohne Authentifizierung schlagen mit 401 Unauthenticated fehl.

JSON-Konvention

• Alle Anfragen mit Body verwenden Content-Type: application/json. Formular-kodierte Bodies werden mit 415 abgelehnt.
• Zeitstempel werden als ISO-8601-UTC-Strings (2026-04-26T14:23:00Z) zurückgegeben und im gleichen Format akzeptiert.
• Telefonnummern werden im E.164-Format mit führendem + (+33647189022) zurückgegeben und in display lesbar formatiert, wenn relevant.
• Objekt-IDs sind durch ihre Ressource präfixiert: num_, call_, sms_, vm_, whk_, evt_.

Authentifizierung

Authentifizierung mit einem Bearer-Schlüssel, der im Panel unter Einstellungen → API-Schlüssel ausgestellt wird. Es gibt zwei Schlüsseltypen:

• sk_live_… — Server-seitiges Geheimnis. Vollständige Lese-/Schreibrechte. Niemals im Client-Code verwenden.
• pk_live_… — Öffentlicher Schlüssel. Aktuell reserviert; wird noch von keinem Endpunkt verwendet.

Header-Format

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

Den NoKYC-Version-Header verwenden, um eine bestimmte API-Version festzulegen (siehe Versionierung). Wenn weggelassen, wird der festgelegte Standard Ihres Kontos verwendet.

Berechtigungsbereiche

Schlüssel werden mit einem von drei Berechtigungsbereichen ausgestellt:

Schlüssel können jederzeit rotiert werden. Alte Schlüssel bleiben nach der Rotation 5 Minuten gültig, um eine unterbrechungsfreie Bereitstellung zu ermöglichen.

Fehler

Die API verwendet herkömmliche HTTP-Status-Codes. 2xx bedeutet Erfolg, 4xx bedeutet ein Problem mit Ihrer Anfrage, 5xx bedeutet, dass wir einen Fehler gemacht haben und gerne davon hören möchten.

Fehlerumschlag

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

Status-Codes

Fehlertypen

• invalid_request_error — fehlerhafte Eingabe, fehlende Felder, ungültiges Format.
• authentication_error — Problem mit dem Schlüssel.
• authorization_error — Problem mit dem Berechtigungsbereich.
• rate_limit_error — zu viele Anfragen.
• api_error — unser Fehler. Wiederholbar.
• resource_error — der Ressourcenstatus verhindert die Operation (z. B. Anruf von einer pausierten Nummer).
• upstream_error — Carrier oder Partner hat nicht reagiert.

Jede Fehlerantwort enthält eine request_id. Immer protokollieren — das ist die einzige Möglichkeit, wie unser Support Ihren Aufruf mit unserem internen Trace korrelieren kann.

Paginierung

Listen-Endpunkte verwenden vorwärtsgerichtete Cursor-Paginierung. Sie geben bis zu limit Objekte zurück (Standard 25, max. 100) und einen has_more-Boolean. Um die nächste Seite abzurufen, die ID des letzten Objekts als starting_after übergeben.

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"
}

Listen sind nach zuletzt erstellten Objekten sortiert. Rückwärtspaginierung über ending_before wird nicht unterstützt — stattdessen den Cursor verwenden.

Idempotenz

POST-Anfragen, die den Zustand ändern, akzeptieren einen Idempotency-Key-Header. Wir deduplizieren den Schlüssel für 24 Stunden und geben die zwischengespeicherte Antwort bei Wiederholungen zurück. Pro logischer Operation eine UUID verwenden.

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" }

Dieselbe Taste mit anderem Body-Inhalt wiederholen gibt 409 Conflict mit idempotency_key_mismatch zurück.

Idempotenz-Schlüssel sind nicht erforderlich, aber für jede kostenpflichtige Operation (Anrufe, SMS, Nummernkäufe) dringend empfohlen. Ohne einen solchen kann ein Netzwerk-Retry zu einer doppelten Belastung führen.

Rate Limits

Standardmäßig ist jeder API-Schlüssel auf 100 Anfragen pro Minute begrenzt. Großkunden können beim Support eine Erhöhung beantragen. Limits gelten pro Schlüssel, nicht pro IP.

Antwort-Header

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

Wenn Sie das Limit überschreiten, erhalten Sie 429 Too Many Requests mit einem Retry-After-Header in Sekunden. Linearer Backoff bis zu 4 Wiederholungen wird empfohlen; wenn es anhält, einen höheren Grenzwert anfordern.

Burst-Kontingent

Das Limit ist ein Token-Bucket — kurze Bursts über 100 Anfragen pro Minute werden toleriert, solange der gleitende 60-Sekunden-Durchschnitt unter der Grenze bleibt.

Versionierung

API-Versionen sind datiert (2026-04-01). Breaking Changes werden als neue datierte Version ausgeliefert; abwärtskompatible Ergänzungen kommen in die aktuelle Version. Eine Version wird mit dem NoKYC-Version-Header festgelegt.

Kompatibilität

• Wir unterstützen jede Version für mindestens 24 Monate nach dem nächsten Release.
• Abkündigungshinweise werden 90 Tage im Voraus per E-Mail an die Kontoinhaber gesendet.
• Ein NoKYC-Deprecation-Antwort-Header warnt Sie, wenn Sie eine veraltete Version verwenden.

Aktuelle Version: 2026-04-01.

Nummern

Eine Nummer repräsentiert eine virtuelle Telefonleitung, die Sie kontrollieren. Nummern sind an ein Land und einen Typ (mobile oder landline) gebunden und haben einen Abrechnungszeitraum.

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_…"

Anrufe

Ein Anruf ist eine einzelne Sprachsitzung, die von einer Ihrer Nummern ausgeht. Ausgehende Anrufe werden über POST /v1/calls getätigt; eingehende Anrufe werden an Ihren Webhook gespiegelt und sind auch über die API abrufbar.

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
}

SMS-Nachrichten

SMS senden und abrufen. Lange Nachrichten werden automatisch gemäß GSM-03.38 / UCS-2-Regeln segmentiert; die Antwort zeigt die tatsächliche Segmentanzahl für die Abrechnung.

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
}

Mailbox-Nachrichten

Mailbox-Nachrichten werden automatisch gespeichert, transkribiert und übersetzt. Audio-URLs sind voraus-signiert und laufen 1 Stunde nach Ausstellung ab.

{
  "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"
  }
}

KI-Konfiguration

Jede Nummer kann einen KI-Agenten betreiben, der Anrufe annimmt, wenn Sie es nicht tun, unbekannte Anrufer filtert, Mailbox-Nachrichten zusammenfasst oder Gespräche live übersetzt. Konfigurieren Sie dies pro Nummer über die KI-Unterressource.

{
  "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 }
}

Stimmen

Verfügbare Stimmen: neutral_en, neutral_fr, neutral_es, neutral_de, neutral_jp, warm_en, warm_fr. Individuell geklonte Stimmen für Unternehmen auf Anfrage.

Konto

Kontodaten lesen: Guthaben, Nutzungsstatistiken, konfigurierte Webhooks.

{
  "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

Ereignisse von Ihrem Konto oder bestimmten Nummern abonnieren. Wir senden ein JSON-Ereignis per POST an Ihren Endpunkt und wiederholen dies bis zu 5 Mal mit exponentiellem Backoff über 24 Stunden.

Ereignisumschlag

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

Signaturverifizierung

Jede Anfrage trägt einen X-NoKYC-Signature-Header in der Form t=<ts>,v1=<hex>. Die Signatur ist HMAC-SHA256 von <ts>.<raw_body> mit dem Signiergeheimnisschlüssel des Endpunkts. Anfragen, die älter als 5 Minuten sind, ablehnen.

# 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

Endpunkte

Ereignistypen

Objekt-Schemata

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"
}

Offizielle SDKs

Die HTTP API ist die Quelle der Wahrheit, aber diese SDKs bieten Ihnen typisierte Bindungen, Wiederholungen, Idempotenz und Webhook-Verifizierung direkt nach der Installation.

• 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