# Persons

Retrieve information on persons from the Kycaid blacklist databases using fuzzy search to check for compliance with laws and regulations. Each response may have several objects, with one object per a blacklist

Endpoint: POST /bdb/persons
Version: 1.0
Security: API-Key

## Security:

  - `API-Key` (unknown)
    apiKey in header API-Key

## Request fields (application/json):

  - `full_name` (string | null, required)
    The full name of a person, which includes a first and last name
    Example: Josh Coffey

  - `first_name` (string | null)
    The first name of a person
    Example: Josh

  - `last_name` (string | null)
    The last name of a person
    Example: Coffey

  - `middle_name` (string | null)
    The middle name of a person
    Example: David

  - `dob` (string | null)
    The date of birth of a person, formatted as “YYYY-MM-DD” according to ISO 8601
    Example: 1976-02-21

  - `residence_country` (string | null)
    A residence country of an object. A two-letter country code according to ISO 3166-2
    Example: GB

  - `gender` (string | null)
    The gender of a person. `M` indicates male; `F` indicates female
    Enum: "M", "F"

  - `name_match_threshold` (number)
    The minimum similarity score required to include a name in the search results. A higher value returns fewer, more exact matches, and a lower value returns more results with less similarity
    Example: 0.75

  - `name_match_weight` (number)
    Influence of a name match on the total match score
    Example: 0.7

  - `dob_match_enabled` (boolean)
    Enable or disable inclusion of a date of birth in the total match score
    Enum: true, false

  - `dob_match_weight` (number)
    Influence of a date of birth match on the total match score
    Example: 0.1

  - `residence_country_match_enabled` (boolean)
    Enable or disable inclusion of a residence country match in the total match score
    Enum: true, false

  - `residence_country_match_weight` (number)
    Influence of a residence country match on the total match score
    Example: 0.05

  - `gender_match_enabled` (boolean)
    Enable or disable inclusion of a gender match in the total match score
    Enum: true, false

  - `gender_match_weight` (number)
    Influence of a gender match on the total match score
    Example: 0.05

  - `bdb_types` (array)
    A type of blacklist databases to make a check
- `SANCTIONS`: Global and local sanctions
databases
- `PEP`: Databases of politically exposed persons (PEP)
- `WANTED`: Databases of persons being searched for by the police
- `EXPIRED`: Databases of stolen or lost documents
    Example: ["SANCTIONS"]

## Response 200:

  - `200` (unknown)
    **OK**
The request was successful, and our system returned an expected response.

## Response 200 fields (application/json):

  - `data` (object)

  - `data.parameters` (object)

  - `data.parameters.name_match_threshold` (number)
    The minimum similarity score required to include a name in the search results. A higher value returns fewer, more exact matches, and a lower value returns more results with less similarity
    Example: 0.75

  - `data.parameters.name_match_weight` (number)
    Influence of a name match on the total match score
    Example: 0.7

  - `data.parameters.dob_match_enabled` (boolean)
    Enable or disable inclusion of a date of birth in the total match score
    Enum: true, false

  - `data.parameters.dob_match_weight` (number)
    Influence of a date of birth match on the total match score
    Example: 0.1

  - `data.parameters.residence_country_match_enabled` (boolean)
    Enable or disable inclusion of a residence country match in the total match score
    Enum: true, false

  - `data.parameters.residence_country_match_weight` (number)
    Influence of a residence country match on the total match score
    Example: 0.05

  - `data.parameters.gender_match_enabled` (boolean)
    Enable or disable inclusion of a gender match in the total match score
    Enum: true, false

  - `data.parameters.gender_match_weight` (number)
    Influence of a gender match on the total match score
    Example: 0.05

  - `data.result` (array)

  - `data.result.full_name` (string | null)
    The full name of a person, which includes a first and last name
    Example: Josh Coffey

  - `data.result.origin_full_name` (string | null)
    A full name of an object, which consists of a first name and a last name, set in a native language
    Example: Джош Кофі

  - `data.result.first_name` (string | null)
    The first name of a person
    Example: Josh

  - `data.result.origin_first_name` (string | null)
    A first name of an object, set in a native language
    Example: Джош

  - `data.result.last_name` (string | null)
    The last name of a person
    Example: Coffey

  - `data.result.origin_last_name` (string | null)
    A last name of an entity, set in a native language
    Example: Кофі

  - `data.result.middle_name` (string | null)
    The middle name of a person
    Example: David

  - `data.result.origin_middle_name` (string | null)
    A middle name of an object, set in a native language
    Example: Conrad

  - `data.result.dob` (string | null)
    The date of birth of a person, formatted as “YYYY-MM-DD” according to ISO 8601
    Example: 1976-02-21

  - `data.result.residence_country` (string | null)
    A residence country of an object. A two-letter country code according to ISO 3166-2
    Example: GB

  - `data.result.gender` (string | null)
    The gender of a person. `M` indicates male; `F` indicates female
    Enum: "M", "F"

  - `data.result.description` (string | null)
    The detailed description of a status in blacklist databases
    Example: Reciprocal - 2010-04-30

  - `data.result.bdb_name` (string | null)
    A name of a blacklist database
    Example: Open Sanctions Default

  - `data.result.aliases` (array)

  - `data.result.addresses` (array)

  - `data.result.name_match_score` (number)
    Relevance of a name match in a fuzzy search
    Example: 0.8

  - `data.result.total_match_score` (number)
    The calculated relevance score for a search result
    Example: 0.86

## Response 400:

  - `400` (unknown)
    **Bad Request**
Our system could not process the request due to invalid syntax, missing parameters, or incorrect data format. Check the request structure and try again.

## Response 400 fields (application/json):

  - `type` (string)
    Example: bad_request

  - `errors` (array)

## Response 402:

  - `402` (unknown)
    **Payment Required**
Access to the requested resource is restricted until a payment is successfully processed. Ensure your account has a valid payment method or sufficient funds to complete this action.

## Response 402 fields (application/json):

  - `type` (string)
    Example: insufficient_funds

  - `errors` (array)

## Response 422:

  - `422` (unknown)
    **Unprocessable Content**
Our system understands the request but can’t process it due to invalid fields in the request body.

## Response 422 fields (application/json):

  - `type` (string)
    Example: validation

  - `errors` (array)

  - `errors.parameter` (string)
    Example: first_name

  - `errors.message` (string)
    Example: Value must be between 1 and 64 characters

## Response 429:

  - `429` (unknown)
    **Too Many Requests**
This response indicates that a user has sent too many requests in a given amount of time.

## Response 429 fields (application/json):

  - `type` (string)
    Example: flow

  - `errors` (array)

  - `errors.parameter` (string)
    Example: limit_exceeded

  - `errors.message` (string)
    Example: Rate limit exceeded

## Response 500:

  - `500` (unknown)
    **Internal Server Error**
This response indicates that our system encountered an unexpected condition that prevented it from fulfilling the request.

## Response 500 fields (application/json):

  - `type` (string)
    Example: internal_server

  - `errors` (array)

## Response 502:

  - `502` (unknown)
    **Bad Gateway**
This response indicates that our system is unable to reach or communicate properly with an upstream server it relies on, the URL provided is incorrect, or a required token is missing from the request.