# Verify von einem anderen Anbieter migrieren

Nutzen Sie diese Anleitung, um telefonische und E-Mail-Einmalpasswörter (OTP) von einem anderen Verifizierungsanbieter zu Bird Verify zu migrieren. Der Aufwand ist gering, weil die Oberfläche gering ist: Zwei Aufrufe ersetzen das Create-and-Check-Paar Ihres bisherigen Anbieters, und Bird verwaltet den Code, die Nachricht und den Zustellkanal dahinter.

Ein struktureller Unterschied bestimmt den Umfang der Arbeit. Bird hat kein anwendungsbezogenes Service-Objekt und keine Verification-ID, die Sie nachverfolgen müssten. Eine Verifizierung wird über den Empfänger identifiziert, beide Aufrufe verwenden daher denselben `to`, und der Zustand, den Ihre Integration vorhalten muss, schrumpft auf null.

Die Migrations-Checkliste:

1. [Create- und Check-Aufrufe zuordnen](#1-create--und-check-aufrufe-zuordnen)
2. [Kanäle, Länder und Absender festlegen](#2-kanäle-länder-und-absender-festlegen)
3. [Verifizierungslebenszyklus portieren](#3-verifizierungslebenszyklus-portieren)
4. [Webhooks umstellen](#4-webhooks-umstellen)
5. [Pro Code-Lebensdauer umschalten](#5-schrittweise-umstellen-jeweils-eine-code-lebensdauer)

Die Schritte 1 und 3 hängen davon ab, welchen Anbieter Sie verlassen. Ihr [Anbieter-Leitfaden](#migration-von-einem-bestimmten-anbieter) enthält die feldweise Zuordnung und die Status-Übersetzung.

## 1. Create- und Check-Aufrufe zuordnen

[`POST /v1/verify/verifications`](/docs/api/reference/create-verification) sendet einen Bestätigungscode. Die kleinste Anfrage besteht aus einem Empfänger:

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

[`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-check) übermittelt die Eingabe des Nutzers, adressiert über denselben Empfänger plus den Code. Die vollständigen Payloads finden Sie unter [Verifizierungen senden](/docs/guides/verify/sending-verifications).

Vier Unterschiede, die Sie beim Portieren beachten müssen:

- **Der Empfänger ist der Schlüssel.** Anbieter, die eine Verification-SID oder -ID zurückgeben, erwarten sie beim Check zurück. Bird gleicht stattdessen über das Adress-Set ab, und es muss exakt übereinstimmen: Eine Verifizierung, die mit E-Mail und Telefonnummer erstellt wurde, wird nicht gefunden, wenn nur eine davon angegeben wird. Die Spalte, die bisher die Verification-ID des Anbieters enthält, kann entfallen.
- **Ein falscher Code liefert `200` zurück.** Die Antwort enthält `success: false`, einen `reason` mit dem Wert `incorrect_code`, `expired` oder `attempts_exhausted` sowie `attempts_remaining`. Reservieren Sie Ihren Fehlerpfad für fehlgeschlagene Anfragen. Sobald eine Verifizierung einen Endzustand erreicht hat, liefern weitere Checks `404` statt `success: false`.
- **Bird erzeugt den Code und gibt ihn nie zurück.** Es gibt keinen Custom-Code-Parameter. Eine Anbieter-Integration, die einen eigenen Bestätigungscode übergeben oder den Code ausgelesen hat, um ihn selbst zu versenden, hat hier keine Entsprechung.
- **Beide Endpunkte akzeptieren `Idempotency-Key`.** Ein Replay nach einem Timeout gibt die ursprüngliche Antwort zurück, ohne einen weiteren Code zu senden oder einen Versuch zu verbrauchen.

Per-Request-Optionen sind bewusst wenige: `options.code_length` und `options.channels`, womit Sie die Kanäle für eine einzelne Anfrage umsortieren oder einschränken. Alles andere ist Workspace-Konfiguration und kein Feld im Send-Aufruf.

## 2. Kanäle, Länder und Absender festlegen

Bird liefert Codes per E-Mail, SMS, WhatsApp und Telegram. Für einen Telefonempfänger versuchen die meisten Länder zuerst WhatsApp mit SMS als Fallback, und die Zustellung rückt zum nächsten Kanal im Plan vor, wenn ein Versand fehlschlägt. Legen Sie die Reihenfolge fest oder deaktivieren Sie einen Kanal pro Land auf der Seite [**Countries**](https://bird.com/dashboard/w/verify/countries); deaktivieren Sie dort auch die Länder, die Sie nicht bedienen, denn ein ungenutztes Ziel ist kein Reichweitengewinn, sondern Angriffsfläche für SMS-Pumping.

Zwei Lücken sollten Sie vor einem festen Termin mit Ihrem aktuellen Ablauf abgleichen:

- **Es gibt keinen Sprachanruf-Kanal und keine stille Netzwerk-Authentifizierung.** Ein Ablauf, der für Nutzer, die SMS nicht empfangen können, auf einen Telefonanruf zurückfällt, braucht hier eine andere Lösung.
- **Wählen Sie den Absender vor der Umstellung.** E-Mail, SMS und WhatsApp verwenden standardmäßig Bird Verify und können stattdessen Authifly nutzen. Sie können auch Ihre verifizierte E-Mail-Domain, eine vorhandene SMS-Absenderkennung oder eine verbundene WhatsApp-Nummer mit einem genehmigten Authentifizierungstemplate verwenden. Telegram nutzt einen eigenen verifizierten Benachrichtigungsaccount. Wenn Sie einen SMS-Absender beibehalten möchten, den Ihre Nutzer bereits kennen, prüfen Sie, ob er in jedem Zielland unterstützt und registriert ist. [Absender und Branding](/docs/guides/verify/senders) beschreibt die Optionen und das Fallback-Verhalten.

Wenn Sie Ihre eigene WhatsApp-Nummer verwenden, wählen Sie in Ihrer Verify-Konfiguration ein vorhandenes genehmigtes Authentifizierungstemplate aus. Bird steuert den E-Mail- und SMS-Nachrichtentext. Sie können weder eine Template-ID noch einen individuellen Nachrichtentext in einer einzelnen Verifizierungsanfrage übergeben.

## 3. Verifizierungslebenszyklus portieren

Eine Verifizierung ist `pending`, bis sie sich auflöst: `verified`, wenn ein korrekter Code rechtzeitig eintrifft, `failed` mit Grund `attempts_exhausted` oder `undeliverable`, oder `expired` mit Grund `ttl_elapsed`. Bilden Sie die Endstatus Ihres Anbieters auf diese drei ab und behandeln Sie `reason` als offenes Enum.

Die Zeitvorgaben, die Ihre UI prägen, sind Workspace-Einstellungen auf der Seite [**Configure**](https://bird.com/dashboard/w/verify/configure): wie lange ein Code gültig bleibt, wie viele Check-Versuche ein Nutzer hat und wie lange die Resend-Abklingzeit läuft. Stellen Sie sie so ein, dass sie dem entsprechen, was Ihre Nutzer heute erleben, statt Ihre UI-Texte umzuschreiben. Die Codelänge ist der einzige Wert, den Sie auch pro Anfrage setzen können. Die Standardwerte und Bereiche finden Sie unter [Verifizierungseinstellungen](/docs/guides/verify/sending-verifications#verification-settings).

Zwei Verhaltensweisen ersetzen in der Regel Code, den Sie bereits haben:

- **Erneutes Senden ist ein weiterer Create-Aufruf.** Rufen Sie Create mit demselben Empfänger auf: Innerhalb der Abklingzeit gibt er die laufende Verifizierung zurück, ohne zu senden, und danach wird ein neuer Code verschickt. Jeder für eine laufende Verifizierung gesendete Code bleibt gültig, bis die Verifizierung aufgelöst wird. Ein Nutzer, der den ersten Code eingibt, nachdem der zweite angekommen ist, wird dafür nicht bestraft.
- **"I didn't get a code" hat einen eigenen Endpunkt.** [`POST /v1/verify/verifications/next-channel`](/docs/api/reference/create-verification-next-channel) rückt zum nächsten Kanal im Plan vor und sendet dort sofort, wobei die Resend-Abklingzeit ignoriert, aber Ablaufzeit, Versuchsbudget und Verifizierung beibehalten werden. Verknüpfen Sie ihn mit dem Button, statt Resends auf einem Kanal zu wiederholen, der nicht ankommt.

Über Ihren Einstellungen liegen Plattform-Leitplanken, die Sie nicht konfigurieren: ein stündliches Sendelimit pro Adresse und ein Check-Limit pro Empfänger, die beide mit einem `429` und einem `Retry-After` beantwortet werden. Wenn Ihr bisheriger Anbieter es erlaubt hat, Rate-Limits pro Endpunkt zu erhöhen, und Sie das getan haben, prüfen Sie Ihren Spitzenwert vor der Umstellung gegen die Werte in [Missbrauchsschutz](/docs/guides/verify/sending-verifications#abuse-guardrails).

## 4. Webhooks umstellen

Verify sendet Events auf zwei Achsen. Session-Events, `verify.verification.created`, `verify.verification.verified` und `verify.verification.failed`, folgen der Verifizierung selbst. Attempt-Events, `verify.attempt.sent`, `verify.attempt.delivered` und `verify.attempt.undelivered`, folgen jedem einzelnen Bestätigungscode-Versand, sodass ein erneuter Versand oder ein Kanal-Failover dem gleichen Session weitere Attempts hinzufügt. Abonnieren Sie einen Endpunkt für die gewünschten Typen mit [`POST /v1/webhooks`](/docs/api/reference/create-webhook); die Payloads finden Sie unter [Verify-Events](/docs/guides/verify/events).

Abonnieren Sie die Session-Events, die Ihre Integration benötigt. `verify.verification.failed` deckt die Zustellsackgasse ab: Es wird mit `reason: "undeliverable"` ausgelöst, wenn der Plan erschöpft ist und die aufgezeichneten Fehler darauf hinweisen, dass kein Bestätigungscode gesendet wurde, und `last_attempt_reason` benennt den Fehler auf dem letzten versuchten Kanal. Eine Verifizierung, die abläuft oder ihre Prüfversuche aufbraucht, löst kein Session-Event aus – entnehmen Sie diese beiden Ergebnisse stattdessen der Check-Antwort.

Diese Events dienen Analysen, Alerting und Support-Tooling. Ihre Authentifizierungsentscheidung kommt vom Check-Aufruf, der synchron antwortet, und ein Login-Flow sollte niemals auf einen Webhook warten, um einen Benutzer einzulassen. Die Zustellung erfolgt at-least-once und ungeordnet, signiert gemäß [Standard Webhooks](https://www.standardwebhooks.com). Deduplizieren Sie anhand des `webhook-id`-Headers genauso wie bei jedem anderen Bird-Event.

## 5. Schrittweise umstellen, jeweils eine Code-Lebensdauer

Verify hat keine simulierten Empfänger: Was sich zu testen lohnt, ist der ankommende Code. Führen Sie die Integration daher vor dem Produktiveinsatz gegen eine Telefonnummer und ein Postfach aus, die Sie kontrollieren, auf jedem aktivierten Kanal.

Die Umstellung selbst hat eine Regel, die leicht übersehen wird. **Ein vom alten Anbieter ausgestellter Code kann nicht von Bird geprüft werden und umgekehrt.** Wechseln Sie daher beim Create-Aufruf, und leiten Sie für die Dauer einer Code-Lebensdauer jeden Check an den Anbieter weiter, der die jeweilige Verifizierung ausgestellt hat. In der Praxis:

1. Halten Sie fest, welcher Anbieter jede laufende Verifizierung erstellt hat.
2. Senden Sie einen Anteil neuer Verifizierungen über Bird und prüfen Sie diese gegen Bird.
3. Prüfen Sie ältere Verifizierungen weiterhin gegen den alten Anbieter, bis die letzte abläuft – das dauert ein Code-Gültigkeitsfenster plus einen Puffer.
4. Erhöhen Sie den Anteil von Bird, sobald die Konversionsraten der ersten Kohorte stimmen, und stellen Sie dann den alten Pfad ein.

Beobachten Sie die Konversion, nicht nur die Zustellung. Die Seite [**Verifications**](https://bird.com/dashboard/w/verify/verifications) und die Verify-Metriken zeigen Sendungen, Zustellungen und wie viele Verifizierungen `verified` erreicht haben – das ist die Zahl, die Ihnen verrät, ob eine Kanalreihenfolge oder eine neue Absenderidentität Sie Registrierungen kostet.

## Migration von einem bestimmten Anbieter

- [Twilio Verify](/docs/guides/verify/migrate/twilio): Services werden zu Workspace-Einstellungen, `VerificationCheck` wird zu einem empfängerbasierten Check, Kanal- und Statusübersetzung
- [Prelude](/docs/guides/verify/migrate/prelude): eine nahezu identische Create-und-Check-Struktur, wobei Routing-Signale und stille Verifizierung die Teile sind, die sich nicht portieren lassen

## Nächste Schritte

- [Verifizierungen senden](/docs/guides/verify/sending-verifications): der vollständige Request- und Response-Vertrag, Status und Limits
- [Länderkonfiguration](/docs/guides/verify/countries): Kanalreihenfolge und Verfügbarkeit pro Land
- [Absender und Branding](/docs/guides/verify/senders): wie jede Nachricht aussieht und der gebrandete E-Mail-Absender
- [Verify-Events](/docs/guides/verify/events): Session- und Attempt-Event-Payloads

## Related resources

- [Verify phone numbers at signup](/learn/series/verify-phone-numbers-at-signup) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Customer verification](/verify-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=verify)