> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Soft KYC

> Run lightweight identity verification using database checks without full document scanning via the iDenfy Soft KYC (eIDV) API endpoint.

<Note>
  **Requirements:**

  * API key pair
  * Soft ID settings enabled (configured by iDenfy staff)
  * Finances added to your environment
</Note>

***

## Generate Request

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

<Note>
  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.
</Note>

### 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 |

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

### Request Parameters (`US_15`)

<AccordionGroup>
  <Accordion title="firstName — string (required)">
    First name of the person to verify.
  </Accordion>

  <Accordion title="lastName — string (required)">
    Last name of the person to verify.
  </Accordion>

  <Accordion title="database — string (required)">
    Must be `US_15` for the field set below.
  </Accordion>

  <Accordion title="dob — string (conditionally required)">
    Date of birth in `YYYY-MM-DD` format. Must place the person between 5 and 150 years old.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="middleName — string (optional)">
    Middle name of the person to verify.
  </Accordion>

  <Accordion title="yob — integer (optional)">
    Year of birth. Ignored when `dob` is also sent.
  </Accordion>

  <Accordion title="state — string (optional)">
    State code, exactly 2 characters (e.g., `CA`).
  </Accordion>

  <Accordion title="city — string (optional)">
    City name, at least 2 characters.
  </Accordion>

  <Accordion title="address1 — string (optional)">
    Primary address line.
  </Accordion>

  <Accordion title="address2 — string (optional)">
    Secondary address line.
  </Accordion>

  <Accordion title="zip — string (optional)">
    Postal/ZIP code. Digits only.
  </Accordion>

  <Accordion title="phone — string (optional)">
    Phone number.
  </Accordion>

  <Accordion title="email — string (optional)">
    Email address.
  </Accordion>

  <Accordion title="clientId — string (optional)">
    Your own identifier for the person. Echoed back in the response and usable as a filter on the list endpoint.
  </Accordion>
</AccordionGroup>

<Warning>
  An empty string counts as "not sent". `"firstName": ""` returns a required-field error rather than an empty match.
</Warning>

### Request Example

```json theme={"system"}
{
  "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

```json theme={"system"}
{
  "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` |

<Note>
  **Understanding response fields:**

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

  1. **Informational fields:** Names like `firstName`, `lastName`, etc. These directly mirror the data you provided in the request and are not verified against the database.
  2. **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.
</Note>

### 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`. |

<Note>
  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`.)
</Note>

### Response Example

```json theme={"system"}
[
  {
    "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

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>


## Related topics

- [Soft ID Verification](/guides/dashboard/kyc/soft-id-verification.md)
- [Team Member Management](/guides/dashboard/settings/team-member-management.md)
- [Biometric and Liveness](/guides/dashboard/settings/biometric-liveness.md)
- [Branding (KYC)](/guides/dashboard/settings/kyc-branding.md)
- [KYC Webhooks](/kyc/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.