DocumentationAPI Reference
General reference · eKYB Reference / eKYB Prefill Coverage

United States

eKYB Pre-fill in the US leverages official business registry data to automatically retrieve and populate business information based on a company's name and address, including the business name, registered address, entity type, registration status, and directors — without requiring manual input from the user.

Source

Country Source Description
United States US_KYB_PREFILL Returns matching US business details from official business registry data for pre-fill.

Direct API approach

For general integration notes and shared response semantics, see the eKYB Prefill API Reference.

All module configurations and user data can be forwarded directly in the request for performing a Prefill lookup. This overrides existing configuration and data collected about the user.

Endpoint

POST /omni/externalVerification/ekyb-prefill

Request parameters

Parameter Required Description
plugins Mandatory String array. Must be ["ekyb-prefill"]. Specifies the Prefill flow.
source Mandatory String. Must be US_KYB_PREFILL. Identifies the Prefill source.
country Mandatory String. Two-letter Alpha-2 country code. Must be US.
businessName Mandatory String. Registered name of the business.
address Mandatory String. Business address as a freeform string. Must contain at minimum city + state (for example: San Francisco, CA). City alone is not accepted.
taxId Optional String. US Employer Identification Number (EIN / TIN). When provided, adds tinMatch to the response. See Tax ID formats for details.

Tax ID formats

EIN (Employer Identification Number), also referred to as TIN, is the US federal tax identifier assigned to businesses by the IRS. Providing taxId is optional. When included, it enables IRS TIN verification and adds tinMatch to the response.

Format Example
9 numeric digits, no spaces or special characters 943320693

Sample request

{
    "plugins": ["ekyb-prefill"],
    "source": "US_KYB_PREFILL",
    "country": "US",
    "businessName": "Acme Solutions LLC",
    "address": "San Francisco, CA",
    "taxId": "123456789"
}

Sample response

The Prefill response returns business data retrieved directly from the source of truth. nameMatch, addressMatch, and tinMatch reflect the result of comparing submitted inputs against registry data.

{
  "kyb-prefill": [
    {
      "name": "Acme Solutions LLC",
      "nameMatch": "Approximate Match",
      "address": "742 Nebula Lane, San Francisco, CA 94107",
      "addressMatch": "Approximate Match",
      "tinMatch": "Verified",
      "entityType": "C_CORPORATION",
      "registrationStatus": "Active",
      "directors": [
        { "name": "Ethan Caldwell", "positionName": "Chief Executive Officer" },
        { "name": "Maya Reynolds", "positionName": "Officer" },
        { "name": "Lucas Bennett", "positionName": "Director" },
        { "name": "Sofia Mitchell", "positionName": "Assistant Secretary" }
      ]
    }
  ]
}

Info

addressMatch is evaluated against all addresses on file for the business, not only the primary registered address. If the submitted city + state matches any address on file, the result may return as Verified or Approximate Match even when the primary registered address is in a different location.

tinMatch is only present in the response when taxId was submitted in the request. When taxId is omitted, all other response fields are still returned.

Response fields

Key Value Description
name Business name The registered legal name of the business as returned from the source of truth.
nameMatch Verified, Approximate Match, Unverified Match result comparing the submitted businessName against the name on file in the source of truth. See Name and address match values for details.
address Registered address The primary registered address of the business as returned from the source of truth.
addressMatch Verified, Approximate Match, Unverified Match result comparing the submitted address against all addresses on file for the business. See Name and address match values for details.
tinMatch Verified, Potential Match, Unverified Match result from IRS TIN verification. Only present in the response when taxId was submitted in the request. See TIN match values for details.
entityType Entity type The legal entity type of the business as returned from the source of truth (for example, C_CORPORATION, LLC).
registrationStatus Active, Inactive, Unknown Current registration status of the business. See Registration status values for details.
directors Array of {name, positionName} Officers and directors associated with the business as returned from the source of truth. positionName reflects the primary title on file. Includes directors, managers, and other officers — role types are not separated.

Name and address match values

Status Description
Verified Exact match found against registry data.
Approximate Match Similar match found; may reflect minor differences in naming or address formatting.
Unverified No match found in registry data.

TIN match values

Status Description
Verified The submitted TIN matches IRS records exactly.
Potential Match The submitted TIN is a partial or probable match against IRS records.
Unverified The submitted TIN does not match IRS records.

Registration status values

Status Description
Active The business is actively registered in at least one state.
Inactive The business registration is lapsed or dissolved.
Unknown The registration status could not be determined.

Error responses

For standard HTTP response codes, see the API Error Response page. US Prefill returns the following country-specific 400 errors.

businessName is missing or empty:

{
    "timestamp": 1782851408892,
    "status": 400,
    "error": "Bad Request",
    "message": "Missing required field: businessName.",
    "path": "/omni/externalVerification/ekyb-prefill"
}

address is missing, empty, or cannot be resolved to at least city + state:

{
    "timestamp": 1782851468367,
    "status": 400,
    "error": "Bad Request",
    "message": "address must contain at minimum city and state.",
    "path": "/omni/externalVerification/ekyb-prefill"
}

Single Session Dashboard results

Prefill results are available on the Business tab in Single Session view.

Was this page helpful?