# Verify migreren vanaf een andere provider

Gebruik deze handleiding om eenmalige verificatiecodes via telefoon en e-mail (OTP) van een andere verificatieprovider naar Bird Verify te verplaatsen. De migratie is klein, omdat het oppervlak klein is: twee calls vervangen wat het create-en-check-paar van je provider er ook uitziet, en Bird beheert de code, het bericht en het afleverkanaal erachter.

Eén structureel verschil bepaalt de opzet van het werk. Bird heeft geen service-object per applicatie en geen verificatie-ID dat je hoeft bij te houden. Een verificatie wordt geïdentificeerd aan de hand van de ontvanger, dus beide calls nemen dezelfde `to`, en de state die je integratie bijhoudt krimpt tot niets.

De migratiechecklist:

1. [Breng de create- en check-calls in kaart](#1-breng-de-create--en-check-calls-in-kaart)
2. [Stel je kanalen, landen en afzender in](#2-stel-je-kanalen-landen-en-afzender-in)
3. [Porteer de verificatielevenscyclus](#3-porteer-de-verificatielevenscyclus)
4. [Schakel webhooks over](#4-schakel-webhooks-over)
5. [Migreer per codelevensduur](#5-schakel-over-met-één-codelevensduur-tegelijk)

Stap 1 en 3 hangen af van welke provider je verlaat. Je [providergids](#migreren-vanaf-een-specifieke-provider) bevat de veld-voor-veld-mapping en de statusvertaling.

## 1. Breng de create- en check-calls in kaart

[`POST /v1/verify/verifications`](/docs/api/reference/create-verification) verstuurt een verificatiecode. Het kleinste verzoek is een ontvanger:

```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) verstuurt wat de gebruiker heeft ingetypt, op basis van dezelfde ontvanger plus de code. De volledige payloads staan in [Verificaties versturen](/docs/guides/verify/sending-verifications).

Vier verschillen om rekening mee te houden bij het porten:

- **De ontvanger is de sleutel.** Providers die een verificatie-SID of -ID teruggeven, verwachten dat bij de check. Bird matcht in plaats daarvan op de adresset, en die moet exact overeenkomen: een verificatie die is aangemaakt met zowel een e-mailadres als een telefoonnummer wordt niet gevonden met slechts één van beide. De kolom die het verificatie-ID van de provider bevat kun je verwijderen.
- **Een verkeerde code geeft `200` terug.** Het antwoord bevat `success: false`, een `reason` van `incorrect_code`, `expired` of `attempts_exhausted`, en `attempts_remaining`. Reserveer je foutpad voor mislukte verzoeken. Zodra een verificatie een eindstatus bereikt, geven verdere checks `404` terug in plaats van `success: false`.
- **Bird genereert de code en geeft die nooit terug.** Er is geen custom-code-parameter, dus een providerintegratie die een eigen verificatiecode meegaf, of de code terugleesde om die zelf te versturen, heeft hier geen equivalent.
- **Beide endpoints accepteren `Idempotency-Key`.** Een replay na een timeout geeft het oorspronkelijke antwoord terug zonder een nieuwe code te versturen of een poging te verbruiken.

Per-request-opties zijn bewust beperkt: `options.code_length` en `options.channels`, waarmee je de kanalen voor één verzoek herschikt of beperkt. Al het andere is werkruimteconfiguratie in plaats van een veld op de verstuuractie.

## 2. Stel je kanalen, landen en afzender in

Bird levert codes af via e-mail, SMS, WhatsApp en Telegram. Voor een telefoongeadresseerde proberen de meeste landen eerst WhatsApp met SMS als terugvaloptie, en de aflevering gaat door naar het volgende kanaal in het plan wanneer een verzending mislukt. Stel de volgorde in, of schakel een kanaal uit, per land op de [**Countries**](https://bird.com/dashboard/w/verify/countries)-pagina; schakel de landen die je niet bedient meteen uit, want een ongebruikte bestemming is blootstelling aan SMS-pumping in plaats van bereik.

Twee hiaten zijn het waard om te controleren tegen je huidige flow voordat je een datum vastlegt:

- **Er is geen spraakoproepkanaal en geen stille netwerkauthenticatie.** Een flow die terugvalt op een telefoonoproep voor gebruikers die geen SMS kunnen ontvangen, heeft hier een andere oplossing nodig.
- **Kies de afzender vóór de cutover.** E-mail, SMS en WhatsApp gebruiken standaard Bird Verify en kunnen in plaats daarvan Authifly gebruiken. Je kunt ook je geverifieerde e-maildomein, een bestaand SMS Sender ID of een gekoppeld WhatsApp-nummer met een goedgekeurd authenticatietemplate gebruiken. Telegram gebruikt een eigen geverifieerd notificatieaccount. Als je een SMS-afzender wilt behouden die je gebruikers al herkennen, controleer dan of deze wordt ondersteund en geregistreerd is in elk bestemmingsland. [Afzenders en branding](/docs/guides/verify/senders) behandelt de keuzes en het fallbackgedrag.

Als je je eigen WhatsApp-nummer gebruikt, selecteer dan een bestaand goedgekeurd authenticatietemplate in je Verify-configuratie. Bird beheert de e-mail- en SMS-berichttekst. Je kunt geen template-ID of aangepaste berichttekst meegeven bij een individueel verificatieverzoek.

## 3. Porteer de verificatielevenscyclus

Een verificatie is `pending` totdat ze wordt afgerond: `verified` wanneer een correcte code op tijd binnenkomt, `failed` met reden `attempts_exhausted` of `undeliverable`, of `expired` met reden `ttl_elapsed`. Vertaal de eindstatussen van je provider naar die drie, en behandel `reason` als een open enum.

De timings die je UI bepalen zijn werkruimte-instellingen op de [**Configure**](https://bird.com/dashboard/w/verify/configure)-pagina: hoe lang een code geldig blijft, hoeveel checkpogingen een gebruiker krijgt, en hoe lang de cooldown voor opnieuw versturen duurt. Stel ze in zodat ze overeenkomen met wat je gebruikers nu ervaren, in plaats van je UI-tekst te herschrijven. Codelengte is de enige waarde die je ook per verzoek kunt instellen. De standaardwaarden en bereiken staan in [Verificatie-instellingen](/docs/guides/verify/sending-verifications#verification-settings).

Twee gedragingen vervangen meestal code die je al hebt:

- **Opnieuw versturen is nogmaals de create-call.** Roep create aan met dezelfde ontvanger: binnen de cooldown geeft het de actieve verificatie terug zonder te versturen, en daarna gaat er een nieuwe code uit. Elke code die is verstuurd voor een actieve verificatie blijft geldig totdat de verificatie wordt afgerond, dus een gebruiker die de eerste code invoert nadat de tweede is aangekomen, wordt daar niet voor gestraft.
- **"I didn't get a code" heeft een eigen endpoint.** [`POST /v1/verify/verifications/next-channel`](/docs/api/reference/create-verification-next-channel) gaat door naar het volgende kanaal in het plan en verstuurt daar direct, waarbij de cooldown voor opnieuw versturen wordt genegeerd maar de vervaltijd, het pogingsbudget en de verificatie behouden blijven. Koppel het aan de knop in plaats van herhaaldelijk te versturen op een kanaal dat niet aankomt.

Bovenop je instellingen zitten platformbeveiligingen die je niet configureert: een limiet per adres per uur voor versturen en een limiet per ontvanger voor checks, beide beantwoord met een `429` en een `Retry-After`. Als je huidige provider je per-endpoint-limieten liet verhogen en je dat hebt gedaan, controleer dan je piek tegen de cijfers in [Misbruikbeveiligingen](/docs/guides/verify/sending-verifications#abuse-guardrails) vóór de migratie.

## 4. Schakel webhooks over

Verify zendt events uit op twee assen. Sessie-events, `verify.verification.created`, `verify.verification.verified` en `verify.verification.failed`, volgen de verificatie zelf. Poging-events, `verify.attempt.sent`, `verify.attempt.delivered` en `verify.attempt.undelivered`, volgen elke individuele verificatiecodeversturing, dus een opnieuw versturen of een kanaalfailover voegt pogingen toe aan dezelfde sessie. Abonneer een endpoint op de typen die je wilt met [`POST /v1/webhooks`](/docs/api/reference/create-webhook); de payloads staan in [Verify events](/docs/guides/verify/events).

Abonneer je op de sessie-events die je integratie nodig heeft. `verify.verification.failed` dekt het doodlopende bezorgpad: het vuurde met `reason: "undeliverable"` wanneer het plan is uitgeput en de geregistreerde fouten aangeven dat er geen verificatiecode is verstuurd, en `last_attempt_reason` bevat de fout op het laatst geprobeerde kanaal. Een verificatie die verloopt of haar checkpogingen uitput, zendt geen sessie-event uit, dus haal die twee uitkomsten uit het check-antwoord.

Deze events dienen voor analytics, alerting en supporttooling. Je authenticatiebeslissing komt van de check-call, die synchroon antwoordt, en een loginflow mag nooit op een webhook wachten om een gebruiker binnen te laten. Bezorging is at-least-once en ongeordend, ondertekend volgens [Standard Webhooks](https://www.standardwebhooks.com), dus deduplicate op de `webhook-id`-header op dezelfde manier als bij elk ander Bird-event.

## 5. Schakel over met één codelevensduur tegelijk

Verify heeft geen gesimuleerde ontvangers: wat je wilt testen is dat de code aankomt, dus voer de integratie uit tegen een telefoonnummer en een mailbox die je beheert, op elk kanaal dat je hebt ingeschakeld, voordat je productie aanraakt.

De overschakeling zelf heeft één regel die je makkelijk mist. **Een code die je oude provider heeft uitgegeven, kan niet door Bird worden gecontroleerd, en andersom.** Schakel dus over bij de create-call, en routeer gedurende de duur van één codelevensduur elke check naar de provider die die verificatie heeft uitgegeven. In de praktijk:

1. Registreer welke provider elke actieve verificatie heeft aangemaakt.
2. Begin een deel van de nieuwe verificaties via Bird te versturen en check die tegen Bird.
3. Blijf oudere verificaties tegen de oude provider checken totdat de laatste verloopt; dat kost één geldigheidsvenster van de code plus een marge.
4. Verhoog het aandeel van Bird zodra de conversiepercentages van de eerste groep er goed uitzien, en zet daarna het oude pad uit.

Let op conversie, niet alleen op bezorging. De [**Verifications**](https://bird.com/dashboard/w/verify/verifications)-pagina en de Verify-metrics tonen versturingen, bezorgingen en hoeveel verificaties `verified` bereikten; dat is het getal dat je vertelt of een kanaalvolgorde of een nieuwe afzenderidentiteit je aanmeldingen kost.

## Migreren vanaf een specifieke provider

- [Twilio Verify](/docs/guides/verify/migrate/twilio): Services worden werkruimte-instellingen, `VerificationCheck` wordt een op ontvanger gebaseerde check, kanaal- en statusvertaling
- [Prelude](/docs/guides/verify/migrate/prelude): een vrijwel identieke create-en-check-opzet, met routeringssignalen en stille verificatie als de onderdelen die niet meekomen

## Volgende stappen

- [Verificaties versturen](/docs/guides/verify/sending-verifications): het volledige request- en responsecontract, statussen en limieten
- [Landconfiguratie](/docs/guides/verify/countries): kanaalvolgorde en beschikbaarheid per land
- [Afzenders en branding](/docs/guides/verify/senders): hoe elk bericht eruitziet, en de branded e-mailafzender
- [Verify events](/docs/guides/verify/events): sessie- en poging-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)