API-Dokumentation

API-Dokumentation herunterladen (Markdown)

kartesim stellt Partnern echte Telefonnummern über zwei Dienste bereit: langfristige Nummernmieten und OTP-Sitzungen pro Nutzung. Beide sind über das HANDLER_API-Protokoll und die Native REST API verfügbar.

OTP-Sitzungenpro Nutzung

Fordere eine temporäre Nummer an, warte auf eine SMS und erhalte den OTP-Code, alles in einem API-Aufrufzyklus. Abgerechnet wird pro Sitzung, mit Erstattung, wenn du stornierst, bevor der Code ankommt.

NummernmietenSIM-Karten

Miete eine dedizierte Telefonnummer tage-, wochen- oder monatsweise. Alle SMS, die auf dieser Nummer eingehen, werden in Echtzeit an dein Konto weitergeleitet.

Mieten werden von deinem Account-Manager eingerichtet. Kontaktiere uns, um deine Miete einzurichten. Sobald sie aktiv ist, erscheint deine Telefonnummer im Partnerportal und kann über die API abgefragt werden. OTP-Sitzungen nutzt du selbstständig über die API, ohne Einrichtung.

Authentifizierung

Alle API-Anfragen erfordern deinen Partner-API-Schlüssel. Wie du ihn übergibst, hängt von deinem Protokoll ab.

Handler API: Query-Parameter

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

Native REST API: HTTP-Header

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

Halte deinen API-Schlüssel geheim. Dein Schlüssel ist im Partnerportal unter API sichtbar. Mit der Schaltfläche Schlüssel neu generieren dort kannst du ihn sofort erneuern.

Handler-API-Referenz

Basis-URL: /api/stubs/handler_api.php. Alle Anfragen verwenden GET. Alle Antworten sind Klartext.

GET/api/stubs/handler_api.php?action=getBalance

Gibt dein aktuelles Prepaid-Guthaben in USD zurück.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	erforderlich	Dein API-Schlüssel
action	string	erforderlich	Muss "getBalance" sein

Antworten

45.00Dein Guthaben in USD

999999Fester Platzhalterwert für Konten mit unbegrenztem Guthaben. Kein echtes Guthaben, ändert sich nicht mit der Nutzung

BAD_KEYUngültiger oder widerrufener API-Schlüssel

Beispielanfrage

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

Beispielantwort

45.00

GET/api/stubs/handler_api.php?action=getCountries

Listet die unterstützten Länder mit ihren numerischen Codes auf.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	erforderlich	Dein API-Schlüssel
action	string	erforderlich	Muss "getCountries" sein

Antworten

JSON array[{ "id": 7, "name": "Russia" }, ...]

Beispielanfrage

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

Beispielantwort

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

Ruft aktuelle Preise und den verfügbaren aktiven Bestand pro Land und Dienst ab.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	erforderlich	Dein API-Schlüssel
action	string	erforderlich	Muss "getPrices" sein
country	number	optional	Nach numerischer Länder-ID filtern
hide_empty	integer	optional	Auf 1 setzen, um Länder ohne Bestand aus der Antwort auszuschließen

Antworten

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

Beispielanfrage

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

Beispielantwort

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

Fordert eine temporäre Telefonnummer für die OTP-Verifizierung an. Gibt eine Sitzungs-ID und die zugewiesene Nummer zurück. Die Sitzung läuft nach 10 Minuten ab, wenn keine SMS ankommt.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	erforderlich	Dein API-Schlüssel
action	string	erforderlich	Muss "getNumber" sein
service	string	optional	Name des Dienstes (z. B. "telegram", "whatsapp"), nur informativ
country	integer	optional	Ländervorwahl (z. B. 212 für Marokko). Weglassen oder 0 verwenden für ein beliebiges Land.

Antworten

ACCESS_NUMBER:id:numberSitzung erstellt: id wird für getStatus/setStatus verwendet, number ist die zugewiesene Telefonnummer

