# OTP Initial

`POST https://api.agilitycredit.net/v3/precise-id/otp`

Docs page: https://apidocs.agilitycredit.com/api/precise-id-otp-initial · Tag: Precise ID

The "OTP Initial" endpoint provides One-Time Passcode (OTP)  authentication for identity verification during account opening processes. This  service generates and validates SMS-based OTP codes to verify that the applicant  has access to the provided phone number. The workflow consists of two steps:  first, an OTP is generated and sent to the applicant's phone number, then the  applicant submits the received code for validation. This multi-factor authentication  approach enhances security by confirming phone number ownership and reducing the  risk of identity fraud during account creation.

Authentication: `Authorization: Bearer <api key>`.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | A unique, idempotent key. We recommend to use a guid |
| `Agc-Tenant-Id` | header | yes | The tenant ID provided by Agility Credit. |
| `Agc-User-Id` | header | yes | The requestor user ID. |
| `Agc-Applicant-Id` | header |  | If passed, will assign the report to that applicant. If not, will create a new applicant ID |

## Request body (`application/json`), required

Inquiry request payload.

> ⚠️ **Data is automatically sanitized** before it is sent to the bureau —
> disallowed characters are stripped, values are reformatted or truncated to
> the bureau's limits, and values that cannot be made valid are dropped. Your
> original values are still stored on the applicant record. See
> [**Precise ID data sanitization**](https://apidocs.agilitycredit.com/data-sanitization/precise-id) for the
> full per-field rules.

Variant 1: `PreciseID`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string: `json`, `raw`, `xml` |  |  |
| `applicant` | object | yes |  |
| `applicant.first_name` | string | yes | Applicant first name. Minimum entry is the first initial. Compound names should be separated with a hyphen or space. Allowable special characters: hyphen, space, apostrophe. |
| `applicant.middle_name` | string |  | Applicant middle name; a middle initial is acceptable. Blanks and special characters are not allowed. Omit if not available. |
| `applicant.last_name` | string | yes | Applicant surname; must be two or more characters. Split double surnames with a hyphen (e.g. Smith-Jones). Apostrophe usage is limited to the letters D, L and O. Allowable special characters: hyphen, space, apostrophe. The full name (last … |
| `applicant.suffix` | string: `JR`, `SR`, `II`, `III`, `IV`, `V`, `VI`, `VII`, `VIII`, `IX` |  | Generation / name suffix code. |
| `applicant.ssn` | string | yes | Social Security Number (required); 4, 9 or 11 characters. Allowable special characters: hyphen, space. |
| `applicant.dob` | string |  | Applicant date of birth in YYYY-MM-DD format (a bare YYYY is also accepted and treated as dob_year). Use dob when the full birth date is available; otherwise use dob_year. |
| `applicant.dob_year` | string |  | Applicant year of birth in YYYY format. Use when the full date of birth is not available. |
| `applicant.age` | integer |  | Applicant age. Domain 14 - 120. |
| `applicant.phone_mobile` | string |  | Applicant mobile telephone number; 10 digits (e.g. 5551234567). Formatting characters and a leading country-code 1 are removed automatically; the value must reduce to exactly 10 digits or it is dropped from the bureau request. |
| `applicant.phone_home` | string |  | Applicant home telephone number; 10 digits (e.g. 5551234567). Formatting characters and a leading country-code 1 are removed automatically; the value must reduce to exactly 10 digits or it is dropped from the bureau request. |
| `applicant.phone_work` | string |  | Applicant work telephone number; 10 digits (e.g. 5551234567). Formatting characters and a leading country-code 1 are removed automatically; the value must reduce to exactly 10 digits or it is dropped from the bureau request. |
| `applicant.emails` | array of string |  | Up to 3 applicant email addresses. Allowable special characters: at sign, underscore, hyphen, period. |
| `applicant.address` | object | yes | Applicant current address. The full address (street + city + state + zip) cannot exceed 118 characters. |
| `applicant.address.po_box_number` | string |  | PO Box number, included as part of the street line. |
| `applicant.address.street1` | string | yes | Street address, PO Box or route number. Allowable special characters: forward slash, period, hyphen, pound sign, space. |
| `applicant.address.street2` | string |  | Additional street address line. |
| `applicant.address.city` | string | yes | City name. Allowable special characters: apostrophe, period, hyphen, space. |
| `applicant.address.state_code` | string | yes | Two-character state code. |
| `applicant.address.zip` | string | yes | ZIP code. Allowable special characters: hyphen. |
| `applicant.address.country_code` | string |  | ISO country code. |
| `applicant.address.time_at_address` | object |  | Time at the current residence. Provide both years and months together — residence-duration reporting is omitted if only one is supplied. |
| `applicant.address_previous` | object |  | Applicant previous address (informational only). The full address (street + city + state + zip) cannot exceed 118 characters. |
| `applicant.address_previous.po_box_number` | string |  | PO Box number, included as part of the street line. |
| `applicant.address_previous.street1` | string | yes | Street address, PO Box or route number. Allowable special characters: forward slash, period, hyphen, pound sign, space. |
| `applicant.address_previous.street2` | string |  | Additional street address line. |
| `applicant.address_previous.city` | string | yes | City name. Allowable special characters: apostrophe, period, hyphen, space. |
| `applicant.address_previous.state_code` | string | yes | Two-character state code. |
| `applicant.address_previous.zip` | string | yes | ZIP code. Allowable special characters: hyphen. |
| `applicant.address_previous.country_code` | string |  | ISO country code. |
| `applicant.address_previous.time_at_address` | object |  | Time at the previous residence. Provide both years and months together — residence-duration reporting is omitted if only one is supplied. |
| `applicant.employment` | object |  | Applicant current employment. The full employment data (company + address + city + state + zip) cannot exceed 73 characters. |
| `applicant.employment.employer_name` | string |  | Company name; required when employment is supplied. Allowable special characters: pound sign, ampersand, hyphen, space. |
| `applicant.employment.employer_address` | object |  |  |
| `applicant.employment.income` | object |  |  |
| `applicant.employment_previous` | object |  | Applicant previous employment. |
| `applicant.employment_previous.employer_name` | string |  | Company name. Allowable special characters: pound sign, ampersand, hyphen, space. |
| `applicant.employment_previous.employer_address` | object |  |  |
| `applicant.employment_previous.income` | object |  |  |
| `applicant.mothers_maiden_name` | string |  | Applicant mother's maiden name. |
| `applicant.spouse_name` | string |  | Full name of the applicant's spouse. |
| `applicant.no_of_dependents` | integer |  | Total number of dependents, excluding the applicant. |
| `applicant.driver_license` | object |  |  |
| `applicant.driver_license.number` | string |  | Driver's license number; required when driver_license is supplied. A minimum of two characters must be entered. Allowable special characters: space, asterisk, hyphen. |
| `applicant.driver_license.state` | string |  | Two-character driver's license state code; required when driver_license is supplied. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Inquiry processed successfully | one of: PreciseIDResponseOTPInitial |
| 400 | Bad Request | BadRequestResponse |
| 401 | Unauthorized | UnauthorizedResponse |
| 403 | Forbidden | UnauthorizedResponse |
| 429 | Too Many Requests | TooManyRequestsResponse |
| 500 | Internal Server Error | AgilityServerErrorResponse |
The 200 body is one of: `PreciseIDResponseOTPInitial`.

### Error bodies

400:

```json
{
  "status": "Bad Request - Invalid Parameters",
  "error": "Failed schema validation. Error: data.pull_type must be one of ['prequal', 'hard'], Path: ['data', 'pull_type'], Data: prequalification"
}
```

401:

```json
{
  "message": "Unauthorized"
}
```

403:

```json
{
  "message": "Unauthorized"
}
```

429:

```json
{
  "error": "Too Many Requests"
}
```

500:

```json
{
  "message": "Agility Server Error"
}
```