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

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

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

string

required

Your internal user ID. FraudEG links this verification record to all future activity for this user.

string

required

Verification type. Use individual for consumer KYC and business for KYB. The set of required fields differs by type (see below).

Individual Fields (`type: "individual"`)

string

required

Legal first name as it appears on the user’s government-issued ID.

string

required

Legal last name as it appears on the user’s government-issued ID.

string

required

Date of birth in ISO 8601 format (YYYY-MM-DD), e.g., "1990-07-22".

object

required

Current residential address of the individual.

Show address fields

string

required

Street address line 1.

string

required

City or locality.

string

required

State, province, or region.

string

required

Postal or ZIP code.

string

required

ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE").

object

Optional identity document details for document validity checks.

Show document fields

string

Document type. Accepted values: passport, drivers_license, national_id.

string

Document number as printed on the ID.

string

ISO 3166-1 alpha-2 code of the country that issued the document.

string

Document expiry date in ISO 8601 format (YYYY-MM-DD).

string

User’s phone number in E.164 format (e.g., "+14155552671"). Used for phone-to-identity matching checks.

string

User’s email address. Used for email-to-identity matching and cross-referencing against breach databases.

Business Fields (`type: "business"`)

string

required

The business’s registered legal name exactly as it appears in official registration documents.

string

required

Company registration number or Employer Identification Number (EIN). Used to look up the business in national registries.

string

required

ISO 3166-1 alpha-2 country code of the business’s country of incorporation.

object

required

The business’s official registered address.

Show registered_address fields

string

required

Street address line 1.

string

required

City or locality.

string

required

State, province, or region.

string

required

Postal or ZIP code.

string

required

ISO 3166-1 alpha-2 country code (e.g., "US", "DE").

Response Fields

string

Unique FraudEG identifier for this verification request. Use this ID to look up status later or reference it in support requests.

string

Your internal user ID, echoed back from the request.

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.

array

List of individual checks performed for this verification.

Show check object fields

string

Check identifier. Possible values: identity_match, document_validity, liveness, database_check, address_verification, phone_match.

string

Check outcome. One of pass, pending, or fail.

string

ISO 8601 timestamp of when the verification was submitted.

string | null

ISO 8601 timestamp of when all checks completed. null if status is pending.

Code Example

cURL

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)

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

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

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.

Overview

Transactions

Identity

Monitoring

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

Endpoint

Request Headers

Request Body

Individual Fields (`type: "individual"`)

Business Fields (`type: "business"`)

Response Fields

Code Example

Example Request Body (Individual)

Example Response

​Endpoint

​Request Headers

​Request Body

​Individual Fields (type: "individual")

​Business Fields (type: "business")

​Response Fields

​Code Example

​Example Request Body (Individual)

​Example Response

Endpoint

Request Headers

Request Body

Individual Fields (`type: "individual"`)

Business Fields (`type: "business"`)

Response Fields

Code Example

Example Request Body (Individual)

Example Response