NO_NUMBERSKeine Online-Ports verfügbar, die zu deiner Anfrage passen

NO_BALANCEGuthaben reicht nicht für die OTP-Gebühr

Beispielanfrage

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

Beispielantwort

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

Fragt den OTP-Code einer aktiven Sitzung ab. Frage alle 5 bis 10 Sekunden ab, bis du STATUS_OK oder STATUS_CANCEL erhältst.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	erforderlich	Dein API-Schlüssel
action	string	erforderlich	Muss "getStatus" sein
id	string	erforderlich	Sitzungs-ID aus der ACCESS_NUMBER-Antwort

Antworten

STATUS_WAIT_CODESitzung ist aktiv, SMS noch nicht empfangen. Weiter abfragen.

STATUS_OK:84729OTP empfangen, der Code folgt nach dem Doppelpunkt

STATUS_CANCELSitzung abgelaufen oder storniert

Beispielanfrage

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

Beispielantwort

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

Bestätigt den Empfang des OTP (status=1) oder storniert die Sitzung mit voller Erstattung (status=8). Nur Sitzungen im Status PENDING können storniert werden.

Parameter

Name	Typ	Erforderlich	Beschreibung
api_key	string	erforderlich	Dein API-Schlüssel
action	string	erforderlich	Muss "setStatus" sein
id	string	erforderlich	Sitzungs-ID, auf die sich die Aktion bezieht
status	integer	erforderlich	1 = Empfang bestätigen, 8 = stornieren und erstatten

Antworten

ACCESS_READYBestätigt, Sitzung quittiert

ACCESS_CANCELStorniert, Guthaben erstattet

BAD_ACTIONSitzung nicht gefunden oder bereits abgeschlossen

Beispielanfrage

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

Beispielantwort

ACCESS_CANCEL

Native REST API

Für moderne Integrationen nutze unsere Native REST API statt der älteren Handler API. Übergib deinen API-Schlüssel im HTTP-Header x-api-key.

OTP-Sitzungen

pro Nutzung

Mit OTP-Sitzungen kannst du eine temporäre Telefonnummer anfordern, einen Einmalcode empfangen und die Nummer wieder freigeben, alles über die API. Jede Sitzung wird einmal bei der Erstellung abgerechnet. Wenn du stornierst, bevor der Code ankommt, wird die volle Gebühr erstattet.

POST/api/v1/otp/request

Fordert eine temporäre Telefonnummer für die OTP-Verifizierung an. Gibt eine sessionId und die zugewiesene Nummer zurück. Die OTP_PER_USE-Gebühr wird sofort berechnet.

Parameter

Name	Typ	Erforderlich	Beschreibung
country	integer	optional	Ländervorwahl, nach der gefiltert wird (z. B. 212). Weglassen für ein beliebiges Land.
service	string	optional	Name des Dienstes, z. B. "telegram". Wird zu deiner Information in der Sitzung gespeichert
webhookUrl	string	optional	HTTPS-URL, an die ein POST gesendet wird, wenn das OTP ankommt (statt Polling)
expiresIn	integer	optional	Sitzungs-TTL in Sekunden (60 bis 1800, Standard 600)

Antworten

200 OKSitzung erstellt: Der Body enthält sessionId, number und expiresAt

402 Payment RequiredGuthaben reicht nicht aus

503 Service UnavailableKeine Online-Nummern verfügbar

Beispielanfrage

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

Beispielantwort

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

Fragt Status und Code einer OTP-Sitzung ab. Gibt den extrahierten OTP-Code zurück, sobald die SMS ankommt. Frage alle 5 bis 10 Sekunden ab.

Antworten

200 OK — PENDINGstatus: "PENDING", otp: null — wartet noch

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — Code bereit

200 OK — EXPIREDstatus: "EXPIRED" — keine SMS innerhalb des Zeitfensters

200 OK — CANCELLEDstatus: "CANCELLED" — du hast die Sitzung storniert

