Soft KYC

Requirements:

API key pair
Balance or limit set up for each database you call. Without it, the check returns 403.
The databases you can use are set up by iDenfy staff. There is no endpoint that lists them — contact iDenfy to find out which ones you can call.

In the development environment, US_15 and UK checks return predefined results for a set of dummy people instead of checking a real database. See Soft KYC Dummy Data. HU checks from the development or testing environment go to the Hungarian provider’s test endpoint. LT has no dummy mode.

How It Works

Send POST /api/v2/registry-center-checks/ with your API key pair. The database field chooses the country, and each database takes a different set of fields.
The check runs straight away. On success it returns 201 with the result and charges one check to that database’s balance.
Results come back in the response and in the dashboard. A standalone check sends no webhook.

Generate Request

POST https://ivs.idenfy.com/api/v2/registry-center-checks/
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

Supported Databases

database is not a free-form string. Four values are supported, and each takes a different request body and returns a different response:

`database`	Country	Required fields	Optional
`LT`	Lithuania	`checkedPersonalNumber`	`checkedDocumentType`, `clientId`
`HU`	Hungary	`checkedMrz`	`clientId`
`UK`	United Kingdom	`firstName`, `lastName`, `dateOfBirth`, `address`	`clientId`
`US_15`	United States	`firstName`, `lastName`, and `dob` or `idNum`	see United States

Rules for Every Database

Empty values ("", null, 0) count as “not sent”. An empty required field returns a required-field error — for example, "firstName": "" is rejected rather than checked.
clientId is optional, up to 100 characters. It’s your own identifier for the person, comes back in the response, and can be used as a filter on the list endpoint.

Lithuania (`LT`)

Field	Type	Required	Rules
`database`	String	Yes	`LT`
`checkedPersonalNumber`	String	Yes	Up to 30 characters, digits only. A non-numeric value returns `404`, not `400`.
`checkedDocumentType`	String	No	`I` = ID card, `P` = passport. Any other value is silently ignored and the check runs without a document type.
`clientId`	String	No	Up to 100 characters

Request example

{
  "database": "LT",
  "checkedPersonalNumber": "39001010000",
  "checkedDocumentType": "I",
  "clientId": "client-123"
}

Response example

{
  "id": "5e1b7c2a-3f4d-4a8e-9b6c-1d2e3f4a5b6c",
  "checkedPersonalNumber": "39001010000",
  "checkedDocumentType": "I",
  "personalNumber": "39001010000",
  "name": "JONAS",
  "surname": "JONAITIS",
  "documentNumber": "12345678",
  "documentExpiration": "2030-01-01",
  "facePhoto": null,
  "database": "LT",
  "clientId": "client-123"
}

There are no match statuses. The registry’s data comes back as-is for you to compare.
facePhoto is always null on a standalone check. The photo is kept only when the check runs inside an identity verification.

Hungary (`HU`)

Field	Type	Required	Rules
`database`	String	Yes	`HU`
`checkedMrz`	String	Yes	Up to 100 characters. Line breaks are removed before sending.
`clientId`	String	No	Up to 100 characters

Request example

{
  "database": "HU",
  "checkedMrz": "string",
  "clientId": "client-123"
}

Response example

{
  "id": "8a3f2d1c-6b5e-4f7a-9c8d-2e1f0a9b8c7d",
  "checkedMrz": "string",
  "firstName": "ANNA",
  "lastName": "KOVÁCS",
  "maidenName": "KOVÁCS",
  "mothersMaidenName": "NAGY ÉVA",
  "birthDate": "1985-04-12",
  "birthPlace": "BUDAPEST",
  "address": {},
  "residentialAddress": {},
  "nationality": "HU",
  "idCard": {},
  "passport": {},
  "additionalData": {},
  "database": "HU",
  "clientId": "client-123"
}

There are no match statuses. The registry’s data comes back as-is for you to compare.
address, residentialAddress, idCard, passport and additionalData are objects. nationality is a country code, and birthDate is a YYYY-MM-DD date.
Any field can be empty when the registry has no data.
lastName may come back with a “Dr.” prefix.
Some partners have their own Hungarian provider address set up.

United Kingdom (`UK`)

Field	Type	Required	Rules
`database`	String	Yes	`UK`
`firstName`, `lastName`	String	Yes	Up to 255 characters
`dateOfBirth`	String	Yes	`YYYY-MM-DD`. The person must be 5–150 years old.
`address.line1`	String	Yes	Up to 255 characters
`address.line2`	String	No	Joined onto line 1 before sending
`address.city`	String	Yes	Up to 100 characters
`address.postcode`	String	Yes	Up to 10 characters. Capital letters, digits and spaces only — lowercase is rejected.
`clientId`	String	No	Up to 100 characters

Request example

