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

# POST /v1/identity/verify — KYC and KYB Verification

> POST /v1/identity/verify — submit user identity data for KYC or KYB verification. Returns synchronous or asynchronous verification status.

Submit identity data for a user or business to run Know Your Customer (KYC) or Know Your Business (KYB) verification. FraudEG cross-references the submitted data against authoritative identity databases, document validity services, and liveness detection depending on the checks your plan includes. Simple checks return a `verified` or `failed` status synchronously; checks that require document analysis or third-party database lookups return `pending` and deliver the final result via webhook.

## Endpoint

```http theme={null}
POST https://api.fraudeg.com/v1/identity/verify
```

## Request Headers

| Header          | Value              | Required |
| --------------- | ------------------ | -------- |
| `Authorization` | `Bearer <API_KEY>` | Yes      |
| `Content-Type`  | `application/json` | Yes      |

## Request Body

<ParamField body="user_id" type="string" required>
  Your internal user ID. FraudEG links this verification record to all future activity for this user.
</ParamField>

<ParamField body="type" type="string" required>
  Verification type. Use `individual` for consumer KYC and `business` for KYB. The set of required fields differs by type (see below).
</ParamField>

### Individual Fields (`type: "individual"`)

<ParamField body="first_name" type="string" required>
  Legal first name as it appears on the user's government-issued ID.
</ParamField>

<ParamField body="last_name" type="string" required>
  Legal last name as it appears on the user's government-issued ID.
</ParamField>

<ParamField body="date_of_birth" type="string" required>
  Date of birth in ISO 8601 format (`YYYY-MM-DD`), e.g., `"1990-07-22"`.
</ParamField>

<ParamField body="address" type="object" required>
  Current residential address of the individual.

  <Expandable title="address fields">
    <ParamField body="line1" type="string" required>
      Street address line 1.
    </ParamField>

    <ParamField body="city" type="string" required>
      City or locality.
    </ParamField>

    <ParamField body="state" type="string" required>
      State, province, or region.
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal or ZIP code.
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"GB"`, `"DE"`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="document" type="object">
  Optional identity document details for document validity checks.

  <Expandable title="document fields">
    <ParamField body="type" type="string">
      Document type. Accepted values: `passport`, `drivers_license`, `national_id`.
    </ParamField>

    <ParamField body="number" type="string">
      Document number as printed on the ID.
    </ParamField>

    <ParamField body="issuing_country" type="string">
      ISO 3166-1 alpha-2 code of the country that issued the document.
    </ParamField>

    <ParamField body="expiry_date" type="string">
      Document expiry date in ISO 8601 format (`YYYY-MM-DD`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="phone" type="string">
  User's phone number in E.164 format (e.g., `"+14155552671"`). Used for phone-to-identity matching checks.
</ParamField>

<ParamField body="email" type="string">
  User's email address. Used for email-to-identity matching and cross-referencing against breach databases.
</ParamField>

### Business Fields (`type: "business"`)

<ParamField body="legal_name" type="string" required>
  The business's registered legal name exactly as it appears in official registration documents.
</ParamField>

<ParamField body="registration_number" type="string" required>
  Company registration number or Employer Identification Number (EIN). Used to look up the business in national registries.
</ParamField>

<ParamField body="country" type="string" required>
  ISO 3166-1 alpha-2 country code of the business's country of incorporation.
</ParamField>

<ParamField body="registered_address" type="object" required>
  The business's official registered address.

  <Expandable title="registered_address fields">
    <ParamField body="line1" type="string" required>
      Street address line 1.
    </ParamField>

    <ParamField body="city" type="string" required>
      City or locality.
    </ParamField>

    <ParamField body="state" type="string" required>
      State, province, or region.
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal or ZIP code.
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"DE"`).
    </ParamField>
  </Expandable>
</ParamField>

## Response Fields

<ResponseField name="verification_id" type="string">
  Unique FraudEG identifier for this verification request. Use this ID to look up status later or reference it in support requests.
</ResponseField>

<ResponseField name="user_id" type="string">
  Your internal user ID, echoed back from the request.
</ResponseField>

<ResponseField name="status" type="string">
  Current verification status. One of:

  * `verified` — All checks passed; the identity is confirmed.
  * `pending` — One or more checks are still running asynchronously.
  * `failed` — One or more checks failed; the identity could not be confirmed.
  * `flagged` — The identity matched a watchlist, adverse media, or fraud database entry.
</ResponseField>

<ResponseField name="checks" type="array">
  List of individual checks performed for this verification.

  <Expandable title="check object fields">
    <ResponseField name="name" type="string">
      Check identifier. Possible values: `identity_match`, `document_validity`, `liveness`, `database_check`, `address_verification`, `phone_match`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Check outcome. One of `pass`, `pending`, or `fail`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the verification was submitted.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  ISO 8601 timestamp of when all checks completed. `null` if `status` is `pending`.
</ResponseField>

## Code Example

```bash cURL theme={null}
curl --request POST \
  --url https://api.fraudeg.com/v1/identity/verify \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "usr_8f3kd92",
    "type": "individual",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1990-07-22",
    "address": {
      "line1": "123 Maple Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94103",
      "country": "US"
    },
    "document": {
      "type": "passport",
      "number": "A12345678",
      "issuing_country": "US",
      "expiry_date": "2030-05-14"
    },
    "phone": "+14155552671",
    "email": "jane@example.com"
  }'
```

### Example Request Body (Individual)

```json theme={null}
{
  "user_id": "usr_8f3kd92",
  "type": "individual",
  "first_name": "Jane",
  "last_name": "Smith",
  "date_of_birth": "1990-07-22",
  "address": {
    "line1": "123 Maple Street",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94103",
    "country": "US"
  },
  "document": {
    "type": "passport",
    "number": "A12345678",
    "issuing_country": "US",
    "expiry_date": "2030-05-14"
  },
  "phone": "+14155552671",
  "email": "jane@example.com"
}
```

### Example Response

```json theme={null}
{
  "verification_id": "idv_6mKpX3nQ9wR",
  "user_id": "usr_8f3kd92",
  "status": "pending",
  "checks": [
    { "name": "identity_match", "status": "pass" },
    { "name": "document_validity", "status": "pending" },
    { "name": "liveness", "status": "pending" },
    { "name": "database_check", "status": "pass" }
  ],
  "created_at": "2024-11-15T12:00:00Z",
  "completed_at": null
}
```

<Note>
  When the response `status` is `pending`, some checks are still running asynchronously. Subscribe to the `identity.verification_completed` webhook event to receive the final result without polling. The webhook payload includes the same fields as this response, with `status` and `completed_at` updated to their final values.
</Note>