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

# Create Credit Check

> Create a soft or hard credit check session for an applicant

```
POST /v1/credit-check/hard
POST /v1/credit-check/soft
```

Creates a credit check session and sends email and SMS invitations to the applicant. Use the `/hard` endpoint for a full credit report with AI-powered insights, or `/soft` for a score-only check.

## Request

### Headers

| Header         | Required | Description        |
| -------------- | -------- | ------------------ |
| `x-api-key`    | Yes      | Your API key       |
| `Content-Type` | Yes      | `application/json` |

### Body parameters

Both camelCase and snake\_case parameter names are accepted. If both are provided for the same field, the camelCase value takes priority.

| Parameter           | Alias             | Type    | Required | Description                                                                             |
| ------------------- | ----------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `first_name`        | `firstName`       | string  | Yes      | Applicant's first name                                                                  |
| `last_name`         | `lastName`        | string  | Yes      | Applicant's last name                                                                   |
| `email`             | —                 | string  | Yes      | Applicant's email address                                                               |
| `phone`             | —                 | string  | Yes      | Applicant's phone number in E.164 format (e.g. `+15192223333`)                          |
| `external_id`       | `externalId`      | string  | No       | Your internal reference ID for this session                                             |
| `send_email_invite` | `sendEmailInvite` | boolean | No       | Send an email invitation to the applicant. Defaults to `true`                           |
| `send_phone_invite` | `sendPhoneInvite` | boolean | No       | Send an SMS invitation to the applicant. Defaults to `true`                             |
| `redirect_url`      | `redirectUrl`     | string  | No       | HTTPS URL to redirect the end-user to after the session ends. Must be a valid HTTPS URL |
| `uat`               | —                 | boolean | No       | Put the session into test mode. See [Testing](#testing) below                           |
| `uat_type`          | `uatType`         | string  | No       | The credit scenario to simulate in test mode. See [Testing](#testing) below             |

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.deepidv.com/v1/credit-check/hard \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+15192223333",
      "external_id": "user-12345"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.deepidv.com/v1/credit-check/hard", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      first_name: "John",
      last_name: "Doe",
      email: "john.doe@example.com",
      phone: "+15192223333",
      external_id: "user-12345",
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.deepidv.com/v1/credit-check/hard",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "YOUR_API_KEY",
      },
      json={
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone": "+15192223333",
          "external_id": "user-12345",
      },
  )
  ```
</CodeGroup>

## Response

### 200 — Success

| Field         | Type   | Description                                                              |
| ------------- | ------ | ------------------------------------------------------------------------ |
| `id`          | string | Unique identifier for the created session                                |
| `session_url` | string | URL where the applicant completes the credit check                       |
| `type`        | string | Session type — `credit-check-hard` or `credit-check-soft`                |
| `externalId`  | string | Your external ID (only returned if provided in the request)              |
| `links`       | array  | Convenience links — admin console view and session details API reference |

### Error responses

| Status                  | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `400 Bad Request`       | Invalid request body — check required fields and phone format |
| `401 Unauthorized`      | Missing or invalid API key                                    |
| `402 Payment Required`  | Insufficient token balance                                    |
| `429 Too Many Requests` | Rate limit exceeded                                           |

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "session_url": "https://verify.deepidv.com/credit-check-hard/a1b2c3d4-e5f6-7890-abcd-ef1234567890?oid=your-org-id",
    "type": "credit-check-hard",
    "externalId": "user-12345",
    "links": [
      {
        "rel": "admin_console",
        "href": "https://app.deepidv.com/dashboard/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "description": "Click this link to view this session in your DeepIDV admin console"
      },
      {
        "rel": "session_details",
        "href": "https://api.deepidv.com/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "description": "Use this ref to fetch the session details"
      }
    ]
  }
  ```
</ResponseExample>

***

## Testing

When building your integration, you can create a session in **test mode** so it runs against Equifax's UAT environment using a pre-defined test persona instead of the real applicant's data.

To enable test mode, pass `uat: true` in the request body:

```json theme={null}
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+15192223333",
  "uat": true,
  "uat_type": "STANDARD_HIT"
}
```

