Verifizierungen senden

Für die Verifizierung eines Nutzers brauchen Sie zwei Aufrufe. POST /v1/verify/verifications sendet einen Bestätigungscode an eine E-Mail-Adresse oder Telefonnummer. POST /v1/verify/verifications/check übermittelt den vom Nutzer eingegebenen Wert und meldet, ob er übereinstimmt. Bird erzeugt den Code, gibt ihn in keiner API-Antwort zurück und setzt Ablaufzeit und Versuchslimits durch.

Einen Code senden

Die kleinste gültige Anfrage enthält einen to-Empfänger:

const verification = await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
});
console.log(verification.id, verification.status);

verification = client.verify.verifications.create(to={"phone_number": "+15551234567"})
print(verification.id, verification.status)

verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getId(), ' ', $verification->getStatus();

bird verify verifications create --body-file - <<'JSON'
{
  "to": {
    "phone_number": "+15551234567"
  },
  "metadata": {
    "correlation_id": "signup-7f3a"
  }
}
JSON

curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" }
  }'

Verwenden Sie Ihren regionalen Host (https://us1.platform.bird.com oder https://eu1.platform.bird.com) mit einem passenden bk_{region}_...-Schlüssel.

Empfänger

to bezeichnet den Empfänger mit einer email, einer phone_number im E.164-Format oder beidem. Eine E-Mail-Adresse ermöglicht die Zustellung per E-Mail. Eine Telefonnummer wird in die Kanäle aufgelöst, die im Zielland verfügbar sind, und zwar in der Reihenfolge aus der Länderkonfiguration. Die meisten Länder versuchen WhatsApp vor SMS, einige versuchen zuerst SMS. Telegram folgt in der Fallback-Reihenfolge der Plattform auf beide. Ein Sprachanruf wird nur in Ländern verwendet, in denen Sie Sprachanrufe aktiviert haben. Wenn Sie beide Adressen angeben, kann ein fehlgeschlagener Versuch zu einem anderen verfügbaren Kanal übergehen.

Optionen

options überschreibt Einstellungen nur für diese Anfrage:

• code_length: Länge des Bestätigungscodes für diese Verifizierung, 4 bis 8 Ziffern; überschreibt den Standardwert.
• channels: Ändert die Reihenfolge der Zustellkanäle für diese Anfrage oder schränkt sie ein. Listen Sie Kanalnamen (sms, whatsapp, email, telegram, voice) in der Reihenfolge auf, in der sie versucht werden sollen. Ein weggelassener Kanal wird nicht verwendet, und ein Name, der nicht im aufgelösten Plan des Empfängers steht, wird ignoriert. Auf diese Weise können Sie keinen Kanal hinzufügen, sondern nur kürzen oder neu ordnen, was Empfänger und Länderkonfiguration bereits erlauben. Lässt eine Liste keinen nutzbaren Kanal übrig, schlägt die Anfrage mit 422 fehl.
• language: Ein BCP 47-Tag wie fr oder pt-BR, der festlegt, welche integrierte Übersetzung die Code-Nachricht verwendet. Wenn Sie ihn weglassen, richtet sich die Sprache nach der Telefonnummer des Empfängers; siehe Nachrichtensprache.

Metadaten

metadata ist ein frei gestaltbares Objekt, das bei jedem Abruf zurückgegeben wird. Nutzen Sie es für Ihre eigene Benutzer-ID oder Sitzungsreferenz. Absenderauswahl und Verifizierungseinstellungen werden nicht mit der Anfrage übergeben: Sie stammen aus der Konfiguration Ihres Workspace, die Sie im Dashboard verwalten (siehe Verifizierungseinstellungen).

Die Antwort

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "phone_number": "+15551234567" },
  "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
  "last_channel": "whatsapp",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

channels ist der geordnete Zustellplan, der für diese Verifizierung aufgelöst wurde (bei einem Telefonempfänger stehen die Telefonkanäle in Versuchsreihenfolge), und last_channel gibt an, wohin der letzte Code ging. expires_at ist der Zeitpunkt, zu dem die Verifizierung verfällt, wenn kein korrekter Code eingeht. Erneutes Senden verlängert diese Frist nicht.

Nachrichtensprache

Die SMS-, E-Mail- und gemeinsamen WhatsApp-Nachrichten von Bird gibt es in 40 integrierten Übersetzungen. Ein eigener WhatsApp-Absender verwendet die genehmigten Sprachen seiner ausgewählten Authentifizierungsvorlage. Telegram formuliert seine eigene Nachricht, und ein Sprachanruf liest den Code auf Englisch vor, daher wirkt sich die Einstellung auf beide nicht aus.

