> 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/extract-document-data.md).

# Extract Document Data

This service returns all data extracted from an identification document by applying OCR to the MRZ code, PDF, barcode, and visible fields in other areas of the document according to the model defined for each country.

### Integration

This service is used for implementations of the **SelphID Mobile Widget** sending the property **TokenOCR** generated from the Widget's native function.

### Endpoint

```
POST /services/extractDocumentData
```

### 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                                                                                                                                                                         |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenOcr`             | string | **Yes**  | Token generated by the native or hybrid SelphID Widget, **encrypted with AES256** and Tokenized, sent in the format **Base64**. It contains the OCR result of the document capture. |
| `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
{
  "tokenOcr": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "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 service execution. See [Service Result Code](#service-result-code)         |
| `serviceResultLog`     | string  | Descriptive field of the result of the service execution. Module details are included in case of error or exception. |
| `serviceDocument`      | string  | Object representing the captured document. Its properties are **all fields extracted by the OCR process**.           |
| `serviceTime`          | string  | Total service execution time **(milliseconds)**.                                                                     |
| `serviceTransactionId` | string  | Transaction identifier associated with the request processed by the API.                                             |

#### 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": 0,
  "serviceResultLog": "Service request successfully processed",
  "serviceTime": "19",
  "serviceDocument": "{\"Back/BARCODE/BarcodeData\":\"ABC123\",\"Back/BARCODE/BarcodeType\":\"Code39\",\"Back/BARCODE/DocumentData\":\"ABC123\",\"Back/INPUT/Issuer\":\"USA\",\"Back/MRZ/DateOfBirth\":\"01/01/1980\",\"Back/MRZ/DateOfExpiry\":\"01/01/2030\",\"Back/MRZ/DocumentCode\":\"P\",\"Back/MRZ/DocumentData\":\"123456789\",\"Back/MRZ/DocumentNumber\":\"987654321\",\"Back/MRZ/FirstName\":\"JOHN\",\"Back/MRZ/FullName\":\"JOHN DOE\",\"Back/MRZ/Issuer\":\"USA\",\"Back/MRZ/LastName\":\"DOE\",\"Back/MRZ/MrzText\":\"P<USA123456789987654321<<<<<<<<<<<<<\\n8001015<3001017USA<<<<<<<<<<<1\\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<\",\"Back/MRZ/Nationality\":\"USA\",\"Back/MRZ/NfcKey\":\"123456789\",\"Back/MRZ/Opt2\":\"300101\",\"Back/MRZ/PrimaryID\":\"DOE\",\"Back/MRZ/SecondaryID\":\"JOHN\",\"Back/MRZ/Verified\":\"YES\",\"DateOfBirth\":\"01/01/1980\",\"DateOfExpiry\":\"01/01/2030\",\"DateOfIssue\":\"01/01/2020\",\"DocumentCaptured\":\"US/v2\",\"DocumentNumber\":\"987654321\",\"FirstName\":\"JOHN\",\"Front/INPUT/Issuer\":\"USA\",\"Front/ML/DateOfBirth\":\"01/01/1980\",\"Front/ML/DateOfExpiry\":\"01/01/2030\",\"Front/ML/DateOfIssue\":\"01/01/2020\",\"Front/ML/DocumentNumber\":\"987654321\",\"Front/ML/FirstName\":\"JOHN\",\"Front/ML/LastName\":\"DOE\",\"Front/ML/Nationality\":\"USA\",\"FullName\":\"JOHN DOE\",\"Issuer\":\"USA\",\"LastName\":\"DOE\",\"MatchingSidesScore\":\"1.000\",\"Nationality\":\"USA\",\"NfcKey\":\"123456789\"}",
  "serviceTransactionId": "123e4567-e89b-12d3-a456-426614174000"
}
```

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