Skip to content

API Reference guide

1. Introduction

This document includes the API description of the service provided in the Facephi OCR Service product.

2. REST API

The REST API is described in the following Swagger documentation: OCR Service REST API reference

There are entry point availables:

/api/v1/process

This endpoint is used to read information from a document image with OCR Facephi technology and sort the information into fields.

Parameters meaning:

  • type: It is necessary to specify the document type you wish to process as our service can handle different types of documents. Values availables in the JSON: id_card, passport, driver_license, foreign_card, invoice, pdf.
  • model: This parameter specifies the ID of the document to be processed. In the case of invoices or PDF documents, please refer to the list below. Otherwise, this identifier corresponds to the country of origin of the document. To specify this country, follow the standard specified in ISO_3166-1 alpha-3. In case of invoice or pdf use the key in the below tables.
  • files: Array of strings. Each position of the array is an image raw buffer encoded in base64 RFC4648. Maximum two files. The first image will be the front side of a id_card.
  • (optional)isCropped: If the image is already cropped and aligned, the service can avoid to perform the these operations. Only apply to invoice documents.
  • DEPRECATED (optional)forceDetection: If the invoice document has not the right aspect ratio, the service can perform an operation to correct it and improve the document detection. Only apply to invoice documents.
  • (optional)retrieveImages: The service will returns the cropped image as base64 in the final result.

Document type supported

  • IDCard. type to use: id_card
  • Passport.
  • DriversLicense.
  • ForeignCard. type to use: foreign_card
  • PDF. type to use: pdf
  • Invoice. type to use: invoice

IDCard supported

For the document interpreter version 1:

  • Argentina. model to use: arg
  • México. model to use: mex

For the document interpreter version 2:

  • Bolivia. model to use: bol
  • Brazil. model to use: bra
  • Canada. model to use: can
  • Chile. model to use: chl
  • Colombia. model to use: col
  • Costa Rica. model to use: cri
  • Dominican Republic. model to use: dom
  • Ecuador. model to use: ecu
  • Spain. model to use: esp
  • Guatemala. model to use: gtm
  • Honduras. model to use: hnd
  • Jordan. model to use: jor
  • South Korea. model to use: kor
  • Nigeria. model to use: nga
  • Nicaragua. model to use: nic
  • Panama. model to use: pan
  • Peru. model to use: per
  • Paraguay. model to use: pry
  • El Salvador. model to use: slv
  • Uganda. model to use: uga
  • Uruguay. model to use: ury
  • Vietnam. model to use: vnm
  • South Africa. model to use: zaf

ForeignCard supported

  • México. model to use: mex

Invoice supported

  • TELMEX. model to use: telmex
  • CFE. model to use: cfe
  • MOVISTAR
  • TELCEL
  • TELNOR
  • AT&T
  • TOTALPLAY
  • IZZI

PDF supported

  • IVA: El Salvador: F07 v12, F07 v13 and F07 v14 model. model to use: IVA
  • RENTA: El Salvador: F11 v14, F11 v15, F11 v17 and F11 v18 model. model to use: RENTA
PDF version and encoding supported
  • PDF Version: 1.4 or higher
  • Encoding: iText 2.1.7, macOS Version Quartz PDFContext with embed text option enabled.

/api/v1/health

The aim of this endpoint is to ensure that the service functions properly.

/api/v1/version

This endpoint returns the version of the service.

/api/v1/config

This endpoint is used to retrieve (GET) and update (POST) the service configuration without restarting the service. Only some parameters are modifiable at runtime.

/api/v1/raw

This endpoint is used to read information from a document image with OCR Facephi technology.

Parameters meaning:

  • type: It is necessary to specify the document type you wish to process as our service can handle different types of documents. Values availables in the JSON: id_card, passport, driver_license, foreign_card, invoice, pdf.
  • image: Image raw buffer encoded in base64 RFC4648.

3. Errors

Message Meaning Solution
Invalid license. Status code: STATUS_CODE Error on License Contact Facephi support team
Could not read document, buffer empty The file passed to the service is empty Review the service input
Invalid PDF. Check supported encodings The PDF file has an encoding not supported Review the documentation to validate the supported encoding
Image not valid for the OCR engine The image passed to OCR engine is wrong Review the image passed to the service or Contact Facephi support team
Text not extracted from PDF engine The library has been enabled to extract the text from the PDF but was not able to parse it Contact Facephi support team
Text not found with OCR engine The OCR engine was not able to extract text from the image Review the image passed to the service, validate image format supported and quality or Contact Facephi support team
Text not parsed with OCR interpreter The template used for that image is not valid Contact Facephi support team
Pipeline file not found The service configuration is wrong Contact Facephi support team
Invoice pipeline error The service configuration is wrong Contact Facephi support team
Failed to convert pipeline configuration to JSON from path: RESOURCE_PATH The service configuration is wrong Contact Facephi support team
Failed to load pipeline configuration from path: RESOURCE_PATH The service configuration is wrong Contact Facephi support team
Model not found. Check the model path The service configuration is wrong Contact Facephi support team