Beispielanfrage

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

Beispielantwort

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

Storniert eine Sitzung im Status PENDING. Die OTP-Gebühr wird vollständig erstattet. Sitzungen, die bereits ein OTP empfangen haben, können nicht storniert werden.

Antworten

200 OKstatus: "CANCELLED", refunded: 0.10 — Guthaben gutgeschrieben

409 ConflictSitzung ist nicht im Status PENDING und kann nicht storniert werden

404 Not FoundSitzung nicht gefunden oder gehört zu einem anderen Konto

Beispielanfrage

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

Beispielantwort

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTDeine webhook-URL (Server-Push)

Wenn ein OTP ankommt, senden wir einen POST an die webhookUrl, die du bei der Erstellung der Sitzung angegeben hast. Das ist eine Alternative zum Polling: Dein Server erhält das OTP automatisch, ohne getStatus aufrufen zu müssen.

Payload

POST an deine webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

Sicherheit

Deine webhook-URL muss in Produktion HTTPS sein. HTTP-URLs werden abgelehnt.
Wir senden einen X-Webhook-Signature: sha256=...-Header (HMAC-SHA256). Prüfe ihn, um sicherzugehen, dass die Anfrage echt ist.
Bei 5xx versuchen wir es nach 2 Sekunden einmal erneut. Dein Endpunkt sollte schnell 200 zurückgeben.
Dein Endpunkt muss idempotent sein. Bei einem erneuten Versuch ist eine doppelte Zustellung möglich.

GET/api/partner/rentals

Ruft alle aktiven Nummernmieten deines Kontos ab.

Antworten

200 OKJSON-Array der aktiven Nummernmieten

401 UnauthorizedUngültiger oder fehlender API-Schlüssel

Beispielanfrage

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Beispielantwort

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/sms?simNumber=1234567890

Ruft die neuesten SMS ab, die deine gemieteten Nummern empfangen haben. Optional nach einer bestimmten simNumber filtern.

Parameter

Name	Typ	Erforderlich	Beschreibung
simNumber	string	optional	SMS für eine bestimmte gemietete Nummer filtern

Antworten

200 OKJSON-Array der letzten SMS

401 UnauthorizedUngültiger oder fehlender API-Schlüssel

Beispielanfrage

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

Beispielantwort

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

Nummernmieten

Mit Nummernmieten nutzt du eine echte SIM-Karte für einen festen Mietzeitraum exklusiv. Jede SMS, die auf dieser Nummer eingeht, wird in Echtzeit an dein Konto zugestellt. Du kannst Nummern direkt über die API oder das Partnerportal mieten.

Zeitraum	Dauer	Beschreibung
Täglich	24 Stunden	Am besten für kurzfristige Verifizierungskampagnen
Wöchentlich	7 Tage	Am besten für laufenden Zugriff auf eine stabile Nummer
Monatlich	30 Tage	Am besten für langfristigen Zugriff auf eine dedizierte Nummer

So funktioniert es

Rufe GET /api/v1/numbers/available auf, um verfügbare Nummern (maskiert) anzusehen.
Wähle eine Nummer und einen Abrechnungszyklus und rufe dann POST /api/v1/numbers/rent auf, um sie sofort zu mieten.
Dein Guthaben wird sofort belastet. Die vollständige, unmaskierte Telefonnummer steht in der Antwort.
Alle SMS, die auf deiner gemieteten Nummer eingehen, erscheinen in Echtzeit unter SMS-Protokolle.
Bei Ablauf wird die Nummer automatisch freigegeben. Für nicht genutzte Zeit gibt es keine Erstattung.

GET/api/v1/numbers/available

Sieh dir Nummern an, die zur Miete verfügbar sind. Die Nummern sind maskiert (z. B. +212 6** *** **7), sodass du Land und Netzbetreiber siehst, bevor du dich festlegst. Optional nach Ländercode filtern.

Parameter

