---
title: "List payee verification requests"
method: GET
path: "/payee_verification_requests"
tags: ["payee-verification-requests"]
---

# List payee verification requests

`GET /payee_verification_requests`

List and filter payee verification requests.

## Query parameters

- `limit` integer
- `starting_after` string
- `sort_order` 'asc' | 'desc'
- `start_date` string, date
- `end_date` string, date
- `status` 'created' | 'completed' | 'failed' | 'received'
- `direction` 'outgoing' | 'incoming'
- `scheme` 'vop'
- `payee_identification_type` string
- `payee_identification` string
- `payee_account_number` string
- `requesting_agent_bank_code` string
- `responding_agent_bank_code` string
- `matching_result` 'match' | 'close_match' | 'no_match' | 'impossible_match'
- `internal_account_id` string, uuid

## Response `200`

List of filtered payee verification requests

- object
  - `records` VopRequestDetails[], required
    - `id` string, required — The ID of the payee verification request.
    - `idempotency_key` string — An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.
    - `object` 'payee_verification_request', required — Label used to identify this kind of object.
    - `status` 'created' | 'received' | 'completed' | 'failed', required — The status of the payee verification request. See Payee verification request lifecycle for more details.
    - `status_details` string, required — More information about the payee verification request status.
    - `failure_code` 'business_error' | 'technical_error' | 'psp_technical_error', nullable — A code explaining why the request failed.
    - `direction` 'outgoing' | 'incoming', required — The direction of the request. Can be outgoing or incoming.
    - `scheme` 'vop', required — The scheme the request was sent on. Only `vop` is supported today.
    - `request` object, required — An object containing key information about the request.
      - `payee_identification_type` string — The type of identification used in the request.
      - `payee_identification` string — The identification of the payee.
      - `sent_identification` string, nullable — The identification actually sent on the scheme, after any cleaning or transformation applied to `payee_identification`. Only available for outgoing requests.
      - `payee_account_number` string — The account number of the payee.
      - `additional_information` string — Additional information about the payee.
      - `requesting_agent_bank_code` string — The agent which sent the request.
      - `responding_agent_bank_code` string — The agent at which the request is aimed, i.e. the agent of the payee.
    - `matching_result` 'match' | 'close_match' | 'no_match' | 'impossible_match', required — The result of the verification. Can be `match`, `close_match`, `no_match` or `impossible_match`. Note that `close_match` is only possible when `payee_identification_type = name`.
    - `payee_suggested_name` string, nullable, required — In case of `matching_result = close_match`, name suggested as correct by the responding agent.
    - `matching_details` object, nullable, required — Details of the request processing in case `direction = incoming`.
      - `cleaned_identification` string — Payee identification after data cleaning (removing double spaces, honorific titles, etc.)
      - `retrieved_identification` string, nullable — Payee identification retrieved in your account database (in Numeral or in your systems), using `payee_account_number` as a search key. For name matching: set to the best matching name when `matching_result` is `match` or `close_match`, null when `matching_result` is `no_match`. For other identification types (LEI, BIC, etc.): set to the retrieved value.
      - `retrieved_identifications` string[], nullable — All holder names retrieved from your account database that were evaluated during the matching process. Only populated for `payee_identification_type = name`. Null for other identification types.
      - `internal_account_id` string — If your account database is held in Numeral using internal accounts, the ID of the internal account matching `payee_account_number`.
      - `matching_score` integer — The score, from 0 to 100, of the matching algorithm configured for your entity when run with `cleaned_identification` and `retrieved_identification`.
      - `distance` 'levenshtein' | 'jarowinkler', nullable — The name of the matching algorithm used to compute the matching score.
      - `match_threshold` integer, nullable — The minimum score threshold configured for a result to be considered a `match`.
      - `close_match_threshold` integer, nullable — The minimum score threshold configured for a result to be considered a `close_match`.
    - `scheme_data` object, nullable, required — An object containing technical information about the request.
      - `scheme_request_id` string — The unique ID of the request on the scheme. Different from `id`.
      - `request_timestamp` string, date-time — The timestamp of the creation of the request.
      - `response_timestamp` string, date-time — The timestamp of the answer to the request.
    - `response_received_at` string, date-time, nullable — The UTC timestamp of the reception of the response to the request. Only available for outgoing requests.
    - `initiated_at` string, date-time, nullable — The UTC timestamp at which you started the verification request cycle, as provided on creation. Only available for outgoing requests where it was provided.
    - `metadata` CommonMetadata — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
    - `created_at` string, date-time, required — The UTC timestamp of the creation of the outgoing payee verification request.

## Other responses

- `400` — Validation error.
- `500` — Internal server error.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/versions/220f101cc2ef/schema)