> 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 service API provided in the product **Facephi OCR Service**. ## 2. Rest API In summary, the following entry points 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 both endpoints is that the first one processes only the Latin alphabet, while the second one processes multiple alphabets (Latin, Cyrillic, Arabic, Chinese, etc.). Meaning of the parameters: * `type` (optional): It is necessary to specify the type of document to process, since our service can handle different types of documents. Available values in the JSON: **id\_card, passport, driver\_license, foreign\_card, invoice, pdf**. * If it is not present, the following is used `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 list below. 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 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` (**OBSOLETE**, 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, the following is used `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 [documents supported by country in v2 interpretation](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 enabled. ### `/api/v1/health` The purpose 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 can be modified at runtime. JWT authentication startup settings are intentionally hidden in the GET response and 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 process, since our service can handle different types of documents. Available values 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 | | The 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 verify 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 was extracted from the PDF engine | The library has been enabled to extract text from the PDF, but it could not interpret it | Contact the Facephi support team | | No text was found with the OCR engine | The OCR engine could not 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 was not 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 the pipeline configuration to JSON from path: `RESOURCE_PATH` | The service configuration is incorrect | Contact the Facephi support team | | Error loading the 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 |