History

List phone verifications

List your phone verifications, most recent first, one entry per verification with its outcome, channels, attempts and cost. Every filter is optional and they combine with AND.

Use it to find every verification a phone number went through from your support tooling, then Get a phone verification for the full timeline of one of them. A cursor is bound to the filters that produced it: pass next_cursor back with the exact same query parameters.

GET

verification

phone

history

List phone verifications

curl --request GET \
  --url https://api.prelude.dev/v2/verification/phone/history \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prelude.dev/v2/verification/phone/history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/verification/phone/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/verification/phone/history"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/verification/phone/history")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "verifications": [
    {
      "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
      "phone_number": "+33612345678",
      "status": "converted",
      "channels": [
        {
          "channel": "sms",
          "converted": true
        }
      ],
      "delivered": true,
      "created_at": "2023-11-07T05:31:56Z",
      "phone_number_condition": "allow_listed",
      "device_platform": "android",
      "attempts": 123,
      "cost": {
        "amount": "0.042",
        "currency": "EUR"
      },
      "signals_hash_status": "valid",
      "converted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "next_cursor": "MIZw2XwtkcEcC5SKsMEfSx6a3XAgW-Ct6waU8NCqUkAvFxz41DJbjQIkqHWJS1JY6-it7ZsZHFYN3luFH8yTdCAB"
}

List your phone verifications, most recent first, with the outcome, channels, attempts and cost of each. Filter by phone number, status, channel, region, device platform, template, number of attempts or creation window, and page through the results with cursor. Use it to find every verification a phone number went through from your support tooling, then Get a phone verification for the full timeline of a single one.

Filters combine with AND, and a cursor is bound to the filters that produced it: pass next_cursor back with the exact same query parameters, or the cursor is rejected. Without from and to the whole history is searched; when given, they go together and may span at most 6 months.

channels is empty for a verification that used only a channel this API does not list, such as LINE. attempts is 0 when no message was sent and absent for sandboxed phone numbers. Every timestamp is RFC 3339 in UTC.

Authorizations

Authorization

string

header

required

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

Query Parameters

phone_number

string<phone_number>

Only verifications targeting this E.164 phone number. The leading + may be omitted.

Example:

"+33612345678"

status

enum<string>

Only verifications in this status. pending_check cannot be filtered on. The outcome of the verification.

converted - The end user submitted a valid code.
not_converted - The verification expired without a valid code.
pending_check - A code was delivered and Prelude is still waiting for a check.
sent - A code was sent and the verification window is still open.
challenged - The verification was restricted to non-SMS and non-voice channels.
suspected_fraud - The anti-fraud system blocked the verification.
in_blocklist - The phone number is on the configured block list.
invalid_line - The phone number is not a valid line type.
invalid_number - The phone number is not a valid number.
rate_limited - The verification was refused by a rate limit.
expired_signals - The SDK signals were collected too long before the request.
shadowed - The anti-fraud system flagged the verification without blocking it.

Available options:

converted,

not_converted,

pending_check,

sent,

challenged,

suspected_fraud,

in_blocklist,

invalid_line,

invalid_number,

rate_limited,

expired_signals,

shadowed

channels

enum<string>[]

Only verifications that could use one of these channels. Repeat the parameter for several values.

Available options:

sms,

rcs,

whatsapp,

viber,

zalo,

telegram,

voice,

silent

region

string

Only verifications of phone numbers from this region, as an ISO 3166-1 alpha-2 code.

Example:

"FR"

device_platform

enum<string>

Only verifications created from this device platform. Platform of the end-user device, when known.

Available options:

android,

ios,

ipados,

tvos,

web

template_id

string

Only verifications sent with this template, as returned in template_id by Get a phone verification. Built-in templates (prelude:*) cannot be filtered on.

Example:

"template_01jc0t6fwwfgfsq1md24mhyztj"

min_attempts

integer

Only verifications that sent at least this many messages.

Required range: x >= 0

max_attempts

integer

Only verifications that sent at most this many messages. 0 keeps the verifications that never sent one.

Required range: x >= 0

from

string<date-time>

Only verifications created at or after this RFC 3339 timestamp. Goes with to, at most 6 months apart. Without them the whole history is searched.

Example:

"2026-09-01T00:00:00Z"

string<date-time>

Only verifications created at or before this RFC 3339 timestamp. Goes with from.

Example:

"2026-09-08T00:00:00Z"

limit

integer

default:50

Maximum number of verifications to return per page.

Required range: 1 <= x <= 200

cursor

string

Pagination cursor from the previous response.

Response

verifications

object[]

required

The page of verifications, most recent first.

Show child attributes

next_cursor

string

Pagination cursor for the next page of results. Omitted if there are no more pages.

Example:

"MIZw2XwtkcEcC5SKsMEfSx6a3XAgW-Ct6waU8NCqUkAvFxz41DJbjQIkqHWJS1JY6-it7ZsZHFYN3luFH8yTdCAB"

List phone verifications

curl --request GET \
  --url https://api.prelude.dev/v2/verification/phone/history \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prelude.dev/v2/verification/phone/history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prelude.dev/v2/verification/phone/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prelude.dev/v2/verification/phone/history"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/verification/phone/history")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "verifications": [
    {
      "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
      "phone_number": "+33612345678",
      "status": "converted",
      "channels": [
        {
          "channel": "sms",
          "converted": true
        }
      ],
      "delivered": true,
      "created_at": "2023-11-07T05:31:56Z",
      "phone_number_condition": "allow_listed",
      "device_platform": "android",
      "attempts": 123,
      "cost": {
        "amount": "0.042",
        "currency": "EUR"
      },
      "signals_hash_status": "valid",
      "converted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "next_cursor": "MIZw2XwtkcEcC5SKsMEfSx6a3XAgW-Ct6waU8NCqUkAvFxz41DJbjQIkqHWJS1JY6-it7ZsZHFYN3luFH8yTdCAB"
}

Documentation

API Reference

List phone verifications

Authorizations

Query Parameters

Response