Verifica il tuo primo cliente

Bird Verify conferma che qualcuno controlla un indirizzo email o un numero di telefono. Chiedi a Bird di inviare un codice di verifica monouso. La persona lo inserisce nella tua app e chiedi a Bird se corrisponde. Bird genera e consegna il codice e applica la scadenza e i limiti di tentativi. La tua app non riceve né memorizza il codice generato.

Questo quickstart verifica il tuo indirizzo email, senza bisogno di configurazione. Bird invia i codici email tramite il mittente condiviso Bird Verify, quindi non serve un dominio né un saldo. Dopo aver ricaricato SMS, verificare un numero di telefono richiede le stesse due chiamate.

1. Crea una chiave API

Nella dashboard, vai su Developers > Chiavi API e crea una chiave. Le chiavi sono limitate a una regione e hanno il formato bk_us1_... o bk_eu1_...; la regione nel prefisso indica quale host API chiamare: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La pagina Chiavi API nella dashboard Bird, con l'elenco delle chiavi, il prefisso mascherato, gli ambiti e l'ultimo utilizzo

La chiave completa viene mostrata una sola volta, al momento della creazione. Copiala in un posto sicuro, poi esportala per gli esempi di invio:

Esempio di codice

export BIRD_API_KEY="bk_us1_..."

2. Invia un codice

Crea una verifica per l'indirizzo che vuoi confermare. L'unico campo obbligatorio è to. Usa il tuo indirizzo email per poter leggere il codice. Installa l'Bird SDK per il tuo linguaggio seguendo il quickstart SDK.

Nelle tab SDK, sostituisci la chiave API e user@example.com di esempio prima di eseguire il codice. CLI usa le tue credenziali di accesso, e la tab cURL usa BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const verification = await bird.verify.verifications.create({
  to: { email: "user@example.com" },
});

console.log(verification.id, verification.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        verification = client.verify.verifications.create(
            to={"email": "user@example.com"},
        )
        print(verification.id, verification.status)
    except APIError as err:
        print("could not start the verification:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
		To: bird.VerificationTo{Email: bird.Email("user@example.com")},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(verification.Id, *verification.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\VerificationCreateRequest;
use MessageBird\Wire\Model\VerificationTo;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())
        ->setTo((new VerificationTo())->setEmail('user@example.com')),
);

echo $verification->getId(), ' ', $verification->getStatus(), "\n";

bird verify verifications create --email user@example.com

curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "email": "user@example.com" }
  }'

Se la tua chiave inizia con bk_eu1_, chiama invece https://eu1.platform.bird.com.

Bird accetta la richiesta e inizia a inviare il codice:

Esempio di codice

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "email": "user@example.com" },
  "channels": [{ "channel": "email" }],
  "last_channel": "email",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

Nessun ID di verifica da salvare: il controllo nel passaggio 3 usa lo stesso destinatario come chiave. L'email arriva da Bird Verify <otp@verify.bird.com> con l'oggetto "Your verification code" e un codice a sei cifre; il messaggio stesso indica quando scade. Lunghezza del codice, durata, limite di tentativi e intervallo di reinvio sono impostazioni dello spazio di lavoro, e impostazioni di verifica elenca i valori predefiniti e gli intervalli.

3. Controlla il codice

Prendi il codice dalla tua casella di posta e invialo, usando lo stesso destinatario come chiave:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const result = await bird.verify.verifications.check({
  to: { email: "user@example.com" },
  code: "123456",
});

console.log(result.success);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        result = client.verify.verifications.check(
            to={"email": "user@example.com"},
            code="123456",
        )
        print(result.success)
    except APIError as err:
        print("could not check the passcode:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
		To:   bird.VerificationTo{Email: bird.Email("user@example.com")},
		Code: "123456",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(*result.Success)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\VerificationCheckRequest;
use MessageBird\Wire\Model\VerificationTo;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setEmail('user@example.com'))
        ->setCode('123456'),
);

echo $result->getSuccess() ? 'verified' : 'not verified', "\n";

bird verify verifications check 123456 --email user@example.com

curl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "email": "user@example.com" },
    "code": "123456"
  }'

Un codice corretto restituisce success: true, e la verifica incorporata passa a verified:

Esempio di codice

{
  "success": true,
  "reason": null,
  "attempts_remaining": null,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "verified",
    "reason": null,
    "to": { "email": "user@example.com" },
    "channels": [{ "channel": "email" }],
    "last_channel": "email",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": "2026-07-23T14:46:47Z",
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:47Z"
  }
}

Prima di aggiungere questo flusso a una registrazione, considera questi esiti:

Un controllo non riuscito restituisce HTTP 200. La risposta contiene success: false, un reason (incorrect_code, expired o attempts_exhausted) e un contatore attempts_remaining finché restano tentativi. Gestisci questo risultato nella tua applicazione. La verifica fallisce definitivamente quando esaurisce i tentativi di controllo.
Una verifica si risolve una sola volta. Dopo aver raggiunto verified (o dopo un fallimento o una scadenza), controllarla di nuovo restituisce un 404. Considera la prima risposta definitiva come quella valida. Se l'utente ha bisogno di un nuovo codice, chiama di nuovo l'endpoint di creazione con lo stesso destinatario: la verifica in corso viene riutilizzata e un nuovo codice viene inviato una volta trascorso l'intervallo di reinvio.

Ogni verifica che crei appare nella pagina Verifications con stato, destinatario, canale e tempistica. Il codice generato non viene mostrato.

La pagina Verifications con l'elenco delle verifiche, le colonne stato, ID di verifica, destinatario, canale, costo e data di creazione

Verifica un numero di telefono

Per verificare tramite SMS, inserisci un numero di telefono in to in formato E.164 al posto di un indirizzo email:

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://{region}.platform.bird.com/v1/verify/verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone_number": "+15551234567"
    },
    "metadata": {
      "correlation_id": "signup-7f3a"
    }
  }'

Il controllo è identico: sostituisci email con lo stesso phone_number. La consegna su telefono utilizza il saldo SMS del tuo spazio di lavoro, e il paese di destinazione determina il percorso. Bird prova prima WhatsApp nella maggior parte dei paesi e prima SMS in alcuni. Configurazione paese mostra e configura i canali disponibili e il loro ordine per ogni destinazione. Mittenti e branding mostra cosa arriva su ciascun canale.

Raggiungi l'utente su entrambi i canali

Non devi scegliere un solo canale. Includi sia un email sia un phone_number in to, e Bird definisce un piano di consegna dalla tua configurazione paese, che mostra i canali disponibili e il loro ordine per ogni destinazione. Bird segue quel piano finché un invio viene accettato. Se la consegna fallisce del tutto, Bird invia un nuovo codice tramite il canale successivo. Controlla il codice con lo stesso oggetto to usato per creare la verifica. L'utente inserisce il codice che ha ricevuto.

Prossimi passaggi

Invio delle verifiche: opzioni, stati, reinvii, impostazioni e limiti in dettaglio.
Configurazione paese: abilita i paesi e imposta l'ordine dei canali per paese.
Mittenti e branding: aspetto dei messaggi con il codice e come inviare email dal tuo dominio.
Reference API di Verify: lo schema completo di richiesta e risposta.
Verificare i numeri di telefono alla registrazione: un video che integra lo stesso flusso in un web shop

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoWhat does OTP mean? One-time passwords explained Esplora la funzionalitàCustomer verification Segui il percorso di apprendimentoBuild your first integration

Prova l'esercitazione e ottieni un brief di implementazione