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 /v2/verification/phone/history/{id}

Get a phone verification

cURL

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

200

{
  "id": "vrf_01jc0t6fwwfgfsq1md24mhyztj",
  "phone_number": "[phone]",
  "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": [
    "automation_signature"
  ],
  "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>"
  }
}

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

id · string · required

The verification identifier.

Example:

"vrf_01jc0t6fwwfgfsq1md24mhyztj"

Response

200

application/json

OK

A verification and everything Prelude recorded about it.

id · string · required

The verification identifier.

Example:

"vrf_01jc0t6fwwfgfsq1md24mhyztj"

phone_number · string<phone_number> · required

The E.164 phone number the verification targeted.

Example:

"[phone]"

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 to still attest to it.
• 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. These are the same labels the Verify and Watch APIs serve as risk_factors.

• 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

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