Document Reader

This service is used to read information from a document image with FacePhi OCR technology and organize the information into fields.

The service can handle different types of documents including identity cards, foreign cards, invoices, and PDFs. It is necessary to specify the document type and the model to process the document correctly.

For a complete list of supported document types and models, see Documents supported by OCR.

Documents supported by OCR

Document types

The OCR service can process different types of documents. Use the parameter type to specify the type of document to process:

Type	Value	Description
Identity card	id_card	National identity cards
Foreign card	foreign_card	Foreign identification cards
PDF	pdf	PDF documents that require OCR processing
Invoice	invoice	Invoice documents

Supported models by document type

Identity cards (ID Cards)

For identity cards, use the country code ISO 3166-1 alpha-3 as the parameter model:

Country	ISO Code
Argentina	ARG
Mexico	MEX

Foreign cards (Foreign Cards)

For foreign cards, use the following codes as the parameter model:

Country	ISO Code
Mexico	MEX

Invoices

For invoices, use the supplier code as the parameter model:

Supplier	Code
TELMEX	TELMEX
CFE	CFE

PDF documents

For PDF documents, use the document type code as the parameter model:

Document type	Code
VAT: El Salvador	VAT
Income Tax: El Salvador	INCOME TAX

Endpoint

POST /ocr

Headers

Name	Type	Required	Description
x-api-key	string	Yes	Access authorization API key.
family	string	No	Value: Onboarding. Required with the tracking service.

All calls to the Endpoints for Tracking with Identity Platform must contain the header family.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
type	string	Yes	Document type to process. Only the types allowed in the tenant configuration can be used. Possible values: id_card, passport, driver_license, foreign_card, invoice, pdf
model	string	Yes	Identifier of the document model to process. For identity documents, use the country code ISO 3166-1 alpha-3. For invoices or PDF documents, use the specific codes provided by FacePhi.
files	string[]	Yes	Document images encoded in Base64 (RFC4648). Maximum of two images per request. The first image is treated as the front side.
isCropped	boolean	No	Indicates whether the provided images are already cropped. Default value: false
forceDetection	boolean	No	Forces OCR detection even if automatic document detection fails. Default value: false
retrieveImages	boolean	No	Returns cropped images in the response when supported for the configured tenant. Default value: false
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

{
  "type": "pdf",
  "model": "IVA",
  "files": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."],
  "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 the service execution.
serviceResultLog	string	Descriptive field of the service execution result.
timestamp	string	Moment when the service finished processing.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
serviceResult	object	Object with the OCR result containing the extracted fields.
serviceTime	string	Total service execution time (milliseconds).

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

{
  "serviceResultCode": 200,
  "serviceResultLog": "Service executed ok",
  "timestamp": "2024-07-12T09:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "dictionary": {
      "CommercialName": "Example Comercial Name",
      "DeclarationNumber": "11111111111",
      "EconomicActivity": "National Transports",
      "NIT": "9999-999999-999-9",
      "NRC": "999999-9",
      "Name": "John Doe",
      "TaxedPeriod": "04 2021"
    },
    "model": "IVA",
    "side": "front",
    "type": "pdf",
    "version": "2021"
  },
  "serviceTime": "638"
}

400 Bad Request

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "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

{
  "message": "Endpoint request timed out"
}