{
  "database": "UK",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-04-12",
  "address": {
    "line1": "10 Sample Street",
    "line2": "Flat 2",
    "city": "London",
    "postcode": "SW1A 1AA"
  },
  "clientId": "client-123"
}

Response example

{
  "id": "3b9e6f1a-7c2d-4e5f-8a1b-9c0d1e2f3a4b",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-04-12",
  "address": {
    "line1": "10 Sample Street",
    "line2": "Flat 2",
    "city": "London",
    "postcode": "SW1A 1AA",
    "country": "UK"
  },
  "firstNameStatus": "MATCH",
  "lastNameStatus": "MATCH",
  "dateOfBirthStatus": "MATCH",
  "addressStatus": "NO_MATCH",
  "addressStatusScore": 0,
  "database": "UK",
  "clientId": "client-123"
}

UK statuses are only MATCH or NO_MATCH. Anything short of a match is NO_MATCH.
address.country is always UK.

United States (`US_15`)

Field	Type	Required	Rules
`database`	String	Yes	`US_15`
`firstName`, `lastName`	String	Yes	Up to 100 characters
`dob`	String	`dob` or `idNum`	`YYYY-MM-DD`. The person must be 5–150 years old.
`idNum`	String	`dob` or `idNum`	Up to 9 characters. Exactly 4 digits = last 4 of the SSN, exactly 9 = full SSN. Any other length is silently left out of what goes to the provider. Digits aren’t checked.
`yob`	Integer	No	1901–2050. Ignored when `dob` is sent.
`middleName`	String	No	Up to 100 characters
`address1`, `address2`	String	No	Up to 255 characters, not blank
`city`	String	No	2–100 characters (spaces at the ends don’t count)
`state`	String	No	Up to 2 characters, e.g. `CA`
`zip`	String	No	Digits only, up to 10 characters
`phone`	String	No	Must be a valid phone number, at least 10 characters. It comes back in international format.
`email`	String	No	Must be a valid email address
`clientId`	String	No	Up to 100 characters

At least one of dob or idNum is required, and this is always enforced. Without either, the check returns 400 with an error on both dob and idNum.

Any value that breaks the rules above returns 400, and the error names the field. Request example

{
  "firstName": "John",
  "lastName": "Smith",
  "state": "CA",
  "database": "US_15",
  "dob": "1990-09-09",
  "city": "San Jose",
  "address1": "Benson str",
  "address2": "3914",
  "zip": "95128",
  "phone": "+1 (416) 555-5678",
  "idNum": "897884526",
  "email": "example.email@domain.com"
}

Response example

{
  "id": "94f63296-7f3a-46d2-8558-ebd89224cb19",
  "firstName": "John",
  "lastName": "Smith",
  "middleName": null,
  "dob": "1990-09-09",
  "yob": null,
  "address1": "Benson str",
  "address2": "3914",
  "city": "San Jose",
  "state": "CA",
  "zip": "95128",
  "idNum": "897884526",
  "phone": "+14165555678",
  "email": "example.email@domain.com",
  "firstNameStatus": "NO_MATCH",
  "lastNameStatus": "NO_MATCH",
  "middleNameStatus": null,
  "dobStatus": "NO_MATCH",
  "yobStatus": null,
  "address1Status": "NO_MATCH",
  "address2Status": "NO_MATCH",
  "cityStatus": "NO_MATCH",
  "stateStatus": "NO_MATCH",
  "zipStatus": "NO_MATCH",
  "idNumStatus": "NO_MATCH",
  "phoneStatus": "NO_MATCH",
  "emailStatus": "NO_MATCH",
  "database": "US_15",
  "clientId": null
}

The response returns every input field, each with a matching status field (firstNameStatus … emailStatus). There is no score and no overall result.

Possible Status Values

UK and US_15 responses include a status field for each checked field. LT and HU return registry data without statuses.

Status	Description
`MATCH`	The provided data matches the database record.
`PARTIAL_MATCH`	The provided data partially matches the database record. `US_15` only.
`NO_MATCH`	The provided data does not match the database record, or the match is very weak.
`INVALID`	The format of the provided input data was invalid. `US_15` only.
`NO_INPUT`	The corresponding input field was provided but contained blank or empty data. `US_15` only.
`NO_DATA`	No corresponding data was found in the database source for comparison. `US_15` only.
empty	The corresponding input field wasn’t sent.

The thresholds that separate MATCH from PARTIAL_MATCH are defined by the upstream data provider and are not exposed on the response. US_15 returns no score or confidence value — only the statuses above. (UK is the exception: its response includes an addressStatusScore.)

List Soft ID Verification Checks

GET https://ivs.idenfy.com/api/v2/registry-center-checks/
Authorization: Basic {API_KEY}:{API_SECRET}

