# Auth Initial

`POST https://api.agilitycredit.net/v3/prefill/auth`

Docs page: https://apidocs.agilitycredit.com/api/prefill-auth-initial · Tag: Prefill

Starts the possession step of the Prefill flow, confirming the applicant controls the supplied mobile number. Choose a channel via `type`:

- `otp` — An SMS one-time passcode is sent to the applicant. Complete the step by submitting the code to **Auth Final** (`POST /prefill/auth/{session_id}`).
- `magic_link` — An `auth_url` (a Magic Link) is returned. Present it to the applicant; after they tap it, **poll** Auth Final to read the result.

The response carries the engine-minted `session_id` (echo it back on Auth Final as the `{session_id}` path parameter) and an `Agc-Applicant-Id` response header identifying the applicant record. Pass `Agc-Applicant-Id` back on later calls to update the same applicant instead of creating a new one.

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

Possession initiation payload. Use the Magic Link or OTP variant.

Variant 1: `ProveAuthInitialMagicLink`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string: `magic_link` | yes | Possession channel. Use `magic_link` for the Magic Link flow. |
| `phone_mobile` | string | yes | The applicant's mobile phone number. |
| `callback_url` | string (uri) | yes | Required when `type` is `magic_link`. HTTPS URL associated with the session. The applicant currently sees a standard Agility confirmation page after tapping the Magic Link; redirecting the browser back to this URL is planned for a future i… |
| `secret` | string |  | Optional shared secret. When supplied, responses for this session are signed with an `X-Agc-Signature` header (HMAC-SHA256 over `{timestamp}.{body}`), matching the Agility webhook signing convention. |
| `dob` | string |  | Optional applicant date of birth. Accepted formats: `YYYY-MM-DD` (full ISO-8601, e.g. `1990-01-31`) or `MM/YYYY` (month and year only, e.g. `01/1990`). |
| `message_text` | string |  | Optional custom prefix for the Magic Link SMS. The engine appends the auth URL after a colon: `"${message_text}: ${authUrl}"`. When omitted, the server auto-brands with the tenant name, e.g. `"Verify your identity with ExampleCU: https://.… |
| `last4_ssn` | string |  | Optional last four digits of the applicant's SSN. |

Variant 2: `ProveAuthInitialOtp`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string: `otp` | yes | Possession channel. Use `otp` for the SMS one-time passcode flow. |
| `phone_mobile` | string | yes | The applicant's mobile phone number. The passcode is sent here. |
| `secret` | string |  | Optional shared secret. When supplied, responses for this session are signed with an `X-Agc-Signature` header (HMAC-SHA256 over `{timestamp}.{body}`), matching the Agility webhook signing convention. |
| `dob` | string |  | Optional applicant date of birth. Accepted formats: `YYYY-MM-DD` (full ISO-8601, e.g. `1990-01-31`) or `MM/YYYY` (month and year only, e.g. `01/1990`). |
| `message_text` | string |  | Optional custom SMS body text. Prove substitutes the generated one-time passcode where `#####` appears. When omitted, the server uses a tenant-branded default (e.g. `"Your ExampleCU verification code is #####."`). Must include `#####` for … |
| `last4_ssn` | string |  | Optional last four digits of the applicant's SSN. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Possession step initiated | one of: ProveAuthResponseInitialMagicLink, ProveAuthResponseInitialOtp |
| 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: `ProveAuthResponseInitialMagicLink`, `ProveAuthResponseInitialOtp`.

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