# Out-of-Wallet Initial

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

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

The "Out of Wallet Questions - Initial Request" endpoint performs identity  verification through knowledge-based questions derived from the applicant's  credit history and public records. This service presents multiple-choice questions  about the applicant's financial history, previous addresses, loans, or other personal information that only the legitimate person should know.  The workflow includes an initial step that generates questions based on available  data, followed by a final step that evaluates the applicant's answers and  provides scoring results. This "in-wallet" authentication method helps  verify identity by testing knowledge of information typically found in  the applicant's credit file and financial records.

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: PreciseIDResponseKIQInitial |
| 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: `PreciseIDResponseKIQInitial`.

### 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"
}
```