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

# Applicant

> Applicant identity and contact details for a verification order.

# Applicant

Person being verified on an order: identity, optional contact details, addresses, and aliases.

## Fields

| Field                  | Required | Type       | Description                                                                                                                                                                                                 |
| ---------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstName`            | Yes      | `string`   | Applicant first name. Example: `"John"`.                                                                                                                                                                    |
| `lastName`             | Yes      | `string`   | Applicant last name. Example: `"Smith"`.                                                                                                                                                                    |
| `ssn`                  | Yes      | `string`   | Social Security Number. Conventionally formatted as `XXX-XX-XXXX` (example: `"123-45-6789"`). The API requires a non-empty string; format validation is not enforced.                                       |
| `birthday`             | No       | `string`   | Birthday in `YYYY-MM-DD` format. Example: `"1990-05-15"`.                                                                                                                                                   |
| `phone`                | No       | `string`   | Applicant phone number.                                                                                                                                                                                     |
| `email`                | No       | `string`   | Applicant email address. Must be valid when provided.                                                                                                                                                       |
| `signedReleaseFileUrl` | No       | `string`   | Signed release PDF source: HTTPS URL, GCS URI (`gs://`), or base64-encoded PDF (optionally `data:application/pdf;base64,...`). Max 10MB for inline base64. See [Signed release file](#signed-release-file). |
| `addresses`            | No       | `object[]` | Applicant address history. Omit or send `[]` when no home address is available. See [Address](/api-reference/schemas/address).                                                                              |
| `applicantAlias`       | No       | `object[]` | Alternate or former names (AKA). See [Applicant alias](/api-reference/schemas/applicant-alias).                                                                                                             |

<Note>
  `addresses` is optional on order creation. See [Create order — field
  reference](/api-reference/endpoints/create-order#request-body-field-reference) for the full request contract.
</Note>

## Signed release file

`signedReleaseFileUrl` is optional. When provided, the signed release PDF is attached to outbound verification requests (email or fax, depending on organization policy).

You can supply the file in **three ways**:

| Method            | Input                                                                                                   | Stored on search                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **External URL**  | `https://example.com/signed-release.pdf`                                                                | Same HTTPS URL                                                                        |
| **GCS upload**    | `gs://.../releaseForms/...pdf` from [Generate upload URL](/api-reference/endpoints/generate-upload-url) | Same GCS URI                                                                          |
| **Inline base64** | Raw base64 or `data:application/pdf;base64,...`                                                         | Uploaded to cloud storage at order creation; searches store the resulting `gs://` URI |

<Note>
  Inline base64 must decode to a valid PDF (starts with `%PDF`) and must not exceed 10MB. Production accepts HTTPS URLs only (not `http://`).
</Note>

### GCS upload flow (recommended for large files)

1. `GET /files/release-form/generate-upload-url` → `signedUrl`, `fileUri`
2. `PUT` the PDF to `signedUrl` with `Content-Type: application/pdf`
3. Set `applicant.signedReleaseFileUrl` to `fileUri`

### Inline base64 example

```json theme={null}
{
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789",
    "signedReleaseFileUrl": "JVBERi0xLjQK..."
  }
}
```

## Example

```json theme={null}
{
  "firstName": "John",
  "lastName": "Smith",
  "ssn": "123-45-6789",
  "birthday": "1990-05-15",
  "phone": "+1-555-123-4567",
  "email": "john.smith@example.com",
  "signedReleaseFileUrl": "https://example.com/signed-release.pdf",
  "addresses": [
    {
      "addressType": "home",
      "addressLine1": "456 Oak Avenue",
      "addressLine2": null,
      "addressCity": "Los Angeles",
      "addressState": "CA",
      "addressZipCode": "90210",
      "addressCountry": "US",
      "startDate": "2021-01-01",
      "endDate": null
    },
    {
      "addressType": "home",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "addressCity": "New York",
      "addressState": "NY",
      "addressZipCode": "10001",
      "addressCountry": "US",
      "startDate": "2020-01-01",
      "endDate": "2021-01-01"
    }
  ],
  "applicantAlias": [
    {
      "firstName": "Jonathan",
      "lastName": "Smith",
      "middleName": "Michael",
      "suffix": "Jr."
    }
  ]
}
```

## Validation rules

* **SSN**: Required non-empty string. Conventionally `XXX-XX-XXXX`; format validation is not enforced.
* **Email Format**: Must be a valid email address when provided
* **Date Format**: All dates must be in YYYY-MM-DD format
* **Address Requirement**: When `addresses` is non-empty, exactly one address must be current (`endDate: null` or omitted). Omit `addresses` or send `[]` when you do not need home address history.
* **Signed release file**: Must be a valid HTTPS URL (production), GCS URI (`gs://`), or base64-encoded PDF (max 10MB). Inline base64 is uploaded to cloud storage at order creation; searches store the resulting `gs://` URI.

## Related schemas

* [Address](/api-reference/schemas/address) — Address structure
* [Applicant alias](/api-reference/schemas/applicant-alias) — Name alias structure
* [Verification request](/api-reference/schemas/verification-request) — Complete request structure