Ohne options.language ergibt sich die Sprache aus der Telefonnummer des Empfängers. Eine französische Nummer erhält Französisch und eine japanische Nummer Japanisch, ohne dass Sie dies anfordern. Eine Verifizierung ohne Telefonnummer wird auf Englisch gesendet, ebenso eine, für deren Land es keine Übersetzung gibt.

Setzen Sie options.language, um die Sprache selbst festzulegen, etwa passend zu der Sprache, die Ihr Benutzer in Ihrer App gewählt hat, statt nach dem Land seiner Nummer:

{
  "to": { "phone_number": "+15551234567" },
  "options": { "language": "es" }
}

Ein Tag ohne eigene integrierte Übersetzung fällt auf seine Basissprache zurück, danach auf Englisch: en-GB sendet Englisch, pt-BR sendet Portugiesisch. Nur ein fehlerhaft formatierter Tag wird abgelehnt, mit 422. Dies sind die integrierten Übersetzungen, die Sie anfordern können. Alle sind auf SMS und per E-Mail verfügbar, alle außer Mongolisch auch über den gemeinsamen WhatsApp-Absender von Bird:

Die Referenz zum Erstellen einer Verifizierung enthält die maßgebliche Liste.

Die Sprache wird beim Erstellen der Verifizierung festgelegt. Ein erneuter Versand oder ein Wechsel zu einem anderen Kanal kommt daher in derselben Sprache an wie die erste Nachricht. Wenn Sie create für denselben Empfänger erneut mit einem anderen language aufrufen, wird die laufende Verifizierung wiederverwendet und nicht geändert.

Wenn ein Fallback greift, kann die verwendete Übersetzung von dem gesendeten Tag abweichen. Öffnen Sie die Verifizierung auf der Seite Verifications, um das zu prüfen: Jeder Versuch zeigt die gerenderte Sprache als Template-Tag. Der gemeinsame WhatsApp-Absender von Bird hat keine mongolische (mn) Vorlage. Er sendet für diese Sprache daher Englisch, während SMS und E-Mail Mongolisch beibehalten. Ihre eigene WhatsApp-Vorlage folgt ihren freigegebenen Sprachen und ihrer Sprachrichtlinie. Eine Sprache, die sie nicht senden kann, kann den WhatsApp-Versuch fehlschlagen lassen.

Sie können die Sprache pro Anfrage wählen, aber keinen Nachrichtentext mit dieser Anfrage übergeben. Ein eigener WhatsApp-Absender verwendet den Text seiner ausgewählten Authentifizierungsvorlage. Absender und Branding zeigt die Absenderoptionen und den Nachrichtentext von Bird.

Code prüfen

Senden Sie die Eingabe des Nutzers an POST /v1/verify/verifications/check, zugeordnet über denselben Empfänger; eine Verifizierungs-ID ist nicht nötig. Geben Sie genau das to-Set an, mit dem Sie die Verifizierung erstellt haben: Eine mit beiden Adressen erstellte Verifizierung wird über nur eine der Adressen nicht gefunden.

const result = await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" },
  code: "123456",
});
console.log(result.success);

result = client.verify.verifications.check(
    to={"phone_number": "+15551234567"}, code="123456"
)
print(result.success)

result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
	To:   bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
	Code: "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*result.Success)

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setPhoneNumber('+15551234567'))
        ->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'failed';

bird verify verifications check 123456 --phone-number +15551234567

curl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" },
    "code": "123456"
  }'

Die Antwort gibt an, ob der Code übereinstimmte:

{
  "success": false,
  "reason": "incorrect_code",
  "attempts_remaining": 4,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "pending",
    "reason": null,
    "to": { "phone_number": "+15551234567" },
    "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
    "last_channel": "whatsapp",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": null,
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:38Z"
  }
}

Behandeln Sie diese beiden Antwortverhalten:

• Ein falscher Code gibt 200 zurück. Behandeln Sie success: false mit einem reason (incorrect_code, expired, attempts_exhausted) als normale Antwort. attempts_remaining gibt an, wie viele Versuche noch bleiben. Reservieren Sie die Fehlerbehandlung für fehlgeschlagene Anfragen.
• Eine abgeschlossene Verifizierung lässt sich nicht erneut prüfen. Sobald eine Verifizierung einen Endstatus erreicht hat, geben weitere Prüfungen 404 zurück. Speichern Sie das erste eindeutige Ergebnis, statt erneut zu prüfen.

Wenn der Nutzer einen neuen Code anfordert, rufen Sie den Create-Endpunkt erneut mit demselben Empfänger auf: Die laufende Verifizierung wird wiederverwendet, nicht ersetzt. Nach Ablauf der Wartezeit für erneutes Senden (standardmäßig 60 Sekunden) wird ein neuer Code verschickt; innerhalb der Wartezeit gibt der Aufruf die laufende Verifizierung zurück, ohne erneut zu senden. Jeder für die laufende Verifizierung gesendete Code bleibt gültig, bis sie abgeschlossen ist oder abläuft, sodass der Nutzer jeden angekommenen Code eingeben kann.

