> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prelude.so/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/verify/v2/api-reference/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.
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.
## OpenAPI
````yaml get /v2/verification/phone/history/{id}
openapi: 3.1.0
info:
title: Prelude API
version: 2.0.0
description: The Prelude API allows you to send messages to your users.
contact:
email: support@prelude.so
servers:
- url: https://api.prelude.dev
description: Production server
security:
- apiToken: []
tags:
- name: Notify
description: Send transactional and marketing messages with compliance enforcement.
- name: Transactional
description: Send transactional messages (deprecated - use Notify API instead).
- name: Verify
description: Verify phone numbers.
- name: Watch
description: Evaluate email addresses and phone numbers for trustworthiness.
- name: Lookup
description: >-
Retrieve detailed information about a phone number including carrier data,
line type, and portability status.
paths:
/v2/verification/phone/history/{id}:
get:
tags:
- Verify
summary: Get a phone verification
description: >
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](/verify/v2/api-reference/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.
operationId: getPhoneVerification
parameters:
- name: id
in: path
required: true
schema:
type: string
examples:
- vrf_01jc0t6fwwfgfsq1md24mhyztj
description: The verification identifier.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneVerification'
'400':
description: KO
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_verification_id:
summary: Malformed identifier
value:
code: invalid_verification_id
message: The provided verification identifier is invalid.
type: bad_request
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
verification_not_found:
summary: Unknown verification
value:
code: verification_not_found
message: No verification was found for the provided identifier.
type: not_found
'429':
description: Rate limited
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying the request.
X-Should-Retry:
schema:
type: boolean
description: Whether the client should retry the request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
summary: Too many reads
value:
code: rate_limited
message: Rate limit exceeded. Please retry later.
type: rate_limited
components:
schemas:
PhoneVerification:
type: object
description: A verification and everything Prelude recorded about it.
properties:
id:
type: string
examples:
- vrf_01jc0t6fwwfgfsq1md24mhyztj
description: The verification identifier.
phone_number:
type: string
format: phone_number
examples:
- '+33612345678'
description: The E.164 phone number the verification targeted.
status:
type: string
enum:
- converted
- not_converted
- pending_check
- sent
- challenged
- suspected_fraud
- in_blocklist
- invalid_line
- invalid_number
- rate_limited
- expired_signals
- shadowed
description: |
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.
device_platform:
type: string
enum:
- android
- ios
- ipados
- tvos
- web
description: Platform of the end-user device, when known.
device_model:
type: string
examples:
- iPhone15,2
description: Model of the end-user device, when known.
app_version:
type: string
description: Version of your application, when known.
ip_address:
type: string
description: IP address the verification was created from.
phone_number_region:
type: string
examples:
- FR
description: ISO 3166-1 alpha-2 region of the phone number.
ip_address_region:
type: string
examples:
- FR
description: ISO 3166-1 alpha-2 region of the caller's IP address.
ip_distance_meters:
type: integer
description: Distance between the phone number region and the IP location.
carrier:
$ref: '#/components/schemas/PhoneVerificationCarrier'
block_reasons:
type: array
items:
type: string
enum:
- 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
description: >
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.
phone_number_condition:
type: string
enum:
- allow_listed
- block_listed
- sandboxed
description: >-
Whether the phone number was allow-listed, block-listed, or
sandboxed at verification time.
phone_number_current_condition:
type: string
enum:
- allow_listed
- block_listed
- sandboxed
description: >-
Whether the phone number is currently allow-listed, block-listed, or
sandboxed.
signals_hash_status:
type: string
enum:
- valid
- invalid
description: Whether the SDK signals integrity check passed.
correlation_id:
type: string
description: >-
The correlation identifier you supplied when creating the
verification.
template_id:
type: string
description: The template used for this verification.
created_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
lifecycle:
$ref: '#/components/schemas/PhoneVerificationLifecycle'
signals:
$ref: '#/components/schemas/PhoneVerificationSignals'
required:
- id
- phone_number
- status
- created_at
- expires_at
Error:
type: object
properties:
code:
type: string
description: The error code.
examples:
- invalid_phone_number
message:
type: string
examples:
- >-
The provided phone number is invalid. Provide a valid E.164 phone
number.
description: A human-readable message describing the error.
type:
type: string
examples:
- bad_request
description: The error type.
request_id:
type: string
examples:
- 3d19215e-2991-4a05-a41a-527314e6ff6a
description: >-
A string that identifies this specific request. Report it back to us
to help us diagnose your issues.
required:
- code
- message
- type
PhoneVerificationCarrier:
type: object
description: The end user's mobile network.
properties:
mccmnc:
type: string
examples:
- 208-01
name:
type: string
examples:
- Orange
required:
- mccmnc
PhoneVerificationLifecycle:
type: object
description: >-
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.
properties:
events:
type: array
items:
$ref: '#/components/schemas/PhoneVerificationEvent'
total_cost:
$ref: '#/components/schemas/PhoneVerificationMoney'
undeliverable_route_count:
type: integer
description: >-
How many times the message was reported undeliverable by independent
routes. Above zero usually means the phone number is incorrect or
the device unreachable.
required:
- events
PhoneVerificationSignals:
type: object
description: The anti-fraud signals you forwarded when creating the verification.
properties:
device_id:
type: string
description: End-user device identifier you forwarded.
os_version:
type: string
user_agent:
type: string
is_trusted_user:
type: boolean
description: >-
Whether you flagged this end user as trusted when creating the
verification. Declared by you, not computed by Prelude.
ja4_fingerprint:
type: string
description: TLS fingerprint you forwarded.
required:
- is_trusted_user
PhoneVerificationEvent:
type: object
description: One timeline entry. `type` names the single payload field that is set.
properties:
type:
type: string
enum:
- create
- attempt
- check
- signals
create:
type: object
properties:
created_at:
type: string
format: date-time
cost:
$ref: '#/components/schemas/PhoneVerificationMoney'
required:
- created_at
attempt:
$ref: '#/components/schemas/PhoneVerificationAttempt'
check:
$ref: '#/components/schemas/PhoneVerificationCheck'
signals:
type: object
properties:
received_at:
type: string
format: date-time
expired_at:
type: string
format: date-time
status:
type: string
enum:
- valid
- invalid
required:
- received_at
required:
- type
PhoneVerificationMoney:
type: object
properties:
amount:
type: string
examples:
- '0.042'
description: >-
Exact decimal amount. It is never rounded to the currency's minor
units, so a sub-cent cost reads as `0.0004` rather than as `0.00`.
currency:
type: string
examples:
- EUR
description: ISO 4217 currency code.
required:
- amount
- currency
PhoneVerificationAttempt:
type: object
description: One message sent for this verification.
properties:
id:
type: string
created_at:
type: string
format: date-time
trigger:
type: string
enum:
- initial
- auto_retry
- user_retry
description: What caused the attempt.
channel:
type: string
enum:
- sms
- rcs
- whatsapp
- viber
- zalo
- telegram
- voice
- silent
preferred_channel:
type: string
enum:
- sms
- rcs
- whatsapp
- viber
- zalo
- telegram
- voice
- silent
description: Channel you asked for, when it differs from the one used.
content:
type: string
description: >-
Message body. While the verification can still be completed, the
code inside it is masked rather than removed.
status:
type: string
enum:
- succeeded
- failed
delivery_status:
type: string
enum:
- unknown
- in_transit
- delivered
- undeliverable
- read
delivery_events:
type: array
items:
type: object
properties:
status:
type: string
enum:
- unknown
- submitted
- in_transit
- delivered
- undeliverable
- expired
- read
- silent_started
- silent_verified
- silent_mismatch
description: >
The state this event reported. It is finer-grained than the
attempt's `delivery_status` and includes the states a silent
verification goes through.
received_at:
type: string
format: date-time
required:
- status
- received_at
carrier:
$ref: '#/components/schemas/PhoneVerificationCarrier'
cost:
$ref: '#/components/schemas/PhoneVerificationMoney'
required:
- id
- created_at
PhoneVerificationCheck:
type: object
description: One code submission for this verification.
properties:
created_at:
type: string
format: date-time
is_valid:
type: boolean
status_detail:
type: string
enum:
- expired_attempt
- expired_auth
- rate_limited
- transaction_missing
- transaction_mismatch
description: Why an invalid check failed, when known.
channel:
type: string
enum:
- sms
- rcs
- whatsapp
- viber
- zalo
- telegram
- voice
- silent
value:
type: string
description: >-
The submitted code. Absent while the verification can still be
completed, so that a check in flight cannot be read back through
this endpoint, and absent on silent verification checks, which carry
no code.
psd2_info:
type: object
description: Present on checks against a `prelude:psd2` code.
properties:
expected_transaction:
$ref: '#/components/schemas/PhoneVerificationPSD2Transaction'
description: The transaction submitted when the code was issued.
received_transaction:
$ref: '#/components/schemas/PhoneVerificationPSD2Transaction'
description: >-
The transaction submitted with this check. Differs from
`expected_transaction` when `status_detail` is
`transaction_mismatch`.
required:
- created_at
- is_valid
PhoneVerificationPSD2Transaction:
type: object
properties:
amount:
$ref: '#/components/schemas/PhoneVerificationMoney'
recipient:
type: string
description: Payee name displayed to the payer.
securitySchemes:
apiToken:
type: http
scheme: bearer
````