---
title: "eKYC Prefill API Reference"
url: "https://developer.incode.com/general-reference/ekyc-prefill-api-reference/"
section: "general-reference"
group: "eKYC Pre-fill Reference"
version: "v1.1"
status: "live"
---
# eKYC Prefill API Reference

The eKYC Prefill endpoint (`POST /omni/externalVerification/ekyc-prefill`) looks up the end user of the session in the configured source and returns the data the source holds. This page explains the request parameters, response schema, lookup limits, and error responses for that endpoint. For the sources available per country and the data each source returns, see [eKYC Prefill Coverage](/general-reference/ekyc-prefill-coverage/). For instructions on how to configure the module in Dashboard, see [eKYC Prefill (Dashboard)](/dashboard-platform-administration/ekyc-prefill-dashboard/).

The endpoint accepts an onboarding session token (`X-Incode-Hardware-Id`) and `x-api-key`, uses `application/json`, and responds synchronously. The Flow or Workflow used for the Session must contain the [eKYC Prefill module](/features-and-modules/ekyc-prefill/).

:::info
This is different than [eKYC API Reference](/general-reference/ekyc-api-reference/).
:::



## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `source` | string | Yes | `US_PREFILL`, `US_PREFILL_EXPRESS`, or `BR_PREFILL`. Must match the source set in the session's module |
| `countryCode` | string | Yes | ISO 3166-1 alpha-2 country code. Must match the module's country: `US` for the US sources, `BR` for `BR_PREFILL` |
| `phone` | string | `US_PREFILL`, `US_PREFILL_EXPRESS` | Phone number in `E.164` format, for example `+12025550123`. Only `+1` numbers are accepted |
| `dateOfBirth` | string | `US_PREFILL` (one of three) | `yyyy-MM-dd`, not in the future and not more than 130 years ago |
| `ssn` | string | `US_PREFILL` (one of three) | 9 digits, as `123456789` or `123-45-6789` |
| `surName` | string | `US_PREFILL` (one of three) | Last name, at most 100 characters |
| `taxIdNumber` | string | `BR_PREFILL` | Brazilian CPF, as 11 digits or `XXX.XXX.XXX-XX` |

Take `source` and `countryCode` from the module in the session's flow configuration rather than hardcoding them. An organization can switch the module's source, and a request with the old source then returns `400`.

### Inputs per source

- `US_PREFILL`: `phone`, plus at least one of `dateOfBirth`, `ssn`, or `surName`. Only the identifiers enabled in the module configuration are accepted; sending one that is disabled returns `400`.
- `US_PREFILL_EXPRESS`: `phone` only.
- `BR_PREFILL`: `taxIdNumber` only. The CPF check digits are verified before the lookup, so an invalid CPF returns `400` without using up a lookup.

Each source ignores the fields it does not use, and never sends them to the data source. No field may be longer than 255 characters. Unknown fields are ignored. `firstName` and `includeDriverLicenseData` have no effect: driver's license data is returned only when the module's **Include driver's license data** option is on.

### Legacy fields

`plugins` (string array) is a legacy field. Do not include it in new integrations. When sent, it must be `["kyc-prefill"]`; any other value returns `400`.

### Example requests

```json Node
{
  "source": "US_PREFILL",
  "countryCode": "US",
  "phone": "+12025550123",
  "dateOfBirth": "1985-11-22"
}
```

```json Node
{ 
  "source": "US_PREFILL_EXPRESS", 
  "countryCode": "US", 
  "phone": "+12025550143" 
}
```

```json Node
{ 
  "source": "BR_PREFILL", 
  "countryCode": "BR", 
  "taxIdNumber": "123.456.789-00" 
}
```

:::info
The CPF in this example fails check-digit validation on purpose, so no real CPF appears in Incode's documentation. Send a valid CPF in production requests.
:::

## Response

