> ## 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.
# KYC Match
> Verify identity attributes (name, address, date of birth, email) against the subscriber record held by the end-user's mobile operator.
KYC Match is currently available for **France** (Orange, SFR, Bouygues) and
must be enabled for your account. [Contact us](https://prelude.so/contact) to
get access. Numbers on other operators return `unsupported_operator`.
## OpenAPI
````yaml post /v2/intel/kyc/match/{phone}
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/intel/kyc/match/{phone}:
post:
tags:
- Lookup
summary: KYC Match
description: >
Verify identity attributes against the subscriber record held by the
end-user's mobile operator. Send a phone number along with the
attributes to check; Prelude resolves the operator internally and
returns a per-attribute match. Currently available for France only
(Orange, SFR, Bouygues) and must be enabled for your account.
operationId: kycMatch
parameters:
- name: phone
in: path
required: true
schema:
type: string
format: phone_number
description: >-
An E.164 formatted phone number whose subscriber identity to match
against.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KYCMatchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/KYCMatchResponse'
example:
request_id: 01HVE0000000000000000000000
phone_number: '+33612345678'
country_code: FR
operator: orange_fr
given_name_match: 'true'
family_name_match: 'false'
family_name_match_score: 82
address_match: 'false'
address_match_score: 64
postal_code_match: 'true'
locality_match: 'true'
region_match: not_available
country_match: 'true'
birthdate_match: 'true'
email_match: not_available
'400':
description: >-
The request is invalid (e.g. malformed phone number or no attribute
provided).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: >-
The phone number resolved to an operator that does not support KYC
Match (`unsupported_operator`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: >-
The upstream operator or aggregator was unavailable
(`provider_unavailable`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
KYCMatchRequest:
type: object
description: >
The identity attributes to verify. Only the fields you want checked need
to be sent; at least one attribute is required. Each operator can answer
a subset of these attributes - any attribute the operator does not
support resolves to `not_available` rather than `false`.
properties:
given_name:
type: string
description: The end-user's given (first) name.
examples:
- Jean
family_name:
type: string
description: The end-user's family (last) name.
examples:
- Dupont
address:
type: string
description: The street address.
examples:
- 12 rue de la Paix
postal_code:
type: string
description: The postal code. Compared exactly.
examples:
- '75002'
locality:
type: string
description: The locality (city).
examples:
- Paris
region:
type: string
description: The region, state, or province.
examples:
- Île-de-France
country:
type: string
description: The ISO 3166-1 alpha-2 country code. Compared exactly.
examples:
- FR
birthdate:
type: string
format: date
description: >-
The date of birth in ISO 8601 (`YYYY-MM-DD`) format. Compared
exactly.
examples:
- '1990-01-15'
email:
type: string
format: email
description: The email address.
examples:
- jean.dupont@example.com
KYCMatchResponse:
type: object
description: >
The per-attribute match result. Each `_match` field is one of
`true`, `false`, or `not_available` (the operator could not answer for
that attribute). Fuzzy attributes additionally return a
`_match_score` (0-99 similarity) when they do not match
exactly; the score is omitted on a match or when `not_available`.
properties:
request_id:
type: string
description: >-
A string that identifies this specific request. Report it back to us
to help us diagnose your issues.
examples:
- 01HVE0000000000000000000000
phone_number:
type: string
description: The phone number that was matched, in E.164 format.
examples:
- '+33612345678'
country_code:
type: string
description: The country code of the phone number.
examples:
- FR
operator:
type: string
description: The mobile operator that answered the match.
examples:
- orange_fr
given_name_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: Whether the given name matched the operator's record.
examples:
- 'true'
given_name_match_score:
type: integer
minimum: 0
maximum: 99
description: >-
Similarity score (0-99) for the given name. Returned only on a
non-match.
family_name_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: Whether the family name matched the operator's record.
examples:
- 'false'
family_name_match_score:
type: integer
minimum: 0
maximum: 99
description: >-
Similarity score (0-99) for the family name. Returned only on a
non-match.
examples:
- 82
address_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: Whether the street address matched the operator's record.
examples:
- 'false'
address_match_score:
type: integer
minimum: 0
maximum: 99
description: >-
Similarity score (0-99) for the address. Returned only on a
non-match.
examples:
- 64
postal_code_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: >-
Whether the postal code matched the operator's record. Compared
exactly; never scored.
examples:
- 'true'
locality_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: Whether the locality matched the operator's record.
examples:
- 'true'
locality_match_score:
type: integer
minimum: 0
maximum: 99
description: >-
Similarity score (0-99) for the locality. Returned only on a
non-match.
region_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: Whether the region matched the operator's record.
examples:
- not_available
region_match_score:
type: integer
minimum: 0
maximum: 99
description: >-
Similarity score (0-99) for the region. Returned only on a
non-match.
country_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: >-
Whether the country matched the operator's record. Compared exactly;
never scored.
examples:
- 'true'
birthdate_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: >-
Whether the date of birth matched the operator's record. Compared
exactly; never scored.
examples:
- 'true'
email_match:
type: string
enum:
- 'true'
- 'false'
- not_available
description: Whether the email address matched the operator's record.
examples:
- not_available
email_match_score:
type: integer
minimum: 0
maximum: 99
description: Similarity score (0-99) for the email. Returned only on a non-match.
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
securitySchemes:
apiToken:
type: http
scheme: bearer
````