> ## 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.
# 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](/verify/v2/api-reference/history/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.
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](/verify/v2/api-reference/history/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.
## OpenAPI
````yaml get /v2/verification/phone/history
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:
get:
tags:
- Verify
summary: List phone verifications
description: >
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](/verify/v2/api-reference/history/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.
operationId: listPhoneVerifications
parameters:
- name: phone_number
in: query
required: false
schema:
type: string
format: phone_number
examples:
- '+33612345678'
description: >-
Only verifications targeting this E.164 phone number. The leading
`+` may be omitted.
- name: status
in: query
required: false
schema:
$ref: '#/components/schemas/PhoneVerificationStatus'
description: >-
Only verifications in this status. `pending_check` cannot be
filtered on.
- name: channels
in: query
required: false
schema:
type: array
items:
$ref: '#/components/schemas/PhoneVerificationChannel'
description: >-
Only verifications that could use one of these channels. Repeat the
parameter for several values.
- name: region
in: query
required: false
schema:
type: string
examples:
- FR
description: >-
Only verifications of phone numbers from this region, as an ISO
3166-1 alpha-2 code.
- name: device_platform
in: query
required: false
schema:
$ref: '#/components/schemas/PhoneVerificationDevicePlatform'
description: Only verifications created from this device platform.
- name: template_id
in: query
required: false
schema:
type: string
examples:
- template_01jc0t6fwwfgfsq1md24mhyztj
description: >-
Only verifications sent with this template, as returned in
`template_id` by [Get a phone
verification](/verify/v2/api-reference/history/get-a-phone-verification).
Built-in templates (`prelude:*`) cannot be filtered on.
- name: min_attempts
in: query
required: false
schema:
type: integer
minimum: 0
description: Only verifications that sent at least this many messages.
- name: max_attempts
in: query
required: false
schema:
type: integer
minimum: 0
description: >-
Only verifications that sent at most this many messages. `0` keeps
the verifications that never sent one.
- name: from
in: query
required: false
schema:
type: string
format: date-time
examples:
- '2026-09-01T00:00:00Z'
description: >-
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.
- name: to
in: query
required: false
schema:
type: string
format: date-time
examples:
- '2026-09-08T00:00:00Z'
description: >-
Only verifications created at or before this RFC 3339 timestamp.
Goes with `from`.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 50
description: Maximum number of verifications to return per page.
- name: cursor
in: query
required: false
schema:
type: string
description: Pagination cursor from the previous response.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListPhoneVerificationsResponse'
'400':
description: KO
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_phone_number:
summary: Invalid phone number
value:
code: invalid_phone_number
message: >-
The provided phone number is invalid. Provide a valid
E.164 phone number.
type: bad_request
param: phone_number
invalid_status:
summary: Unknown status
value:
code: invalid_status
message: >-
Unknown status `pending_check`. Accepted statuses:
challenged, converted, expired_signals, in_blocklist,
invalid_line, invalid_number, not_converted, rate_limited,
sent, shadowed, suspected_fraud.
type: bad_request
param: status
invalid_channel:
summary: Unknown channel
value:
code: invalid_channel
message: >-
Unknown channel `line`. Accepted channels: rcs, silent,
sms, telegram, viber, voice, whatsapp, zalo.
type: bad_request
param: channels
invalid_region:
summary: Unknown region
value:
code: invalid_region
message: >-
The provided region is invalid. Provide an ISO 3166-1
alpha-2 country code, e.g. FR.
type: bad_request
param: region
invalid_device_platform:
summary: Unknown device platform
value:
code: invalid_device_platform
message: >-
The device platform must be one of 'android', 'ios',
'ipados', 'tvos', or 'web'.
type: bad_request
param: device_platform
invalid_template_id:
summary: Built-in or malformed template
value:
code: invalid_template_id
message: >-
The provided template ID is invalid. You can get your
template identifier from the Dashboard.
type: bad_request
param: template_id
invalid_attempts_range:
summary: Minimum above maximum
value:
code: invalid_attempts_range
message: '`min_attempts` must not exceed `max_attempts`.'
type: bad_request
param: min_attempts
invalid_date_format:
summary: Timestamp not in RFC 3339
value:
code: invalid_date_format
message: The date passed to `from` is not a valid RFC3339 date.
type: bad_request
param: from
invalid_time_range:
summary: Half-open window
value:
code: invalid_time_range
message: '`from` and `to` must be provided together.'
type: bad_request
invalid_pagination_limit:
summary: Limit out of range
value:
code: invalid_pagination_limit
message: The `limit` parameter must be between 1 and 200.
type: bad_request
param: limit
invalid_pagination_cursor:
summary: Cursor replayed with other filters
value:
code: invalid_pagination_cursor
message: The provided pagination cursor is invalid.
type: bad_request
param: cursor
'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:
PhoneVerificationStatus:
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.
PhoneVerificationChannel:
type: string
enum:
- sms
- rcs
- whatsapp
- viber
- zalo
- telegram
- voice
- silent
PhoneVerificationDevicePlatform:
type: string
enum:
- android
- ios
- ipados
- tvos
- web
description: Platform of the end-user device, when known.
ListPhoneVerificationsResponse:
type: object
properties:
verifications:
type: array
description: The page of verifications, most recent first.
items:
$ref: '#/components/schemas/PhoneVerificationSummary'
next_cursor:
type: string
description: >-
Pagination cursor for the next page of results. Omitted if there are
no more pages.
examples:
- >-
MIZw2XwtkcEcC5SKsMEfSx6a3XAgW-Ct6waU8NCqUkAvFxz41DJbjQIkqHWJS1JY6-it7ZsZHFYN3luFH8yTdCAB
required:
- verifications
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.
param:
type: string
examples:
- phone_number
description: The parameter the error refers to, when it applies to a single one.
required:
- code
- message
- type
PhoneVerificationSummary:
type: object
description: >-
One entry of the verification history. [Get a phone
verification](/verify/v2/api-reference/history/get-a-phone-verification)
returns the full record.
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.
phone_number_condition:
$ref: '#/components/schemas/PhoneVerificationPhoneNumberCondition'
status:
$ref: '#/components/schemas/PhoneVerificationStatus'
device_platform:
$ref: '#/components/schemas/PhoneVerificationDevicePlatform'
channels:
type: array
description: >-
The channels the verification could use, and which one the end user
converted through. Empty when the verification used only channels
this API does not list.
items:
type: object
properties:
channel:
$ref: '#/components/schemas/PhoneVerificationChannel'
converted:
type: boolean
description: >-
Whether the end user submitted a valid code received through
this channel.
required:
- channel
- converted
attempts:
type: integer
description: >-
Number of messages sent for the verification, `0` when none was.
Absent for sandboxed phone numbers.
delivered:
type: boolean
description: Whether at least one message was reported delivered.
cost:
$ref: '#/components/schemas/PhoneVerificationMoney'
description: Total cost of the verification. Absent when nothing was billed.
signals_hash_status:
$ref: '#/components/schemas/PhoneVerificationSignalsHashStatus'
created_at:
type: string
format: date-time
converted_at:
type: string
format: date-time
description: >-
When the end user submitted a valid code. Absent unless the
verification converted.
required:
- id
- phone_number
- status
- channels
- delivered
- created_at
PhoneVerificationPhoneNumberCondition:
type: string
enum:
- allow_listed
- block_listed
- sandboxed
description: >-
Whether the phone number was allow-listed, block-listed, or sandboxed at
verification time.
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
PhoneVerificationSignalsHashStatus:
type: string
enum:
- valid
- invalid
description: Whether the SDK signals integrity check passed.
securitySchemes:
apiToken:
type: http
scheme: bearer
````