`200 OK.` The result is under `kyc-prefill`. Null fields are omitted, and not every source returns every field; see [Returned data per source](/general-reference/ekyc-prefill-coverage/#returned-data-per-source) in eKYC Prefill Coverage.

### Response field categories

Response fields fall into six categories:

- **Status and reasons** describe the outcome of the lookup: `checkStatus`, `message`, `reasonCodes`, `reasons`.
- **Person data** returns the identity the source holds on the looked-up person: `returnedFirstName`, `returnedLastName`, `returnedFullName`, `returnedDob`, `returnedSsn`, `returnedIsItin`, `returnedTaxIdNumber`.
- **Contact information** returns the person's emails, addresses, and phone details: `returnedEmails`, `returnedAddresses`, `returnedPhoneDetails`, `returnedPhoneStatus`, `phoneValid`, `returnedAssociatedPhoneNumbers`.
- **Signals** flag characteristics of the person or their contact details: `returnedPersonSignals`, `returnedCreditSignals`, plus contact signals nested inside addresses and phone details.
- **Driver's license data** is returned only when the module's **Include driver's license data** option is on: `returnedDriverLicenses`.
- **Alternate identities** (`US_PREFILL_EXPRESS` only) list other people the source links to the same phone number: `additionalProfiles`.

### Response fields

| Field | Type | Description |
|---|---|---|
| `checkStatus` | string | `pass`, `partialPass`, `fail`, or `inconclusive`. See [Check statuses](/general-reference/ekyc-prefill-reference/#check-statuses) in eKYC Prefill Reference |
| `message` | string | Present only when no person data was returned. Human-readable and different per source: branch on `checkStatus`, not on this text |
| `returnedFirstName` | string | First name. Not returned by `BR_PREFILL` |
| `returnedLastName` | string | Last name. Not returned by `BR_PREFILL` |
| `returnedFullName` | string | Full name |
| `returnedDob` | string | Date of birth as the source holds it. Usually `yyyy-MM-dd`, but parse it defensively |
| `returnedSsn` | string | SSN as the source holds it. Some sources return it masked |
| `returnedIsItin` | boolean | Whether `returnedSsn` is an Individual Taxpayer Identification Number |
| `returnedTaxIdNumber` | string | `BR_PREFILL` only. The CPF the source holds for the person found, as 11 digits |
| `returnedPersonSignals` | object | Person signals, see below |
| `returnedPhoneDetails` | object | Phone details of the looked-up number, see below |
| `returnedPhoneStatus` | string | `US_PREFILL_EXPRESS` only. Phone status as the source reports it, for example `inactive`. Not a closed list |
| `phoneValid` | boolean | `US_PREFILL_EXPRESS` only. Whether the source considers the looked-up number valid |
| `returnedEmails` | string[] | Email addresses linked to the person |
| `returnedAddresses` | object[] | Addresses linked to the person, see below |
| `returnedCreditSignals` | object | Credit signals, see below |
| `returnedDriverLicenses` | object[] | Driver's licenses. Only when the module requests them |
| `returnedAssociatedPhoneNumbers` | object[] | Other phone numbers linked to the person. The looked-up number is left out |
| `additionalProfiles` | object[] | `US_PREFILL_EXPRESS` only. See [Additional profiles](#additional-profiles) below |
| `reasonCodes` | string[] | Reason codes behind the answer. Not a closed list |
| `reasons` | object[] | Each reason with its code and message |

For the list fields, absent and `[]` both mean none.

### Person signals

| Field | Type | Description |
|---|---|---|
| `isDeceased` | boolean | The person is reported deceased |
| `hasSanction` | boolean | The person appears on a sanctions list |
| `activeMilitary` | boolean | The person is on active military duty |
| `fraudCriminalBackground` | boolean | The person has a fraud or criminal record |

### Phone details

| Field | Type | Description |
|---|---|---|
| `activityScore` | integer | Phone activity score from the source |
| `type` | string | Line type, for example `Mobile` |
| `carrier` | string | Carrier name |
| `lastPorted` | string | Date the number was last ported. Not every source returns it |
| `activityDescription` | string | Free text from the source. Do not branch on it. Not every source returns it |
| `codeRangeAllocated` | boolean | Passed through from the source. Not every source returns it |
| `signals` | object | Contact signals, see below |

### Address

| Field | Type | Description |
|---|---|---|
| `street` | string | Street address |
| `street2` | string | Second address line, when the record has one |
| `city` | string | City |
| `state` | string | State |
| `postalCode` | string | Postal code |
| `signals` | object | Contact signals, see below. Not returned by `BR_PREFILL` |

### Contact signals

| Field | Type | Description |
|---|---|---|
| `highFrequency` | boolean | The phone or address is used by an unusually high number of identities |
| `possibleFraudRisk` | boolean | The phone or address is linked to possible fraud |

### Credit signals

| Field | Type | Description |
|---|---|---|
| `consumerVictimStatement` | boolean | A consumer victim statement is on file |
| `extendedConsumerVictimStatement` | boolean | An extended consumer victim statement is on file |

### Driver's license

| Field | Type | Description |
|---|---|---|
| `licenseNumber` | string | License number |
| `issuingState` | string | Issuing state |
| `firstReportedDate` | string | First date the license was reported |
| `lastReportedDate` | string | Last date the license was reported |

### Associated phone number

| Field | Type | Description |
|---|---|---|
| `phoneNumber` | string | Phone number |
| `firstReportedDate` | string | First date the number was reported for the person |
| `lastReportedDate` | string | Last date the number was reported for the person |

### Additional profiles

`US_PREFILL_EXPRESS` only. Other identities the source links to the same phone number. They are less reliable than the main result and can be different people. Each profile has the main result's person and contact fields (`returnedFirstName`, `returnedLastName`, `returnedFullName`, `returnedDob`, `returnedPersonSignals`, `returnedEmails`, `returnedAddresses`, `returnedCreditSignals`, `returnedDriverLicenses`, `returnedAssociatedPhoneNumbers`), and never an `SSN`, phone details, a `checkStatus`, or `reasons`.

At most 4 profiles are returned. The field is absent when there are none, which does not mean that nobody else is linked to the number.

### Example response

`US_PREFILL`, fictional data:

```json Node
{
  "kyc-prefill": {
    "checkStatus": "pass",
    "returnedFirstName": "Sarah",
    "returnedLastName": "Johnson",
    "returnedFullName": "Sarah Johnson",
    "returnedDob": "1985-11-22",
    "returnedSsn": "987-65-4321",
    "returnedPersonSignals": { "isDeceased": false, "hasSanction": false, "activeMilitary": false, "fraudCriminalBackground": false },
    "returnedPhoneDetails": {
      "activityScore": 1000,
      "type": "Mobile",
      "carrier": "Example Wireless",
      "signals": { "highFrequency": false, "possibleFraudRisk": false }
    },
    "returnedEmails": ["sarah.johnson@example.com"],
    "returnedAddresses": [
      {
        "street": "100 Maple Dr",
        "city": "Bethesda",
        "state": "MD",
        "postalCode": "20814",
        "signals": { "highFrequency": false, "possibleFraudRisk": false }
      }
    ],
    "returnedCreditSignals": { "consumerVictimStatement": false, "extendedConsumerVictimStatement": false },
    "returnedAssociatedPhoneNumbers": [
      { "phoneNumber": "+12025550147", "firstReportedDate": "2025-08-15", "lastReportedDate": "2025-11-06" }
    ],
    "reasonCodes": ["MC1006", "MC1000"],
    "reasons": [
      { "code": "MC1006", "message": "Phone number intelligence check met" },
      { "code": "MC1000", "message": "Phone Number and date of birth match" }
    ]
  }
}
```

`BR_PREFILL`, fictional data:

```json Node
{
  "kyc-prefill": {
    "checkStatus": "pass",
    "returnedFullName": "Ana Paula Costa Ferreira",
    "returnedDob": "1970-03-12",
    "returnedTaxIdNumber": "12345678900",
    "returnedEmails": ["ana.ferreira@example.com"],
    "returnedAddresses": [
      { "street": "R Exemplo 307", "city": "Fortaleza", "state": "CE", "postalCode": "60710160" },
      { "street": "AV Modelo 696", "street2": "AP 3", "city": "Fortaleza", "state": "CE", "postalCode": "60415540" }
    ],
    "reasonCodes": ["MC1008"],
    "reasons": [{ "code": "MC1008", "message": "Id number match" }]
  }
}
```

### No data found

When the source holds no data for the identifier, the response is still `200`, with `checkStatus` `fail` (or `inconclusive` for `BR_PREFILL`), a message, and the source's reason codes. `US_PREFILL_EXPRESS` also returns the phone fields for the looked-up number when the source checked it.

```json Node
{
  "kyc-prefill": {
    "checkStatus": "fail",
    "message": "No person data was returned for the provided phone number.",
    "returnedPhoneStatus": "inactive",
    "phoneValid": false,
    "reasonCodes": ["RC2001", "RC1006"],
    "reasons": [ ... ]
  }
}
```

A `fail` means nobody is on file. A failure of the data source is never reported as `fail`; it returns `503`, see [Errors](#errors) below.

### Minimum age

A source can set a minimum age for the people it returns. `BR_PREFILL` sets it at 18; the US sources set none. When the person found is under that age, or their age cannot be established from the date of birth, the answer is withheld:

```json Node
{
  "kyc-prefill": {
    "checkStatus": "pass",
    "returnedEmails": [],
    "returnedAddresses": [],
    "reasonCodes": ["Minor"],
    "reasons": [{ "code": "Minor", "message": "..." }]
  }
}
```

- `checkStatus` stays `pass`, because the source did match, and no person field is returned.
- `Minor` and `AgeUnknown` are the two reason codes. They come from Incode, not from the source.
- No person data from the source is stored for the lookup, and neither is the identifier that was sent.
- The lookup counts against the session limit, and a repeat of it is not matched to the stored answer. With `BR_PREFILL`'s limit of one lookup per session, treat a withheld answer as final.

### Lookups per session

Lookups are limited per session and the limit does not reset. See [Lookup limits](/general-reference/ekyc-prefill-coverage/#lookup-limits) in eKYC Prefill Coverage.

- Any answer (`pass`, `partialPass`, `fail`, or `inconclusive`) uses up one lookup. A `400` or a `503` does not.
- A repeated call with the same input in the same session returns the stored result. It does not make a new lookup and does not use up the limit.
- Once the limit is reached, a call with new input returns `429`.

## Errors

The eKYC Prefill endpoint returns conventional HTTP response codes. Validation errors return `400` with a specific message; authentication and authorization errors return `401` or `403`; lookup limits return `429`; data source failures return `503`. The error body has this shape:

```json Node
{
  "timestamp": 1760600000000,
  "status": 400,
  "error": "Send at least one of: dateOfBirth, ssn, surName.",
  "message": "Send at least one of: dateOfBirth, ssn, surName.",
  "path": "/omni/externalVerification/ekyc-prefill"
}
```

The `error` and `message` fields are always identical. Parse either one.

| HTTP | Body status | Cause |
|---|---|---|
| 400 | 400 | A field is missing, too long, or has the wrong format; `source` or `countryCode` does not match the module; or an identifier is not enabled in the module. See the messages below |
| 400 | 4210 | Phone number country is not supported. The phone is not a `+1` number, or the source rejects it for the country |
| 401 | (no body) | Missing, invalid, or expired session token, or a token from a different organization than the `x-api-key` |
| 403 | 4091 | The token is not an onboarding session token with the required access level |
| 403 | 403 | The session or the organization cannot use this module. See the messages below |
| 406 | 406 | The body is empty or not JSON, or a field has the wrong JSON type |
| 409 | 409 | Another call for the same session is still running |
| 415 | 415 | `Content-Type` is missing or is not `application/json` |
| 429 | 429 | The eKYC Prefill lookup limit for this session has been reached |
| 429 | (plain text) | The organization rate limit was reached. Only this one sends `Retry-After` |
| 503 | 8001 | The data source could not be reached or did not give a usable answer. Retrying later can succeed |

### 400 messages

| Message | Cause |
|---|---|
| source is required. Supported sources: ... | `source` is missing |
| source is not supported. Supported sources: ... | `source` is not one of the listed values |
| source XX is not the source configured for this session. | `source` does not match the module |
| countryCode must be XX for source YY. | `countryCode` does not match the source |
| phone is required. / taxIdNumber is required. | The source's lookup identifier (`phone` or `taxIdNumber`) is missing |
| Send at least one of: dateOfBirth, ssn, surName. | `US_PREFILL` was called with the `phone` only |
| XX is not enabled in this session's eKYC Prefill configuration. | An identifier was sent that the module does not enable |
| phone must be in E.164 format..., phone is not a valid phone number. | `phone` is not a valid `E.164` number |
| dateOfBirth must use the yyyy-MM-dd format., etc. | `dateOfBirth` is invalid |
| ssn must have 9 digits, as 123456789 or 123-45-6789. | `ssn` is invalid |
| surName cannot be blank. | `surName` is blank |
| taxIdNumber must be a CPF, as 11 digits or XXX.XXX.XXX-XX. | `taxIdNumber` does not have a CPF format |
| taxIdNumber is not a valid CPF. | The CPF check digits do not match |
| XX cannot be longer than N characters. | A field is too long |
| plugins must be ["kyc-prefill"] when it is sent. | `plugins` has another value |

### 403 messages

| Message | Cause |
|---|---|
| The onboarding session is closed or does not belong to this organization. | The session is closed, deleted, or belongs to another organization |
| eKYC Prefill is not part of this session's flow or workflow. | The session's Flow or Workflow does not contain the module |
| The eKYC Prefill module is configured with a country its source does not serve. | The module's country is not the source's country |
| eKYC Prefill is not available for this source. | The source is not enabled |
| eKYC Prefill is not provisioned for this organization and country. | The organization is not enabled for the source in that country |