> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/ocr/ocr-document.md).

# Document Reader

This service is used to read information from a document image with **FacePhi OCR technology** and organize the information into fields.

The service can handle different types of documents including identity cards, foreign cards, invoices, and PDFs. It is necessary to specify the **document type** and the **model** to process the document correctly.

For a complete list of supported document types and models, see [Documents supported by OCR](#documentos-soportados-por-ocr).

### Documents supported by OCR

#### Document types

The OCR service can process different types of documents. Use the parameter `type` to specify the type of document to process:

| Type          | Value          | Description                               |
| ------------- | -------------- | ----------------------------------------- |
| Identity card | `id_card`      | National identity cards                   |
| Foreign card  | `foreign_card` | Foreign identification cards              |
| PDF           | `pdf`          | PDF documents that require OCR processing |
| Invoice       | `invoice`      | Invoice documents                         |

#### Supported models by document type

*Identity cards (ID Cards)*

For identity cards, use the country code **ISO 3166-1 alpha-3** as the parameter `model`:

| Country   | ISO Code |
| --------- | -------- |
| Argentina | `ARG`    |
| Mexico    | `MEX`    |

*Foreign cards (Foreign Cards)*

For foreign cards, use the following codes as the parameter `model`:

| Country | ISO Code |
| ------- | -------- |
| Mexico  | `MEX`    |

*Invoices*

For invoices, use the supplier code as the parameter `model`:

| Supplier | Code     |
| -------- | -------- |
| TELMEX   | `TELMEX` |
| CFE      | `CFE`    |

*PDF documents*

For PDF documents, use the document type code as the parameter `model`:

| Document type           | Code         |
| ----------------------- | ------------ |
| VAT: El Salvador        | `VAT`        |
| Income Tax: El Salvador | `INCOME TAX` |

### Endpoint

```
POST /ocr
```

### Headers

| Name          | Type   | Required | Description                                                |
| ------------- | ------ | -------- | ---------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | Access authorization API key.                              |
| **family**    | string | No       | Value: **Onboarding**. Required with the tracking service. |

{% hint style="info" %}
All calls to the Endpoints for Tracking with **Identity Platform** must contain the header `family`.
{% endhint %}

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type      | Required | Description                                                                                                                                                                                  |
| ---------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                 | string    | **Yes**  | Document type to process. Only the types allowed in the tenant configuration can be used. Possible values: `id_card`, `passport`, `driver_license`, `foreign_card`, `invoice`, `pdf`         |
| `model`                | string    | **Yes**  | Identifier of the document model to process. For identity documents, use the country code **ISO 3166-1 alpha-3**. For invoices or PDF documents, use the specific codes provided by FacePhi. |
| `files`                | string\[] | **Yes**  | Document images encoded in **Base64** (RFC4648). **Maximum of two images** per request. The first image is treated as the front side.                                                        |
| `isCropped`            | boolean   | No       | Indicates whether the provided images are already cropped. **Default value:** `false`                                                                                                        |
| `forceDetection`       | boolean   | No       | Forces OCR detection even if automatic document detection fails. **Default value:** `false`                                                                                                  |
| `retrieveImages`       | boolean   | No       | Returns cropped images in the response when supported for the configured tenant. **Default value:** `false`                                                                                  |
| `tracking`             | object    | No       | Object that represents the necessary tracking information.                                                                                                                                   |
| `tracking.extraData`   | string    | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.                                                                                            |
| `tracking.operationId` | string    | No       | Operation identifier generated by the Mobile/Web SDK.                                                                                                                                        |

#### Request example

```json
{
  "type": "pdf",
  "model": "IVA",
  "files": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."],
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter              | Type    | Description                                                              |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `serviceResultCode`    | integer | Code indicating the **overall result** of the service execution.         |
| `serviceResultLog`     | string  | Descriptive field of the service execution result.                       |
| `timestamp`            | string  | Moment when the service finished processing.                             |
| `serviceTransactionId` | string  | Transaction identifier associated with the request processed by the API. |
| `serviceResult`        | object  | Object with the OCR result containing the **extracted fields**.          |
| `serviceTime`          | string  | Total service execution time **(milliseconds)**.                         |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

| serviceResultCode | Description                                                                       | HTTP code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 0                 | The service execution was successful, the module processed the request correctly. | 200       |

#### Response example

```json
{
  "serviceResultCode": 200,
  "serviceResultLog": "Service executed ok",
  "timestamp": "2024-07-12T09:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "dictionary": {
      "CommercialName": "Example Comercial Name",
      "DeclarationNumber": "11111111111",
      "EconomicActivity": "National Transports",
      "NIT": "9999-999999-999-9",
      "NRC": "999999-9",
      "Name": "John Doe",
      "TaxedPeriod": "04 2021"
    },
    "model": "IVA",
    "side": "front",
    "type": "pdf",
    "version": "2021"
  },
  "serviceTime": "638"
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

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

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```