API Reference

Create or retry a verification

Create a new verification for a specific phone number. If another non-expired verification exists (the request is performed within the verification window), this endpoint will perform a retry instead.

On a retry, only method, preferred_channel, code_size and custom_code apply. All other options, including callback_url and correlation_id, are fixed from the first request and ignored. Webhooks for every attempt go to the callback_url of the first request.

POST

verification

import Prelude from "@prelude.so/sdk";

const client = new Prelude();

async function main() {
  const verification = await client.verification.create({
    target: {
      type: "phone_number",
      value: "+30123456789",
    },
  });

  console.log(verification.id);
}

main();

package main

import (
  	"context"
  	"fmt"

  	"github.com/prelude-so/go-sdk"
  	"github.com/prelude-so/go-sdk/option"
)

func main() {
	client := prelude.NewClient()

	verification, err := client.Verification.New(context.TODO(), prelude.VerificationNewParams{
		Target: prelude.F(prelude.VerificationNewParamsTarget{
			Type:  prelude.F(prelude.VerificationNewParamsTargetTypePhoneNumber),
			Value: prelude.F("+30123456789"),
		}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", verification.ID)
}

import os
from prelude_python_sdk import Prelude

client = Prelude()

verification = client.verification.create(
    target={
        "type": "phone_number",
        "value": "+30123456789",
    },
)

print(verification.id)

  import so.prelude.sdk.client.PreludeClient;
  import so.prelude.sdk.client.okhttp.PreludeOkHttpClient;
  import so.prelude.sdk.models.VerificationCreateParams;
  import so.prelude.sdk.models.VerificationCreateResponse;

  // Configures using the `API_TOKEN` environment variable
  PreludeClient client = PreludeOkHttpClient.fromEnv();

  VerificationCreateParams params = VerificationCreateParams.builder()
      .target(VerificationCreateParams.Target.builder()
          .type(VerificationCreateParams.Target.Type.PHONE_NUMBER)
          .value("+30123456789")
          .build())
      .build();
  VerificationCreateResponse verification = client.verification().create(params);

require "bundler/setup"
require "prelude_sdk"

prelude = PreludeSDK::Client.new(
  api_token: ENV["API_TOKEN"] # This is the default and can be omitted
)

verification = prelude.verification
  .create(target: {type: "phone_number", value: "+30123456789"})

puts(verification.id)

{
  "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
  "status": "success",
  "method": "email",
  "reason": "invalid_phone_number",
  "risk_factors": [
    "proxy_network",
    "fraud_database"
  ],
  "channels": [
    "rcs"
  ],
  "silent": {
    "request_url": "<string>"
  },
  "metadata": {
    "correlation_id": "<string>"
  },
  "request_id": "<string>"
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Contact support for more throughput.",
  "type": "rate_limited"
}

import Prelude from "@prelude.so/sdk";

const client = new Prelude();

async function main() {
  const verification = await client.verification.create({
    target: {
      type: "phone_number",
      value: "+30123456789",
    },
  });

  console.log(verification.id);
}

main();

package main

import (
  	"context"
  	"fmt"

  	"github.com/prelude-so/go-sdk"
  	"github.com/prelude-so/go-sdk/option"
)

func main() {
	client := prelude.NewClient()

	verification, err := client.Verification.New(context.TODO(), prelude.VerificationNewParams{
		Target: prelude.F(prelude.VerificationNewParamsTarget{
			Type:  prelude.F(prelude.VerificationNewParamsTargetTypePhoneNumber),
			Value: prelude.F("+30123456789"),
		}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", verification.ID)
}

import os
from prelude_python_sdk import Prelude

client = Prelude()

verification = client.verification.create(
    target={
        "type": "phone_number",
        "value": "+30123456789",
    },
)

print(verification.id)

  import so.prelude.sdk.client.PreludeClient;
  import so.prelude.sdk.client.okhttp.PreludeOkHttpClient;
  import so.prelude.sdk.models.VerificationCreateParams;
  import so.prelude.sdk.models.VerificationCreateResponse;

  // Configures using the `API_TOKEN` environment variable
  PreludeClient client = PreludeOkHttpClient.fromEnv();

  VerificationCreateParams params = VerificationCreateParams.builder()
      .target(VerificationCreateParams.Target.builder()
          .type(VerificationCreateParams.Target.Type.PHONE_NUMBER)
          .value("+30123456789")
          .build())
      .build();
  VerificationCreateResponse verification = client.verification().create(params);

require "bundler/setup"
require "prelude_sdk"

prelude = PreludeSDK::Client.new(
  api_token: ENV["API_TOKEN"] # This is the default and can be omitted
)

verification = prelude.verification
  .create(target: {type: "phone_number", value: "+30123456789"})

puts(verification.id)

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

target

object

required

The verification target. Either a phone number or an email address. To use the email verification feature contact us to discuss your use case.

Show child attributes

signals

object

The signals used for anti-fraud. For more details, refer to Signals.

Show child attributes

options

object

Verification options

Show child attributes

metadata

object

The metadata for this verification. This object will be returned with every response or webhook sent that refers to this verification.

Show child attributes

dispatch_id

string

The identifier of the dispatch that came from the front-end SDK.

Required string length: 36

Example:

"123e4567-e89b-12d3-a456-426614174000"

Callbacks

POST

{$request.body#/options/callback_url}webhook_event

Body

application/json

string

required

The event identifier.

Example:

"evt_01hynf45qvevj844m9az2x2f3c"

created_at

string<date-time>

required

The event creation date.

Example:

"2028-01-01T00:00:00Z"

type

string

required

The event type.

Example:

"<message_type>"

payload

object

required

The event payload.

Show child attributes

Response

Your server accepted the event and will process it.

Response

string

required

The verification identifier.

Example:

"vrf_01jc0t6fwwfgfsq1md24mhyztj"

status

enum<string>

required

The status of the verification.

success - A new verification window was created.
retry - A new attempt was created for an existing verification window.
challenged - The verification is suspicious and is restricted to non-SMS and non-voice channels only. This mode must be enabled for your customer account by Prelude support.
blocked - The verification was blocked.
shadow_blocked - The verification triggered a block rule but the decision was not enforced; this is used to dry-run anti-fraud configuration. This mode must be enabled for your customer account by Prelude support.

Available options:

success,

retry,

challenged,

blocked,

shadow_blocked

Example:

"success"

method

enum<string>

required

The method used for verifying this phone number.

Available options:

email,

message,

silent,

voice

reason

enum<string>

The reason why the verification was blocked. Only present when status is "blocked" or "shadow_blocked".

expired_signature - The signature of the SDK signals is expired. They should be sent within the hour following their collection.
in_block_list - The phone number is part of the configured block list.
invalid_phone_line - The phone number is not a valid line number (e.g. landline).
invalid_phone_number - The phone number is not a valid phone number (e.g. unallocated range).
invalid_signature - The SDK signature did not verify, so the request cannot be attributed to the device it claims to come from.
repeated_attempts - The phone number exceeded the allowed number of verification attempts in a short period.
suspicious - The verification attempt was deemed suspicious by the anti-fraud system.

Available options:

expired_signature,

in_block_list,

invalid_phone_line,

invalid_phone_number,

invalid_signature,

repeated_attempts,

suspicious

Example:

"invalid_phone_number"

risk_factors

enum<string>[]

The risk factors that contributed to the verification being blocked. Only present when status is "blocked" or "shadow_blocked" and the anti-fraud system detected specific risk signals.

automation_signature - The request appears to come from an automated client rather than a person.
carrier_not_permitted - The destination carrier is one this account does not accept traffic for.
client_fingerprint_mismatch - The client does not appear to be the platform it identifies itself as.
custom_policy - A rule configured for your account matched this request.
device_emulator - The request appears to come from an emulator rather than a physical device.
device_not_permitted - The device platform is one your account blocks.
device_reuse - One device is driving verifications for an unusual number of phone numbers.
expired_signals - The SDK signals were collected too long before the request to still attest to it.
fraud_database - The phone number is flagged in one or more of the fraud databases Prelude consults.
invalid_signature - The SDK signature did not verify, so the request cannot be attributed to the device it claims to come from.
ip_concentration - The request shares its origin with an unusual volume of other verifications.
ip_reputation - The originating IP address is not trusted.
location_mismatch - The network location and the phone number's country are inconsistent.
missing_signals - The verification expected Prelude SDK signals and none arrived.
number_range_abuse - The phone number belongs to a range currently associated with abuse.
poor_conversion_history - Traffic resembling this request rarely completes a verification.
proxy_network - The request did not arrive over the subscriber's own access network.
repeated_attempts - The phone number exceeded the allowed number of verification attempts in a short period.
temporary_phone_number - The phone number belongs to a disposable or short-lived numbering service.

Available options:

automation_signature,

carrier_not_permitted,

client_fingerprint_mismatch,

custom_policy,

device_emulator,

device_not_permitted,

device_reuse,

expired_signals,

fraud_database,

invalid_signature,

ip_concentration,

ip_reputation,

location_mismatch,

missing_signals,

number_range_abuse,

poor_conversion_history,

proxy_network,

repeated_attempts,

temporary_phone_number

Example:

["proxy_network", "fraud_database"]

channels

enum<string>[]

The ordered sequence of channels to be used for verification

Available options:

rcs,

silent,

sms,

telegram,

viber,

voice,

whatsapp,

zalo

silent

object

The silent verification specific properties.

Show child attributes

metadata

object

The metadata for this verification.

Show child attributes

request_id

string

The identifier of this request. The verify.attempt and verify.delivery_status webhook events of the attempts this request starts return the same request_id.

import Prelude from "@prelude.so/sdk";

const client = new Prelude();

async function main() {
  const verification = await client.verification.create({
    target: {
      type: "phone_number",
      value: "+30123456789",
    },
  });

  console.log(verification.id);
}

main();

package main

import (
  	"context"
  	"fmt"

  	"github.com/prelude-so/go-sdk"
  	"github.com/prelude-so/go-sdk/option"
)

func main() {
	client := prelude.NewClient()

	verification, err := client.Verification.New(context.TODO(), prelude.VerificationNewParams{
		Target: prelude.F(prelude.VerificationNewParamsTarget{
			Type:  prelude.F(prelude.VerificationNewParamsTargetTypePhoneNumber),
			Value: prelude.F("+30123456789"),
		}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", verification.ID)
}

import os
from prelude_python_sdk import Prelude

client = Prelude()

verification = client.verification.create(
    target={
        "type": "phone_number",
        "value": "+30123456789",
    },
)

print(verification.id)

  import so.prelude.sdk.client.PreludeClient;
  import so.prelude.sdk.client.okhttp.PreludeOkHttpClient;
  import so.prelude.sdk.models.VerificationCreateParams;
  import so.prelude.sdk.models.VerificationCreateResponse;

  // Configures using the `API_TOKEN` environment variable
  PreludeClient client = PreludeOkHttpClient.fromEnv();

  VerificationCreateParams params = VerificationCreateParams.builder()
      .target(VerificationCreateParams.Target.builder()
          .type(VerificationCreateParams.Target.Type.PHONE_NUMBER)
          .value("+30123456789")
          .build())
      .build();
  VerificationCreateResponse verification = client.verification().create(params);

require "bundler/setup"
require "prelude_sdk"

prelude = PreludeSDK::Client.new(
  api_token: ENV["API_TOKEN"] # This is the default and can be omitted
)

verification = prelude.verification
  .create(target: {type: "phone_number", value: "+30123456789"})

puts(verification.id)

{
  "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
  "status": "success",
  "method": "email",
  "reason": "invalid_phone_number",
  "risk_factors": [
    "proxy_network",
    "fraud_database"
  ],
  "channels": [
    "rcs"
  ],
  "silent": {
    "request_url": "<string>"
  },
  "metadata": {
    "correlation_id": "<string>"
  },
  "request_id": "<string>"
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Contact support for more throughput.",
  "type": "rate_limited"
}