# Verify von Prelude migrieren

Diese Seite ordnet Preludes v2-Verifizierungs-API Bird Verify zu. Folgen Sie dem [Hauptmigrationsleitfaden](/docs/guides/verify/migrate) der Reihe nach und verwenden Sie diese Zuordnungen für die Schritte 1 und 3.

Die Strukturen sind ähnlich. Preludes `POST https://api.prelude.dev/v2/verification` und `POST /v2/verification/check` sind ein Bearer-authentifiziertes Create-and-Check-Paar, das auf dem Empfänger statt auf einer Verifizierungs-ID basiert, und das gilt ebenso für [`POST /v1/verify/verifications`](/docs/api/reference/create-verification) und [`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-check). Ein erneuter Create-Aufruf für einen aktiven Empfänger wiederholt den Versuch, statt eine neue Verifizierung zu starten, auf beiden Plattformen. Was sich nicht portieren lässt, ist die Risikoebene: Preludes Signals, Routing-Verdicts und stille Verifizierung haben kein Gegenstück in der Bird Verify API.

## Übergeben Sie dies Ihrem Agenten

Fügen Sie dies in Claude Code, Cursor oder Codex ein. Der Agent arbeitet diese Seite gegen Ihr eigenes Repository ab und nutzt die Bird-Oberfläche, die er bereits hat: den MCP-Server, falls einer verbunden ist, oder die CLI, falls sie installiert und angemeldet ist.

```text
I am moving a phone verification integration from Prelude to Bird Verify. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/verify/migrate/prelude.md for the create, check and status mapping, and https://bird.com/docs/guides/verify/migrate.md for the order the steps go in.
3. Find and list my Prelude usage in this repository before you change anything: the /v2/verification and /v2/verification/check call sites, anywhere I read signals or a routing verdict, and anywhere I use dispatch_id for retry safety.
4. Tell me early which of these I depend on. Bird Verify has no voice channel and no silent or network-based authentication. It generates the code itself and never returns it, so I cannot supply my own. It accepts `options.language` but no per-request template or message body. Bird can use an existing SMS Sender ID or a connected WhatsApp number with an approved authentication template, configured per channel or country rather than per request; tell me whether my current sender can be kept. Prelude's risk layer does not port either: its signals, its routing verdicts and its silent verification have no counterpart in Bird Verify, so tell me every decision my code makes on those.
5. Configure my channels and destinations following https://bird.com/docs/guides/verify/countries.md and https://bird.com/docs/guides/verify/senders.md. While you are there, disable every country I do not actually verify into. An enabled destination I never send to is not reach, it is exposure to SMS pumping, so ask me which countries I serve rather than leaving the defaults.
6. Port the create and check calls using the mapping tables on the provider page, and move my status handling to Bird's events: https://bird.com/docs/guides/verify/sending-verifications.md and https://bird.com/docs/guides/verify/events.md.
7. Cut over at the create call, not all at once, because a code issued by Prelude cannot be checked by Bird and a code issued by Bird cannot be checked by Prelude. From the moment I say go, send every NEW verification to Bird, and keep routing each check to whichever provider issued that verification. Keep both paths live for one full code lifetime plus margin, then retire the old one. Tell me how you will decide which provider issued a given verification before you write any of it.
8. Test before any real traffic. Bird Verify has no simulated recipients, so do not look for a sandbox: the thing worth testing is the code arriving. Run the integration against a phone number and a mailbox I control, on each channel I enabled, and show me what arrived on each one.
9. Stop and ask me wherever a step needs a decision. Do not start routing new verifications to Bird until I have seen those test results and replied with the words cut over to Bird. Retiring the Prelude path is a separate step: ask me again and wait for me to reply with the words retire the Prelude path, and do not retire it while any code it issued could still be checked. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.
```

## Den Create-Aufruf zuordnen

| Funktion                 | Prelude                                                                          | Bird                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Empfänger                | `target.type` + `target.value`                                                   | `to.phone_number` oder `to.email`                                                                                   |
| Codelänge                | `options.code_size`                                                              | `options.code_length`                                                                                               |
| Kanalpräferenz           | `options.preferred_channel`, `options.channels`                                  | `options.channels`, sonst die konfigurierte Reihenfolge des Landes                                                  |
| Korrelation              | `metadata.correlation_id`                                                        | `metadata`                                                                                                          |
| Zustellungs-Callbacks    | `options.callback_url`                                                           | ein Workspace-Webhook, der die von Ihnen gewünschten Verify-Eventtypen abonniert hat                                |
| Eigener Bestätigungscode | `options.custom_code`                                                            | kein Äquivalent                                                                                                     |
| Lokalisierung            | `options.locale`                                                                 | `options.language`                                                                                                  |
| Absenderidentität        | `options.sender_id`                                                              | einen von Bird verwalteten oder dem Workspace gehörenden Absender pro Kanal oder Land wählen, nicht pro Anfrage     |
| Nachrichtenvorlage       | `options.template_id`, `options.variables`                                       | kein Äquivalent pro Anfrage; ein genehmigtes WhatsApp-Authentifizierungstemplate in der Verify-Konfiguration wählen |
| Android-Autofill         | `options.app_realm`                                                              | kein Äquivalent                                                                                                     |
| Risikosignale            | `signals` (IP, Gerät, Fingerprint)                                               | nicht akzeptiert                                                                                                    |
| Sichere Wiederholungen   | kein Idempotency-Key oder -Header in deren Create- oder Check-Referenz           | `Idempotency-Key`-Header                                                                                            |
| Signals-Korrelation      | `dispatch_id`, "the identifier of the dispatch that came from the front-end SDK" | kein Äquivalent: Bird akzeptiert keine Signale                                                                      |
| Fallback-Steuerung       | `options.max_auto_fallbacks`, `options.force_challenge`                          | der Kanalplan des Landes                                                                                            |

`dispatch_id` ist kein Retry-Mechanismus und gehört nicht neben `Idempotency-Key`. Preludes eigene Referenz definiert es als "the identifier of the dispatch that came from the front-end SDK": deren Signals-SDK gibt es von `dispatchSignals()` zurück, und Sie leiten es beim Create weiter, damit deren Fraud-Schicht die erfassten Browser-Signals dieser Verifizierung zuordnen kann. Deren Create- und Check-Referenzen dokumentieren den vollständigen Request-Satz ohne Idempotency-Key und ohne eigenen Header, sodass ein wiederholter Create nicht für Sie abgesichert wird. Bei Bird übernimmt der [`Idempotency-Key`](/docs/guides/idempotency)-Header diese Aufgabe.

Die Kanalsets überschneiden sich nur teilweise. Bird liefert über E-Mail, SMS, WhatsApp und Telegram; Preludes RCS, Viber, Zalo, Voice und stille Kanäle haben heute kein Bird-Äquivalent. Eine Nummer, die Prelude über Viber oder Zalo erreicht hat, fällt hier auf SMS zurück, was eine Zustellraten-Frage ist, die im Piloten gemessen werden sollte, statt sie erst bei vollem Volumen zu entdecken.

## Den Check-Aufruf zuordnen

Beide Check-Endpunkte nehmen den Empfänger und den Code ohne Verifizierungs-ID entgegen, sodass dieser Aufruf fast unverändert portiert werden kann. Die Antwort ist der Unterschied:

| Prelude `status`       | Bird                                                |
| ---------------------- | --------------------------------------------------- |
| `success`              | `success: true`                                     |
| `failure`              | `success: false`, `reason: incorrect_code`          |
| `expired_or_not_found` | `success: false`, `reason: expired` oder eine `404` |
| (kein direkter Wert)   | `success: false`, `reason: attempts_exhausted`      |

Prelude fasst "wrong code" und "out of attempts" in `failure` zusammen; Bird trennt sie und gibt `attempts_remaining` zusätzlich zurück, damit Sie dem Nutzer zeigen können, wie viele Versuche noch übrig sind. Eine Verifizierung, die bereits abgeschlossen ist, gibt `404` statt eines Status zurück; speichern Sie daher die erste definitive Antwort, statt erneut zu prüfen.

## Was mit der Risikoebene passiert

Preludes Create-Antwort meldet ein Routing-Verdict: ein `status` von `success`, `retry`, `challenged`, `blocked` oder `shadow_blocked`, mit einem `reason` und `risk_factors` bei Ablehnung, und einem `method`, das den gewählten Kanal benennt. Die Create-Antwort von Bird ist die Verifizierung selbst. Es gibt kein Verdict, auf das verzweigt werden kann, kein Signals-Objekt zum Senden und kein Äquivalent eines Shadow-Blocks, sodass eine Integration, die Registrierungen auf Preludes Verdict basiert, eine eigene Entscheidung braucht, bevor sie Bird aufruft.

Was Bird aus diesem Bereich bietet, ist enger gefasst und überwiegend Konfiguration: länderspezifische Aktivierung zum Abschalten von Zielen, die Sie nie bedienen, die in [Abuse-Guardrails](/docs/guides/verify/sending-verifications#abuse-guardrails) beschriebenen Sende- und Check-Limits der Plattform sowie der Kanalplan selbst. Wenn Pumping-Schutz der Grund für Ihre Wahl von Prelude war, bewerten Sie diese Lücke, bevor Sie die Migration planen.

## Die Callbacks migrieren

Prelude sendet den Zustellstatus an die `callback_url`, die Sie pro Verifizierung festlegen. Bird liefert an Endpunkte, die Ihr Workspace registriert, jeweils abonniert auf die gewünschten Eventtypen, sodass die URL aus dem Request-Body entfällt. Benennen Sie die Eventtypen, die Ihr Handler benötigt: `verify.verification.created`, `verify.verification.verified` und `verify.verification.failed` für die Session, und `verify.attempt.sent`, `verify.attempt.delivered` und `verify.attempt.undelivered` für jeden Bestätigungscode-Versand. Es gibt keinen Platzhalter, der sie ersetzt. Verifizieren Sie Signaturen gemäß [Standard Webhooks](https://www.standardwebhooks.com). Die Payloads finden Sie unter [Verify-Events](/docs/guides/verify/events).

## Umstellung

Die [Umstellungsregel](/docs/guides/verify/migrate#5-cut-over-one-code-lifetime-at-a-time) im Hauptleitfaden gilt unverändert: Ein von Prelude ausgestellter Code kann nicht von Bird geprüft werden. Wechseln Sie daher beim Create-Aufruf und leiten Sie jeden Check an den Anbieter weiter, der die jeweilige Verifizierung ausgestellt hat, bis die letzte abläuft. Da beide APIs auf dem Empfänger basieren, ist die Verzweigung eine einzelne Bedingung um Ihre bestehenden Aufrufstellen, kein Umbau.

Beobachten Sie die Conversion während des Piloten zusammen mit der Zustellung. Prelude routet pro Request über ein breiteres Kanalset; Bird routet nach der Kanalreihenfolge, die Sie pro Land festlegen. Wenn die Conversion eines Marktes sinkt, ordnen Sie die Kanäle dieses Landes neu, bevor Sie Schlüsse über die Migration ziehen.

## Nächste Schritte

- [Verifizierungen senden](/docs/guides/verify/sending-verifications): der vollständige Vertrag für beide Aufrufe, Status und Limits
- [Länderkonfiguration](/docs/guides/verify/countries): länderspezifische Kanalreihenfolge und Verfügbarkeit
- [Absender und Branding](/docs/guides/verify/senders): was der Empfänger auf jedem Kanal sieht
- [Verify-Events](/docs/guides/verify/events): die Events, auf die Ihr Callback-Consumer umstellt

## 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)