History

Get a phone verification

Retrieve everything Prelude recorded for one phone verification: its outcome and the device, network and anti-fraud context it was created in, the chronological timeline of every message attempt and code check, and the anti-fraud signals you forwarded.

The identifier is the id returned by Create or retry a verification or the verification_id of the verification webhooks. Both lifecycle and signals are optional: a verification can resolve with its top-level fields alone.

GET

verification

phone

history

{id}

Get a phone verification

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

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

fetch('https://api.prelude.dev/v2/verification/phone/history/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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

{
  "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
  "phone_number": "+33612345678",
  "status": "converted",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "device_platform": "android",
  "device_model": "iPhone15,2",
  "app_version": "<string>",
  "ip_address": "<string>",
  "phone_number_region": "FR",
  "ip_address_region": "FR",
  "ip_distance_meters": 123,
  "carrier": {
    "mccmnc": "208-01",
    "name": "Orange"
  },
  "block_reasons": [
    "behavioral_pattern"
  ],
  "phone_number_condition": "allow_listed",
  "phone_number_current_condition": "allow_listed",
  "signals_hash_status": "valid",
  "correlation_id": "<string>",
  "template_id": "<string>",
  "lifecycle": {
    "events": [
      {
        "type": "create",
        "create": {
          "created_at": "2023-11-07T05:31:56Z",
          "cost": {
            "amount": "0.042",
            "currency": "EUR"
          }
        },
        "attempt": {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "trigger": "initial",
          "channel": "sms",
          "preferred_channel": "sms",
          "content": "<string>",
          "status": "succeeded",
          "delivery_status": "unknown",
          "delivery_events": [
            {
              "status": "unknown",
              "received_at": "2023-11-07T05:31:56Z"
            }
          ],
          "carrier": {
            "mccmnc": "208-01",
            "name": "Orange"
          },
          "cost": {
            "amount": "0.042",
            "currency": "EUR"
          }
        },
        "check": {
          "created_at": "2023-11-07T05:31:56Z",
          "is_valid": true,
          "status_detail": "expired_attempt",
          "channel": "sms",
          "value": "<string>",
          "psd2_info": {
            "expected_transaction": {
              "amount": {
                "amount": "0.042",
                "currency": "EUR"
              },
              "recipient": "<string>"
            },
            "received_transaction": {
              "amount": {
                "amount": "0.042",
                "currency": "EUR"
              },
              "recipient": "<string>"
            }
          }
        },
        "signals": {
          "received_at": "2023-11-07T05:31:56Z",
          "expired_at": "2023-11-07T05:31:56Z",
          "status": "valid"
        }
      }
    ],
    "total_cost": {
      "amount": "0.042",
      "currency": "EUR"
    },
    "undeliverable_route_count": 123
  },
  "signals": {
    "is_trusted_user": true,
    "device_id": "<string>",
    "os_version": "<string>",
    "user_agent": "<string>",
    "ja4_fingerprint": "<string>"
  }
}

{
  "code": "invalid_verification_id",
  "message": "The provided verification identifier is invalid.",
  "type": "bad_request"
}

{
  "code": "verification_not_found",
  "message": "No verification was found for the provided identifier.",
  "type": "not_found"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Please retry later.",
  "type": "rate_limited"
}

Retrieve everything Prelude recorded for a single phone verification: the outcome, the device, network and anti-fraud context it was created in, the timeline of every message attempt and code check, and the anti-fraud signals you forwarded. Use it to investigate a verification that behaved unexpectedly (a code that never arrived, a check that was refused, a request the anti-fraud system blocked) without opening the dashboard.

lifecycle and signals are both optional: a verification can resolve with its top-level fields alone.

While a verification can still be completed, Prelude withholds its code: the code is masked inside an attempt’s content, and a check’s value is absent entirely. Both show the real code once the verification can no longer be completed, so polling this endpoint is never a way to read a code that is still in play.

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

The verification identifier.

Example:

"vrf_01jc0t6fwwfgfsq1md24mhyztj"

Response

A verification and everything Prelude recorded about it.

string

required

The verification identifier.

Example:

"vrf_01jc0t6fwwfgfsq1md24mhyztj"

phone_number

string<phone_number>

required

The E.164 phone number the verification targeted.

Example:

"+33612345678"

status

enum<string>

required

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

created_at

string<date-time>

required

expires_at

string<date-time>

required

device_platform

enum<string>

Platform of the end-user device, when known.

Available options:

android,

ios,

ipados,

tvos,

web

device_model

string

Model of the end-user device, when known.

Example:

"iPhone15,2"

app_version

string

Version of your application, when known.

ip_address

string

IP address the verification was created from.

phone_number_region

string

ISO 3166-1 alpha-2 region of the phone number.

Example:

"FR"

ip_address_region

string

ISO 3166-1 alpha-2 region of the caller's IP address.

Example:

"FR"

ip_distance_meters

integer

Distance between the phone number region and the IP location.

carrier

object

The end user's mobile network.

Show child attributes

block_reasons

enum<string>[]

Why the anti-fraud system blocked the verification. Empty unless it did.

behavioral_pattern - The phone number past behavior during verification flows exhibits suspicious patterns.
device_attribute - The end-user device reported attributes associated with fraud or emulation.
fraud_database - The phone number appears in a fraud database.
location_discrepancy - The phone number region and the observed location disagree.
missing_signals - The verification expected Prelude SDK signals and none arrived.
network_fingerprint - The network fingerprint matches known fraudulent traffic.
poor_conversion_history - The phone number rarely completes the verifications it starts.
prefix_concentration - The phone number is part of a range known to be associated with suspicious activity patterns.
repeated_number - The phone number was used far more often than normal traffic would explain.
suspected_request_tampering - The SDK signals were altered or expired between collection and use.
suspicious_ip_address - The originating IP address is associated with suspicious activity.
temporary_phone_number - The phone number is known to be a temporary or disposable number.

Available options:

behavioral_pattern,

device_attribute,

fraud_database,

location_discrepancy,

missing_signals,

network_fingerprint,

poor_conversion_history,

prefix_concentration,

repeated_number,

suspected_request_tampering,

suspicious_ip_address,

temporary_phone_number

phone_number_condition

enum<string>

Whether the phone number was allow-listed, block-listed, or sandboxed at verification time.

Available options:

allow_listed,

block_listed,

sandboxed

phone_number_current_condition

enum<string>

Whether the phone number is currently allow-listed, block-listed, or sandboxed.

Available options:

allow_listed,

block_listed,

sandboxed

signals_hash_status

enum<string>

Whether the SDK signals integrity check passed.

Available options:

valid,

invalid

correlation_id

string

The correlation identifier you supplied when creating the verification.

template_id

string

The template used for this verification.

lifecycle

object

Chronological timeline of the verification: creation, message attempts with delivery events, code checks and signals reception. Omitted when Prelude holds no timeline for the verification.

Show child attributes

signals

object

The anti-fraud signals you forwarded when creating the verification.

Show child attributes

Get a phone verification

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

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

fetch('https://api.prelude.dev/v2/verification/phone/history/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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

{
  "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
  "phone_number": "+33612345678",
  "status": "converted",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "device_platform": "android",
  "device_model": "iPhone15,2",
  "app_version": "<string>",
  "ip_address": "<string>",
  "phone_number_region": "FR",
  "ip_address_region": "FR",
  "ip_distance_meters": 123,
  "carrier": {
    "mccmnc": "208-01",
    "name": "Orange"
  },
  "block_reasons": [
    "behavioral_pattern"
  ],
  "phone_number_condition": "allow_listed",
  "phone_number_current_condition": "allow_listed",
  "signals_hash_status": "valid",
  "correlation_id": "<string>",
  "template_id": "<string>",
  "lifecycle": {
    "events": [
      {
        "type": "create",
        "create": {
          "created_at": "2023-11-07T05:31:56Z",
          "cost": {
            "amount": "0.042",
            "currency": "EUR"
          }
        },
        "attempt": {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "trigger": "initial",
          "channel": "sms",
          "preferred_channel": "sms",
          "content": "<string>",
          "status": "succeeded",
          "delivery_status": "unknown",
          "delivery_events": [
            {
              "status": "unknown",
              "received_at": "2023-11-07T05:31:56Z"
            }
          ],
          "carrier": {
            "mccmnc": "208-01",
            "name": "Orange"
          },
          "cost": {
            "amount": "0.042",
            "currency": "EUR"
          }
        },
        "check": {
          "created_at": "2023-11-07T05:31:56Z",
          "is_valid": true,
          "status_detail": "expired_attempt",
          "channel": "sms",
          "value": "<string>",
          "psd2_info": {
            "expected_transaction": {
              "amount": {
                "amount": "0.042",
                "currency": "EUR"
              },
              "recipient": "<string>"
            },
            "received_transaction": {
              "amount": {
                "amount": "0.042",
                "currency": "EUR"
              },
              "recipient": "<string>"
            }
          }
        },
        "signals": {
          "received_at": "2023-11-07T05:31:56Z",
          "expired_at": "2023-11-07T05:31:56Z",
          "status": "valid"
        }
      }
    ],
    "total_cost": {
      "amount": "0.042",
      "currency": "EUR"
    },
    "undeliverable_route_count": 123
  },
  "signals": {
    "is_trusted_user": true,
    "device_id": "<string>",
    "os_version": "<string>",
    "user_agent": "<string>",
    "ja4_fingerprint": "<string>"
  }
}

{
  "code": "invalid_verification_id",
  "message": "The provided verification identifier is invalid.",
  "type": "bad_request"
}

{
  "code": "verification_not_found",
  "message": "No verification was found for the provided identifier.",
  "type": "not_found"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Please retry later.",
  "type": "rate_limited"
}

Documentation

API Reference

Get a phone verification

Authorizations

Path Parameters

Response