Soft KYC

Requirements:

API key pair
Soft ID settings enabled (configured by iDenfy staff)
Finances added to your environment

Generate Request

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

For US_15, supply at least one of dob or idNum (full SSN or last 4 digits). Without either, the provider has only the name to match against. Do not rely on receiving a validation error when both are missing — enforcement of this rule is inconsistent.

Supported Databases

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

`database`	Required fields	Optional
`LT`	`checkedPersonalNumber`	`checkedDocumentType`, `clientId`
`HU`	`checkedMrz`	`clientId`
`UK`	`firstName`, `lastName`, `dateOfBirth`, `address`	`clientId`
`US_15`	`firstName`, `lastName` (see below)	see below

There is no endpoint that lists the databases enabled for your account. Contact iDenfy to find out which ones you can call.

Request Parameters (`US_15`)

firstName — string (required)

First name of the person to verify.

lastName — string (required)

Last name of the person to verify.

database — string (required)

Must be US_15 for the field set below.

dob — string (conditionally required)

Date of birth in YYYY-MM-DD format. Must place the person between 5 and 150 years old.

idNum — string (conditionally required)

Full SSN or last 4 digits. Must be exactly 4 or 9 digits — any other length is silently dropped before the provider is called, so the check runs without it.

middleName — string (optional)

Middle name of the person to verify.

yob — integer (optional)

Year of birth. Ignored when dob is also sent.

state — string (optional)

State code, exactly 2 characters (e.g., CA).

city — string (optional)

City name, at least 2 characters.

address1 — string (optional)

Primary address line.

address2 — string (optional)

Secondary address line.

zip — string (optional)

Postal/ZIP code. Digits only.

phone — string (optional)

Phone number.

email — string (optional)

Email address.

clientId — string (optional)

Your own identifier for the person. Echoed back in the response and usable as a filter on the list endpoint.

An empty string counts as “not sent”. "firstName": "" returns a required-field error rather than an empty match.

Request Example

{
  "firstName": "John",
  "lastName": "Smith",
  "state": "CA",
  "database": "US_15",
  "yob": 1980,
  "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": 1980,
  "address1": "Benson str",
  "address2": "3914",
  "city": "San Jose",
  "state": "CA",
  "zip": "95128",
  "idNum": "897884526",
  "phone": "+14165555678",
  "email": "example.email@gmail.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"
}

List/Retrieve Soft ID Verification Checks

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

The response is a plain, unpaginated array of every matching check. Narrow it with these query parameters:

Parameter	Description
`clientId`	Your own identifier, as sent on the check
`name`, `surname`	First and last name
`created`	Comma-separated date-time range
`databases`	Comma-separated list, e.g. `US_15,UK`
`status`	`MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, or `NO_DATA`
`checkedFields`	Restrict to checks where the given fields were checked
`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.

Possible Status Values

Status	Description
`MATCH`	The provided data matches the database record.
`PARTIAL_MATCH`	The provided data partially matches the database record.
`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.
`NO_INPUT`	The corresponding input field was provided but contained blank or empty data.
`NO_DATA`	No corresponding data was found in the database source for comparison.
`null`	The corresponding input field was not included in the request or was explicitly `null`.

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.)

Response Example

[
  {
    "id": "13c7c069-d4d8-405b-a442-3fe483068ca5",
    "firstName": "Jay Alan",
    "lastName": "Neander",
    "state": "IL",
    "middleName": null,
    "dob": "1981-08-31",
    "yob": null,
    "gender": "MALE",
    "address": null,
    "city": "Chicago",
    "zip": "60646",
    "phone": null,
    "maritalStatus": "MARRIED",
    "firstNameStatus": "NO_MATCH",
    "lastNameStatus": "NO_MATCH",
    "stateStatus": "NO_MATCH",
    "middleNameStatus": null,
    "dobStatus": "NO_MATCH",
    "yobStatus": null,
    "genderStatus": "NO_MATCH",
    "addressStatus": null,
    "cityStatus": "NO_MATCH",
    "zipStatus": "NO_MATCH",
    "phoneStatus": null,
    "maritalStatusStatus": "NO_DATA",
    "database": "US_1"
  },
  {
    "id": "83cb0614-ff58-41e6-afac-6f24b8ff0072",
    "firstName": "Jay Adomas",
    "lastName": "Neander",
    "state": "IL",
    "middleName": null,
    "dob": null,
    "yob": null,
    "address": null,
    "city": null,
    "zip": null,
    "phone": null,
    "idNum": null,
    "firstNameStatus": "MATCH",
    "lastNameStatus": "MATCH",
    "middleNameStatus": null,
    "dobStatus": null,
    "yobStatus": null,
    "addressStatus": null,
    "cityStatus": null,
    "zipStatus": null,
    "phoneStatus": null,
    "idNumStatus": null,
    "database": "US_4"
  },
  {
    "id": "a86aff0a-95a2-46a3-a9fa-27fabfef37f6",
    "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,
    "database": "US_15"
  }
]

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.

A provider outage surfaces as 404 with "Results for registry center check were not found". This reads like “no record matched”, but it means the upstream source could not be reached — retry rather than treating it as a negative result.

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Age Estimation

Bank Card Verification

Fraud Prevention

Bank Verification

Going Live

Reference

Generate Request

Supported Databases

Request Parameters (`US_15`)

Request Example

Response Example

List/Retrieve Soft ID Verification Checks

Possible Status Values

Response Example

Result Delivery and Errors

​Generate Request

​Supported Databases

​Request Parameters (US_15)

​Request Example

​Response Example

​List/Retrieve Soft ID Verification Checks

​Possible Status Values

​Response Example

​Result Delivery and Errors

Generate Request

Supported Databases

Request Parameters (`US_15`)

Request Example

Response Example

List/Retrieve Soft ID Verification Checks

Possible Status Values

Response Example

Result Delivery and Errors