Name	Typ	Erforderlich	Beschreibung
country	number	optional	ITU-Ländercode (z. B. 212). Weglassen oder 0 verwenden für ein beliebiges Land.

Antworten

200 OKJSON mit der Liste der verfügbaren Nummern und der Gesamtzahl

401 UnauthorizedUngültiger oder fehlender API-Schlüssel

429 Too Many RequestsRatenlimit überschritten (30 req/min)

Beispielanfrage

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

Beispielantwort

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

Mietet eine Nummer selbstständig. Bucht dein Guthaben atomar ab und erstellt eine exklusive Miete. Gibt bei Erfolg die vollständige (unmaskierte) Telefonnummer zurück.

Parameter

Name	Typ	Erforderlich	Beschreibung
phoneId	string	erforderlich	Port-ID aus /api/v1/numbers/available
billingCycle	string	erforderlich	DAILY \| WEEKLY \| MONTHLY
cycles	number	optional	Anzahl der Abrechnungszyklen, die im Voraus bezahlt werden (1 bis 12, Standard 1)
autoRenew	boolean	optional	Automatische Verlängerung bei Ablauf (Standard false)

Antworten

200 OKMiete erstellt, vollständige Telefonnummer in der Antwort

402 Payment RequiredGuthaben reicht nicht aus oder für diesen Zyklus ist kein Preis konfiguriert

409 ConflictDie Nummer wurde gerade von einem anderen Partner gemietet. Versuche es mit einer anderen Nummer erneut

401 UnauthorizedUngültiger oder fehlender API-Schlüssel

Beispielanfrage

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

Beispielantwort

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

Ruft alle aktiven Nummernmieten deines Kontos ab.

Antworten

200 OKJSON-Array der aktiven Nummernmieten

401 UnauthorizedUngültiger oder fehlender API-Schlüssel

Beispielanfrage

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Beispielantwort

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

Die Nummern sind deinem Konto fest zugeordnet. Die Nummer wird während deines Mietzeitraums nie geteilt oder neu vergeben. Das für den gesamten Zeitraum nötige Guthaben wird zum Zeitpunkt der Miete berechnet. Wird eine angefragte Nummer zwischen Ansehen und Mieten vergeben, erhältst du einen 409. Versuche es dann mit einer anderen Nummer erneut.

Unterstützte Länder

Mit getCountries rufst du die aktuelle Liste ab. Häufige Ländercodes:

Code	Land	Code	Land
0	Beliebig (automatische Zuweisung)	7	Russland
212	Marokko	33	Frankreich
1	Vereinigte Staaten	44	Vereinigtes Königreich
49	Deutschland	34	Spanien
966	Saudi-Arabien	971	Vereinigte Arabische Emirate
20	Ägypten	216	Tunesien

Fehlerreferenz

Antwort	Bedeutung
BAD_KEY	Ungültiger, widerrufener oder fehlender API-Schlüssel
BAD_ACTION	Unbekannte Aktion oder fehlende Pflichtparameter
TOO_MANY_REQUESTS	Ratenlimit überschritten: 120 Anfragen pro Minute
NO_NUMBERS	Keine Online-Ports verfügbar, die zu deiner OTP-Anfrage passen
NO_BALANCE	Guthaben reicht nicht, um eine OTP-Sitzung zu erstellen
STATUS_WAIT_CODE	OTP noch nicht empfangen, weiter abfragen
STATUS_OK:code	OTP empfangen, der Zifferncode folgt nach dem Doppelpunkt
STATUS_CANCEL	Sitzung abgelaufen oder storniert
ACCESS_NUMBER:id:num	OTP-Sitzung erstellt, Sitzungs-ID und Telefonnummer folgen
ACCESS_CANCEL	Sitzung storniert, Guthaben erstattet
ACCESS_READY	Sitzung quittiert / bestätigt

kartesim Partner-Dokumentation. Für API-Schlüssel oder Mietanfragen wende dich an deinen Account-Manager.