<Info>
  In test mode, the applicant can enter **any value** for their SIN and address when completing the session — the real data is not used to query Equifax. The result is driven entirely by the `uat_type` scenario you specify.
</Info>

### `uat_type` values

Use `uat_type` to control which credit scenario the session simulates. If omitted, or if an unrecognized value is passed, a scenario is chosen at random.

#### Clean / standard profiles

| Value              | Description                                       |
| ------------------ | ------------------------------------------------- |
| `SHELL_FILE`       | Minimal credit file — one address, no trades      |
| `MULTIPLE_ADDRESS` | Consumer with multiple addresses on file          |
| `STANDARD_HIT`     | Standard hit — typical credit profile with trades |

#### Bankruptcy

| Value                        | Description                                |
| ---------------------------- | ------------------------------------------ |
| `BANKRUPTCY_DISCHARGED`      | Past bankruptcy, now discharged            |
| `BANKRUPTCY_UNDISCHARGED`    | Active/unresolved bankruptcy               |
| `BANKRUPTCY_VOLUNTARY`       | Voluntary deposit under the Bankruptcy Act |
| `BANKRUPTCY_PROPOSAL`        | Consumer proposal — debt restructuring     |
| `BANKRUPTCY_RECEIVING_ORDER` | Receiving order bankruptcy                 |

#### Collections

| Value                 | Description                               |
| --------------------- | ----------------------------------------- |
| `COLLECTION_UNPAID`   | Unpaid collection account on file         |
| `COLLECTION_UNPAID_2` | Unpaid collection — alternate consumer    |
| `COLLECTION_PAID`     | Paid/settled collection account on file   |
| `COLLECTION_MULTIPLE` | Multiple collections with narrative codes |

#### Legal items

| Value                 | Description                          |
| --------------------- | ------------------------------------ |
| `JUDGEMENT`           | Active judgement on file             |
| `JUDGEMENT_SATISFIED` | Satisfied/resolved judgement on file |
| `FORECLOSURE`         | Foreclosure on file                  |
| `GARNISHMENT`         | Garnishment on file                  |

#### Loans & trades

| Value                | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `SECURE_LOAN`        | Secure loan trade on file                                |
| `MORTGAGE`           | Mortgage and revolving credit                            |
| `STUDENT_LOAN`       | Student loan on file                                     |
| `AUTO_LOAN`          | Auto loan on file                                        |
| `TRADE_R5`           | Trade with R5 (write-off) and R3 ratings                 |
| `TRADE_VARIOUS`      | Various credit cards with semi-monthly payment frequency |
| `TRADE_REPOSSESSION` | Trade with voluntary repossession                        |

#### Alerts & inquiries

| Value             | Description                                |
| ----------------- | ------------------------------------------ |
| `FRAUD_ALERT`     | Lost/stolen wallet alert on file           |
| `FOREIGN_INQUIRY` | Foreign bureau inquiry on file             |
| `MANY_INQUIRIES`  | Consumer with many recent credit inquiries |

#### Other

| Value          | Description                                         |
| -------------- | --------------------------------------------------- |
| `EMPLOYMENT`   | Consumer with current and former employment records |
| `BANKING`      | Personal chequing and savings accounts on file      |
| `TELCO`        | Telco trade with unpaid collection                  |
| `DEATH_NOTICE` | Consumer with a death notice on file                |

### Example — test request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.deepidv.com/v1/credit-check/hard \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+15192223333",
      "uat": true,
      "uat_type": "BANKRUPTCY_DISCHARGED"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.deepidv.com/v1/credit-check/hard", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      first_name: "John",
      last_name: "Doe",
      email: "john.doe@example.com",
      phone: "+15192223333",
      uat: true,
      uat_type: "BANKRUPTCY_DISCHARGED",
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.deepidv.com/v1/credit-check/hard",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "YOUR_API_KEY",
      },
      json={
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone": "+15192223333",
          "uat": True,
          "uat_type": "BANKRUPTCY_DISCHARGED",
      },
  )
  ```
</CodeGroup>