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. 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

• Argentina. model to use: arg

  • Identity document

• 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.

Supported invoices

• TELMEX. model to use: telmex

• CFE. model to use: cfe

• MOVISTAR

• TELCEL

• TELNOR

• AT&T

• TOTALPLAY

• IZZI

Supported PDFs

• VAT: El Salvador: model F07 v12, F07 v13 and F07 v14. model to use: VAT

• INCOME TAX: El Salvador: model F11 v14, F11 v15, F11 v17 and F11 v18. model to use: INCOME TAX

Supported PDF version and encoding

• PDF Version: 1.4 or higher

• 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 <jwt> 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