Code über einen anderen Kanal senden

Meldet der Nutzer, dass überhaupt kein Code angekommen ist, schaltet POST /v1/verify/verifications/next-channel die Verifizierung auf den nächsten Kanal ihres Plans weiter und sendet dort einen neuen Code. Dieser Endpunkt steht hinter einer Schaltfläche wie "I didn't receive my code": Ihre App entscheidet selbst, den Kanal zu wechseln, statt auf ein Zustellstatus-Signal zu warten.

Ordnen Sie den Aufruf wie bei einer Prüfung demselben Empfänger zu, mit dem Sie die Verifizierung erstellt haben:

const verification = await bird.verify.verifications.nextChannel({
  to: { phone_number: "+15551234567" },
});
console.log(verification.last_channel);

verification = client.verify.verifications.next_channel(
    to={"phone_number": "+15551234567"}
)
print(verification.last_channel)

verification, err := client.Verify.Verifications.NextChannel(context.Background(), bird.VerifyVerificationsNextChannelParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
if verification.LastChannel != nil {
	fmt.Println(*verification.LastChannel)
}

$verification = $bird->verify->verifications->nextChannel(
    (new VerificationNextChannelRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getLastChannel();

bird verify verifications next-channel --phone-number +15551234567

curl -X POST "https://{region}.platform.bird.com/v1/verify/verifications/next-channel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone_number": "+15551234567"
    }
  }'

Die Antwort ist die Verifizierung; last_channel nennt den Kanal, über den der neue Code ging. Jeder bereits gesendete Code bleibt gültig, sodass sich auch eine verspätet ankommende Nachricht noch prüfen lässt.

Zwei Dinge unterscheiden diesen Aufruf von einem erneuten Senden:

• Die Wartezeit für erneutes Senden gilt nicht. Ein bewusster Kanalwechsel ist etwas anderes als eine erneute Anfrage auf demselben Kanal, daher wird der Code sofort gesendet.
• Nur der Kanal rückt vor. Ablaufzeit, Versuchskontingent und Verifizierungs-ID bleiben unverändert.

Senden Sie erneut, wenn der Nutzer auf einem funktionierenden Kanal einen weiteren Versuch möchte. Verwenden Sie diesen Endpunkt, wenn der Kanal selbst das Problem zu sein scheint. Eine Telefonnummer mit dem Plan WhatsApp, dann SMS wechselt zu SMS. Ein Empfänger mit nur einem nutzbaren Kanal hat keinen weiteren Kanal.

Vier Antworten erfordern eine eigene Behandlung statt eines einfachen erneuten Versuchs:

Jeder Code, den dieser Endpunkt sendet, wird wie jede andere Verify-Sendung abgerechnet; siehe Kosten und Abrechnung.

Status

Eine Verifizierung ist pending, bis sie einen Endstatus erreicht; reason gibt den Grund dafür an:

reason ist ein offenes Enum. Behalten Sie einen unbekannten Wert bei, statt die Antwort als ungültig zu behandeln.

Ein Bounce, eine Ablehnung durch den Netzbetreiber oder ein Zustellungs-Timeout kann die Sitzung im Status ausstehend belassen, weil der Empfänger möglicherweise noch einen gültigen Code hat. Dass der Zustellungsplan ausgeschöpft ist, bedeutet allein nicht, dass die Sitzung fehlgeschlagen ist. Die Bedingungen für ein Fehlschlagen finden Sie unter Verify-Events.

Verifizierungen im Dashboard verfolgen

Die Seite Verifications listet jede Verifizierung auf, die der Workspace erstellt hat, und lässt sich nach Status filtern. Jede Zeile zeigt Empfänger, Kanalplan, letzten Kanal, Ablauf- und Verifizierungszeitpunkt sowie Metadaten. Der generierte Code wird nicht angezeigt.

Einstellungen für Verifizierungen

Auf der Seite Configure legen Sie den Verifizierungszyklus des Workspace fest. Jedes Feld zeigt den wirksamen Wert: Ihre Überschreibung, sofern Sie eine gesetzt haben, andernfalls den Plattformstandard von Bird.

• Duration: wie lange ein Code gültig bleibt. Standardwert 10 Minuten; 1 bis 999 Minuten.
• Maximum Retries: wie viele Prüfversuche möglich sind, bevor die Verifizierung mit attempts_exhausted fehlschlägt. Standardwert 5; 1 bis 10.
• Retry Delay: die Wartezeit, bevor ein neuer Code an denselben Empfänger gesendet werden kann. Standardwert 60 Sekunden; 0 bis 3.600.

Die Codelänge ist kein Feld auf dieser Seite: Codes sind standardmäßig 6-stellig und numerisch, und options.code_length legt pro Anfrage 4 bis 8 Stellen fest.

Schutz vor Missbrauch

Unabhängig von Ihren Einstellungen setzt Verify plattformweite Obergrenzen durch, damit OTP-Traffic nicht missbraucht werden kann, weder gegen Ihr Guthaben (SMS-Pumping) noch gegen das Postfach eines Opfers:

• 5 Sendungen pro Adresse pro gleitender Stunde, für das Starten und das erneute Senden von Verifizierungen zusammen. Enthält to beide Adressen, hat jede ihr eigenes Kontingent.
• 10 Prüfungen pro Satz von Empfängeradressen pro Minute, zusätzlich zum Versuchslimit der Verifizierung.

Kanalwechsel begrenzt der Kanalplan, nicht die stündliche Obergrenze. Jeder Aufruf geht strikt vorwärts, sodass eine Verifizierung höchstens einmal pro verbleibendem Kanal sendet.

Wird eine Obergrenze erreicht, erhalten Sie 429. Warten Sie dann den im Header Retry-After angegebenen Zeitraum ab und versuchen Sie es erneut. Die allgemeinen Anfragelimits Ihres Kontos gelten separat und richten sich nach Ihrem Tarif; siehe Ratenlimits.

Sicher erneut versuchen

Alle drei Endpunkte akzeptieren den Header Idempotency-Key. Senden Sie pro logischer Anfrage einen eindeutigen Wert. Wenn Sie es nach einem Timeout oder einer abgebrochenen Verbindung mit demselben Schlüssel erneut versuchen, erhalten Sie die ursprüngliche Antwort noch einmal. Eine solche Wiederholung sendet keinen weiteren Code, verbraucht keinen weiteren Prüfversuch und enthält einen Header Idempotency-Replay. Schlüsselformat und Aufbewahrungsdauer finden Sie unter Idempotenz.

Kosten und Abrechnung

Abgerechnet wird jeder gesendete Code. Jeder gesendete Code wird Ihrem Guthaben zum Tarif des Kanals für das Zielland belastet. Ein erneutes Senden oder ein Wechsel auf einen anderen Kanal verursacht pro Sendung eine weitere Belastung. Die eigene Gebühr von Bird wird während der Verarbeitung der Sendung erhoben und bleibt bestehen, unabhängig davon, ob der Code ankommt. Bei SMS und WhatsApp kommt bei Zustellung der Nachricht eine Drittanbietergebühr hinzu. Kostenlose Routen und Prüfungen kosten nichts, und eine Sendung, die vor der Abrechnung abgelehnt wird, wird nicht berechnet. Guthaben und Aufladungen behandelt Zahlungsmethoden und Guthaben.

Telegram rechnet zu einem anderen Zeitpunkt der Sendung ab. Bevor eine Nachricht hinausgeht, wird Telegram gefragt, ob die Nummer eine Nachricht empfangen kann. Lautet die Antwort ja, fällt die Gebühr an, weltweit zu einem Pauschaltarif. Eine nicht erreichbare Nummer ist kostenlos und wechselt ohne Belastung zum nächsten Kanal. Eine Telegram-Gebühr bedeutet also, dass die Nachricht zur Zustellung angenommen wurde, nicht dass sie angekommen ist. Ein Code, der danach nicht zugestellt wird, bleibt berechnet, und die Verifizierung zahlt erneut für den Kanal, auf den sie ausweicht. Wenn Sie diese zweite Belastung vermeiden möchten, entfernen Sie Telegram für die betreffenden Länder auf der Seite Countries aus der Kanalreihenfolge.

Sprachanrufe werden als Telefonanruf abgerechnet, nicht pro Code, und es fällt keine Verify-Gebühr an. Ein nicht angenommener Anruf kostet nichts. Ein angenommener Anruf wird von der Annahme bis zum Auflegen zum ausgehenden Sprachtarif des Ziellands berechnet, mit der Mindestabrechnungsdauer und den Taktintervallen dieses Tarifs, zuzüglich der Anrufbearbeitungsgebühr von Bird. Beide sind auf der Voice-Preisseite aufgeführt. Wie die abrechenbare Zeit gezählt wird, erfahren Sie unter Kosten und Abrechnung bei Voice. Ein Anruf, der endet, bevor der Code vollständig vorgelesen wurde, wird trotzdem für die verbundene Zeit berechnet, auch wenn der Versuch als undelivered gemeldet wird.

Nächste Schritte