The response is one plain, unpaginated list of every matching check. Each item has the same fields as the create response for its database, including clientId, which is empty when it wasn’t sent.

Only UK and US_15 checks appear in the list.
LT and HU checks are never returned here. They still run normally — their results come back in the create response.
There is no endpoint to get one check by ID. Use the id filter instead.

Parameter	Behaviour
`id`	The check `id` from the create response
`clientId`	Exact match
`name`, `surname`	Exact match, not case-sensitive
`created`	Two dates separated by a comma, e.g. `created=2026-01-01,2026-02-01`. A date on its own means the start of that day in UTC, so the end day itself is left out.
`databases`	Comma-separated: `UK`, `US_15`
`status=MATCH`	Checks where every field is `MATCH`, `NO_DATA`, `NO_INPUT` or empty. A check with only `NO_DATA` therefore counts as a match.
`status=NO_MATCH`, `PARTIAL_MATCH` or `NO_DATA`	Checks where any field has that status. `INVALID` and `NO_INPUT` can’t be filtered on.
`checkedFields`	Comma-separated. These values use underscores: `first_name`, `last_name`, `date_of_birth`, `id_num`, `address1`, etc.
`orderBy`	`created` or `-created`

Understanding response fields:In the response data, fields are categorized into two types:

Informational fields: Names like firstName, lastName, etc. These directly mirror the data you provided in the request and are not verified against the database.
Status fields: Names ending with *Status, like firstNameStatus, lastNameStatus. These indicate the outcome of verifying the corresponding informational field against the database.

The system verifies each applicable field individually; there is no single overall verification status for the entire request.

Response Example

[
  {
    "id": "a86aff0a-95a2-46a3-a9fa-27fabfef37f6",
    "database": "US_15",
    "clientId": "client-123",
    "firstName": "Thomas R",
    "lastName": "Ahern",
    "middleName": null,
    "dob": "1979-02-24",
    "yob": 1979,
    "address1": null,
    "address2": null,
    "city": null,
    "state": "NY",
    "zip": null,
    "idNum": null,
    "phone": null,
    "email": null,
    "firstNameStatus": "MATCH",
    "lastNameStatus": "MATCH",
    "middleNameStatus": null,
    "dobStatus": "MATCH",
    "yobStatus": null,
    "address1Status": null,
    "address2Status": null,
    "cityStatus": null,
    "stateStatus": "MATCH",
    "zipStatus": null,
    "idNumStatus": null,
    "phoneStatus": null,
    "emailStatus": null
  },
  {
    "id": "c2d1e0f4-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
    "database": "UK",
    "clientId": null,
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "1985-04-12",
    "address": {
      "line1": "10 Sample Street",
      "line2": "Flat 2",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "UK"
    },
    "firstNameStatus": "MATCH",
    "lastNameStatus": "MATCH",
    "dateOfBirthStatus": "MATCH",
    "addressStatus": "NO_MATCH",
    "addressStatusScore": 0
  }
]

Result Delivery and Errors

A standalone Soft KYC check sends no webhook. Results arrive inline in the response and in the dashboard. Webhook delivery applies only when the check runs as part of an identity verification — and even then there is no webhook form for the UK database.

Status	Meaning	What to do
`201`	The check ran. The result is in the response, and one check is charged to that database’s balance.	—
`400`	A field failed validation. The error names the field. A `US_15` request without either `dob` or `idNum` gets errors on both fields.	Fix the field and resend
`403`	”Action not allowed due to lack of funds or exceeded limit.” No balance or limit is set up for that database, or it’s used up.	Contact iDenfy to check your pricing for that database
`404`	”Results for registry center check were not found.” No result was stored.	Check the input and retry

A 404 does not mean “person not found”, and it is not charged. It means no result was stored, because:

the provider was unreachable or returned something unreadable, or
the Lithuanian personal code isn’t numeric.

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Age Estimation

Bank Card Verification

Fraud Prevention

Bank Verification

Social Screening

Going Live

Reference

How It Works

Generate Request

Supported Databases

Rules for Every Database

Lithuania (`LT`)

Hungary (`HU`)

United Kingdom (`UK`)

United States (`US_15`)

Possible Status Values

List Soft ID Verification Checks

Response Example

Result Delivery and Errors

​How It Works

​Generate Request

​Supported Databases

​Rules for Every Database

​Lithuania (LT)

​Hungary (HU)

​United Kingdom (UK)

​United States (US_15)

​Possible Status Values

​List Soft ID Verification Checks

​Response Example

​Result Delivery and Errors

How It Works

Generate Request

Supported Databases

Rules for Every Database

Lithuania (`LT`)

Hungary (`HU`)

United Kingdom (`UK`)

United States (`US_15`)

Possible Status Values

List Soft ID Verification Checks

Response Example

Result Delivery and Errors