# Migrer Verify depuis Prelude

Cette page fait correspondre API de l'API v2 de vérification de Prelude avec Bird Verify. Suivez le [guide de migration principal](/docs/guides/verify/migrate) dans l'ordre et utilisez ces correspondances pour les étapes 1 et 3.

Les structures sont proches. `POST https://api.prelude.dev/v2/verification` et `POST /v2/verification/check` de Prelude forment une paire create-and-check authentifiée par bearer et indexée sur la cible plutôt que sur un ID de vérification, tout comme [`POST /v1/verify/verifications`](/docs/api/reference/create-verification) et [`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-check). Appeler create de nouveau pour un destinataire actif relance la vérification au lieu d'en démarrer une nouvelle, sur les deux plateformes. Ce qui ne se transpose pas, c'est la couche de risque : les signaux, les verdicts de routage et la vérification silencieuse de Prelude n'ont pas d'équivalent dans Bird Verify API.

## Confiez ceci à votre agent

Collez ceci dans Claude Code, Cursor ou Codex. L'agent parcourt cette page en s'appuyant sur votre propre dépôt, en utilisant la surface Bird dont il dispose déjà : le serveur MCP s'il est connecté, le CLI s'il est installé et authentifié.

```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.
```

## Faire correspondre l'appel create

| Fonction                          | Prelude                                                                          | Bird                                                                                                                    |
| --------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Destinataire                      | `target.type` + `target.value`                                                   | `to.phone_number` ou `to.email`                                                                                         |
| Longueur du code                  | `options.code_size`                                                              | `options.code_length`                                                                                                   |
| Préférence de canal               | `options.preferred_channel`, `options.channels`                                  | `options.channels`, sinon l'ordre configuré du pays                                                                     |
| Corrélation                       | `metadata.correlation_id`                                                        | `metadata`                                                                                                              |
| Callbacks de livraison            | `options.callback_url`                                                           | un webhook d'espace de travail abonné aux types d'événements Verify que vous indiquez                                   |
| Code de vérification personnalisé | `options.custom_code`                                                            | pas d'équivalent                                                                                                        |
| Localisation                      | `options.locale`                                                                 | `options.language`                                                                                                      |
| Identité de l'expéditeur          | `options.sender_id`                                                              | sélectionnez un expéditeur géré par Bird ou détenu par l'espace de travail, par canal ou par pays, pas par requête      |
| Modèle de message                 | `options.template_id`, `options.variables`                                       | pas d'équivalent par requête ; sélectionnez un modèle d'authentification WhatsApp approuvé dans la configuration Verify |
| Remplissage auto Android          | `options.app_realm`                                                              | pas d'équivalent                                                                                                        |
| Signaux de risque                 | `signals` (IP, appareil, empreinte)                                              | non accepté                                                                                                             |
| Réessais sûrs                     | pas de clé ni d'en-tête d'idempotence dans leur référence create ou check        | en-tête `Idempotency-Key`                                                                                               |
| Corrélation des signaux           | `dispatch_id`, "the identifier of the dispatch that came from the front-end SDK" | pas d'équivalent : Bird n'accepte aucun signal                                                                          |
| Contrôle du repli                 | `options.max_auto_fallbacks`, `options.force_challenge`                          | le plan de canaux du pays                                                                                               |

`dispatch_id` n'est pas un mécanisme de réessai et n'a pas sa place à côté de `Idempotency-Key`. La référence de Prelude le définit comme "the identifier of the dispatch that came from the front-end SDK" : leur SDK Signals le renvoie depuis `dispatchSignals()`, et vous le transmettez au create pour que leur couche antifraude puisse faire correspondre les signaux navigateur captés à cette vérification. Leurs références create et check documentent l'ensemble complet de la requête sans clé d'idempotence ni en-tête personnalisé, de sorte qu'un create rejoué n'est pas rendu sûr pour vous. Sur Bird, c'est l'en-tête [`Idempotency-Key`](/docs/guides/idempotency) qui remplit ce rôle.

Les ensembles de canaux ne se recoupent que partiellement. Bird livre par email, SMS, WhatsApp et Telegram ; les canaux RCS, Viber, Zalo, voix et silencieux de Prelude n'ont pas d'équivalent Bird aujourd'hui. Un numéro que Prelude atteignait via Viber ou Zalo se rabat ici sur SMS, ce qui pose une question de taux de livraison qu'il vaut mieux mesurer en pilote plutôt que de découvrir à plein volume.

## Faire correspondre l'appel check

Les deux endpoints check prennent le destinataire et le code sans ID de vérification, donc cet appel se transpose quasiment tel quel. C'est la réponse qui diffère :

| Prelude `status`        | Bird                                             |
| ----------------------- | ------------------------------------------------ |
| `success`               | `success: true`                                  |
| `failure`               | `success: false`, `reason: incorrect_code`       |
| `expired_or_not_found`  | `success: false`, `reason: expired` ou une `404` |
| (pas de valeur directe) | `success: false`, `reason: attempts_exhausted`   |

Prelude regroupe "wrong code" et "out of attempts" dans `failure` ; Bird les sépare et renvoie `attempts_remaining` en parallèle pour que vous puissiez montrer à l'utilisateur combien de tentatives il lui reste. Une vérification déjà résolue renvoie `404` au lieu d'un statut : stockez donc la première réponse définitive au lieu de revérifier.

## Ce que devient la couche de risque

La réponse create de Prelude rapporte un verdict de routage : un `status` valant `success`, `retry`, `challenged`, `blocked` ou `shadow_blocked`, accompagné d'un `reason` et d'un `risk_factors` en cas de refus, et d'un `method` nommant le canal choisi. La réponse create de Bird est la vérification elle-même. Il n'y a ni verdict sur lequel brancher, ni objet signals à envoyer, ni équivalent d'un blocage fantôme ; une intégration qui conditionne les inscriptions au verdict de Prelude a donc besoin de sa propre décision avant d'appeler Bird.

Ce que Bird offre dans cet espace est plus restreint et relève surtout de la configuration : activation par pays pour couper les destinations que vous ne desservez jamais, les plafonds d'envoi et de vérification décrits dans [Garde-fous contre les abus](/docs/guides/verify/sending-verifications#abuse-guardrails), et le plan de canaux lui-même. Si la protection contre le pumping était la raison de votre choix de Prelude, évaluez cet écart avant de planifier la migration.

## Déplacer les callbacks

Prelude envoie le statut de livraison au `callback_url` que vous définissez par vérification. Bird livre aux endpoints que votre espace de travail enregistre, chacun abonné aux types d'événements souhaités, de sorte que l'URL quitte le corps de la requête. Nommez les types d'événements que votre handler attend : `verify.verification.created`, `verify.verification.verified` et `verify.verification.failed` pour la session, et `verify.attempt.sent`, `verify.attempt.delivered` et `verify.attempt.undelivered` pour chaque envoi de code de vérification. Il n'y a pas de joker qui les remplace tous. Vérifiez les signatures conformément à [Standard Webhooks](https://www.standardwebhooks.com). Les payloads se trouvent dans [Événements Verify](/docs/guides/verify/events).

## Basculer

La [règle de bascule](/docs/guides/verify/migrate#5-cut-over-one-code-lifetime-at-a-time) du guide principal s'applique telle quelle : un code émis par Prelude ne peut pas être vérifié par Bird. Basculez donc au niveau de l'appel create et routez chaque check vers le fournisseur qui a émis cette vérification jusqu'à l'expiration de la dernière. Comme les deux API s'indexent sur le destinataire, la bifurcation est une simple condition autour de vos points d'appel existants, pas une réécriture.

Surveillez la conversion pendant le pilote en même temps que la livraison. Prelude route par requête à travers un ensemble de canaux plus large ; Bird route selon l'ordre des canaux que vous définissez par pays. Si la conversion d'un marché chute, réordonnez les canaux de ce pays avant de tirer des conclusions sur la migration.

## Étapes suivantes

- [Envoyer des vérifications](/docs/guides/verify/sending-verifications) : le contrat complet pour les deux appels, les statuts et les limites
- [Configuration par pays](/docs/guides/verify/countries) : ordre et disponibilité des canaux par pays
- [Expéditeurs et branding](/docs/guides/verify/senders) : ce que le destinataire voit sur chaque canal
- [Événements Verify](/docs/guides/verify/events) : les événements vers lesquels migrer votre consommateur de callbacks

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