---
title: "Send verification payee request"
method: POST
path: "/payee_verification_requests"
tags: ["payee-verification-requests"]
---

# Send verification payee request

`POST /payee_verification_requests`

Send a request to verify your payee's information.

## Headers

- `Idempotency-Key` string

## Request body

- VopRequestCreationDetails — Details required to create a payee verification request.
  - `scheme` 'vop', required — The scheme on which the request will be sent. Only `vop` is supported today.
  - `payee_identification_type` 'name' | 'inac' | 'legal_entity_identifier' | 'business_identification_code' | 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'business_domain_identification' | 'other_identification' | 'proprietary_code', required — The type of identification used in the request. See Supported identification type for more information.
  - `payee_identification` string, required — The identification of the payee. For example, if `payee_identification_type = name`, then you should fill the name of the payee here.
  - `payee_account_number` string, required — The account number of the payee. When `scheme = vop`, must be an IBAN.
  - `payee_additional_information` string — Additional information about the payee.
  - `requesting_agent_bank_code` string — The BIC11 you want to use to send your request. Must be one of the BIC11 configured in Numeral for your company.
  - `initiated_at` string, date-time — The UTC timestamp at which you started the verification request cycle. It is forwarded unchanged to the counterparty as the request timestamp. Must not be in the future and must be less than 5 seconds old.
  - `metadata` CommonMetadata — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).

## Response `200`

Successfully created payee verification request

- VopRequestDetails — Details of a payee verification request.
  - `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)