---
title: "United States"
url: "https://developer.incode.com/general-reference/us-prefill/"
section: "general-reference"
group: "eKYB Reference / eKYB Prefill Coverage"
version: "v1.1"
status: "live"
---
# 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](/general-reference/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

```javascript Node
{
    "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.

```javascript Node
{
  "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:

```javascript Node
{
    "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:

```javascript Node
{
    "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](/dashboard-platform-administration/single-session-view/).