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. For instructions on how to configure the module in Dashboard, see 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.

Request

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

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

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

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

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

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

Person signals

Phone details

Address

Contact signals

Credit signals

Driver's license

Associated phone number

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:

{
  "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:

{
  "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.

{
  "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 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:

{
  "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 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:

{
  "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.

400 messages

403 messages