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

# Document Parsing

> Extract and parse structured data from IDs and documents

The Parsing Model extracts and parses structured data from IDs and documents — names, dates, addresses, amounts, and more.

## Available Models

| Model         | Use Case                                                                                                                                             | Supported File Types      |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `light`       | Parsing light model. Data extraction is aimed at Driver License, State ID, Residency Permit, Social Security Card, Military ID                       | jpg, jpeg, png, webp, pdf |
| `performance` | Parsing performance model. Data extraction is aimed at bank statements, US pay stubs, and common government-issued IDs (for example driver licenses) | jpg, jpeg, png, webp, pdf |

Retrieve the full list of models programmatically:

```bash theme={null}
curl https://api.deepxl.ai/v1/parsing-models \
  -H "x-api-key: YOUR_API_KEY"
```

## Parsing a Document

Submit a file for parsing via `POST /v1/parse`:

```bash theme={null}
curl -X POST https://api.deepxl.ai/v1/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "model=light" \
  -F "file=@drivers_license.jpg" \
  -F 'tags={"customerId":"9999","customerName":"Acme Corp","documentId":"DOC-001","companyName":"DeepXL","companyId":"COMP-001"}'
```

### Parameters

| Parameter | Type   | Required | Description                                                                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `model`   | string | Yes      | `light` or `performance`                                                                                      |
| `file`    | file   | Yes      | The document to parse (max 50MB)                                                                              |
| `tags`    | string | No       | JSON object with metadata key-value pairs                                                                     |
| `country` | string | No       | Optional country hint. Supported values: `us`, `mx`, `br`. Missing, empty, or invalid values default to `us`. |

### Country Hint Behavior

Use the optional `country` parameter when you want to steer parsing toward a specific supported market.

* Supported values: `us`, `mx`, `br`
* Matching is case-insensitive
* Leading and trailing whitespace is ignored
* Missing, empty, or invalid values fall back to `us`

The request value is treated as a **routing hint**. It is normalized before the request is forwarded downstream, and the normalized value is returned as `country` in the parse response metadata.

Example:

```bash theme={null}
curl -X POST https://api.deepxl.ai/v1/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "model=performance" \
  -F "file=@bank_statement.pdf" \
  -F "country=br" \
  -F 'tags={"customerId":"9999","customerName":"Acme Corp","documentId":"DOC-2024-042","companyName":"DeepXL","companyId":"COMP-001"}'
```

## Response Structure

```json theme={null}
{
  "result": {
    "parseId": 123,
    "mediaType": "image",
    "fileType": "jpeg",
    "fileName": "drivers_license.jpg",
    "fileSize": 231433,
    "timestamp": 1770984134,
    "timestampISO": "2026-02-13T13:02:14.833162",
    "model": "light",
    "modelVersion": "1.2.0",
    "documentType": "idDocument",
    "parsedData": {
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfBirth": "1990-05-15",
      "licenseNumber": "D1234567",
      "expirationDate": "2028-05-15",
      "address": "123 MAIN ST ANYTOWN, CA 90210"
    },
    "tags": [
      { "name": "customerId", "value": "9999" },
      { "name": "customerName", "value": "Acme Corp" },
      { "name": "documentId", "value": "DOC-001" },
      { "name": "companyName", "value": "DeepXL" },
      { "name": "companyId", "value": "COMP-001" }
    ],
    "files": [
      {
        "category": "original_file",
        "fileName": "drivers_license.jpg",
        "fileSize": 231433,
        "contentType": "image/jpeg",
        "timestamp": 1770984134,
        "timestampISO": "2026-02-13T13:02:14.833162",
        "url": "https://api.deepxl.ai/v1/files/parse_123_drivers_license.jpg"
      }
    ]
  }
}
```

### Field Reference

| Field          | Type      | Description                                                                    |
| -------------- | --------- | ------------------------------------------------------------------------------ |
| `parseId`      | integer   | Unique identifier for the parse record                                         |
| `mediaType`    | string    | Media type category (`image` or `document`)                                    |
| `fileType`     | string    | File extension (`jpeg`, `png`, `pdf`, `webp`)                                  |
| `fileName`     | string    | Original uploaded file name                                                    |
| `fileSize`     | integer   | File size in bytes                                                             |
| `timestamp`    | integer   | Unix timestamp of the analysis                                                 |
| `timestampISO` | string    | ISO 8601 timestamp of the analysis                                             |
| `model`        | string    | Model used (`light` or `performance`)                                          |
| `modelVersion` | string    | Version of the model used for analysis                                         |
| `documentType` | string    | Identified document type (e.g. `idDocument`, `bankStatement.us`, `payStub.us`) |
| `parsedData`   | object    | Extracted key-value pairs (fields vary by document type)                       |
| `tags`         | object\[] | Metadata tags attached to this parse                                           |
| `files`        | object\[] | Associated files (original upload)                                             |

## Understanding Results

### Document Type

The `documentType` field identifies the parsed document type (for example `idDocument`, `bankStatement.us`, or `payStub.us`).

### Parsed Data

The `parsedData` object contains the extracted key-value pairs. The fields depend on the document type.

**ID Documents (light model):**

| Field            | Description                           |
| ---------------- | ------------------------------------- |
| `firstName`      | First name                            |
| `lastName`       | Last name                             |
| `dateOfBirth`    | Date of birth (YYYY-MM-DD)            |
| `licenseNumber`  | License or document number            |
| `expirationDate` | Document expiration date (YYYY-MM-DD) |
| `address`        | Full address                          |

**`performance` model document types:**

The extracted fields vary by document type. The current set is `idDocument`, `bankStatement.us`, and `payStub.us`.

## Tags and Filtering

Attach metadata to organize your parsing results:

```bash theme={null}
curl -X POST https://api.deepxl.ai/v1/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "model=performance" \
  -F "file=@bank_statement.pdf" \
  -F 'tags={"customerId":"9999","customerName":"Acme Corp","documentId":"DOC-2024-042","companyName":"DeepXL","companyId":"COMP-001"}'
```

Filter your parse history:

```bash theme={null}
curl "https://api.deepxl.ai/v1/parse?tagFilter=customerId=9999" \
  -H "x-api-key: YOUR_API_KEY"
```

## Browsing History

Retrieve paginated parsing results:

```bash theme={null}
curl "https://api.deepxl.ai/v1/parse?limit=25&offset=0&sortBy=parseId&direction=desc" \
  -H "x-api-key: YOUR_API_KEY"
```

### Sort Options

`parseId`, `mediaType`, `fileType`, `fileName`, `fileSize`, `confidence`, `documentType`, `timestamp`