> 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/sdks/backend-sdk/ocr/technical_documentation/api_reference.md). # API reference guide ## 1. Introduction This section includes the description of the API of the service provided in the product **Facephi OCR Service**. ## 2. Rest API In summary, the following endpoints are available: ### `/api/v1/process` and `/api/v1/process_multi` These endpoints are used to read information from the image of a document using Facephi OCR technology and classify the information into fields. The difference between the two endpoints is that the first processes only the Latin alphabet, while the second processes multiple alphabets (Latin, Cyrillic, Arabic, Chinese, etc.). Meaning of the parameters: * `type` (optional): It is necessary to specify the type of document to be processed, since our service can handle different types of documents. Values available in the JSON: **id\_card, passport, driver\_license, foreign\_card, invoice, pdf**. * If it is not present, `id_card`. * `model` (optional): This parameter specifies the ID of the document to be processed. In the case of invoices or PDF documents, see the following list. Otherwise, this identifier corresponds to the document's country of origin. To specify this country, follow the standard specified in [ISO\_3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). In the case of **`invoice` or `pdf`**, use the key from the following tables. * If it is not present, all countries are considered. * `files`: Array of strings. Each position in the array is a raw image buffer encoded in base64 *RFC4648*. Maximum two files. The first image will be the front side of a **id\_card**. * `isCropped` (optional): If the `image` is already cropped and aligned, the service can avoid performing these operations. Only applies to documents `invoice`. * `forceDetection` (**DEPRECATED**, optional): If the document `invoice` does not have the correct aspect ratio, the service can perform an operation to correct it and improve document detection. Only applies to documents `invoice`. * `retrieveImages` (optional): The service will return the cropped image in base64 in the final result. * If it is not present, `false`. #### Supported document types | Document name | parameter `type` | | ----------------- | ---------------- | | Identity document | `id_card` | | Driver's license | `driver_license` | | Foreign card | `foreign_card` | | PDF | `pdf` | | Invoice | `invoice` | #### Models supported by interpreter v1 * [x] Argentina. `model` to use: **arg** * Identity document * [x] Mexico. `model` to use: **mex** * Identity document * Foreign card #### Models supported by interpreter v2 You will find more information in [country-supported documents in interpretation v2](https://github.com/facephi/facephi-gitbook-docs/tree/master/docs/sdks/backend-sdk/ocr/technical_documentation/api_reference/models_v2.md). #### Supported invoices * [x] TELMEX. `model` to use: **telmex** * [x] CFE. `model` to use: **cfe** * [ ] MOVISTAR * [ ] TELCEL * [ ] TELNOR * [ ] AT\&T * [ ] TOTALPLAY * [ ] IZZI #### Supported PDFs * [x] VAT: El Salvador: model F07 v12, F07 v13 and F07 v14. `model` to use: **VAT** * [x] INCOME TAX: El Salvador: model F11 v14, F11 v15, F11 v17 and F11 v18. `model` to use: **INCOME TAX** **Supported PDF version and encoding** * [x] PDF version: 1.4 or higher * [x] Encoding: iText 2.1.7, macOS Version Quartz PDFContext with embedded text option enabled. ### `/api/v1/health` The goal of this endpoint is to ensure that the service works correctly. ### `/api/v1/version` This endpoint returns the service version. ### `/api/v1/config` This endpoint is used to query (GET) and update (POST) the service configuration without needing to restart it. Only some parameters are modifiable at runtime. The JWT authentication startup settings are intentionally hidden in the GET response and are rejected in the POST operation. Optional JWT authentication can be enabled at startup from `config.json` or through the environment variables `FACEPHI_OCR_REST_AUTH_*`. When JWT is enabled, `GET /api/v1/version` and `GET /api/v1/health` remain public, while the rest of the endpoints require a valid JWT through `Authorization: Bearer ` or the configured API key header. ### `/api/v1/raw` This endpoint is used to read information from the image of a document using Facephi OCR technology. Meaning of the parameters: * `type`: It is necessary to specify the type of document to be processed, since our service can handle different types of documents. Values available in the JSON: **id\_card, passport, driver\_license, foreign\_card, invoice, pdf**. * `image`: Raw image buffer encoded in base64 *RFC4648*. ## 3. Errors | Message | Meaning | Solution | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Invalid License. Status code: `STATUS_CODE` | License error | Contact the Facephi support team | | Document could not be read, empty buffer | The file passed to the service is empty | Check the service input | | Invalid PDF. Check the supported encodings | The PDF file has an unsupported encoding | Review the documentation to check the supported encoding | | Invalid image for the OCR engine | The image passed to the OCR engine is incorrect | Review the image passed to the service or contact the Facephi support team | | No text has been extracted from the PDF engine | The library has been enabled to extract text from the PDF, but it has not been able to interpret it | Contact the Facephi support team | | No text has been found with the OCR engine | The OCR engine has not been able to extract text from the image | Review the image passed to the service, validate the supported image format and quality, or contact the Facephi support team | | The text has not been interpreted with the OCR interpreter | The template used for that image is not valid | Contact the Facephi support team | | Pipeline file not found | The service configuration is incorrect | Contact the Facephi support team | | Invoice pipeline error | The service configuration is incorrect | Contact the Facephi support team | | Error converting pipeline configuration to JSON from path: `RESOURCE_PATH` | The service configuration is incorrect | Contact the Facephi support team | | Error loading pipeline configuration from path: `RESOURCE_PATH` | The service configuration is incorrect | Contact the Facephi support team | | Model not found. Check the model path | The service configuration is incorrect | Contact the Facephi support team |