4. Resources - Documents

Fields marked with * are mandatory to correctly use the APIs.

IMPORTANT:

  • All API call examples below are pointing to the SANDBOX environment URLs. For more information on environment URLs, refer to the API Reference.
  • Some URLs are available for both the SDK and Backoffice contexts. Pay attention when the sdk placeholder appears in the URL, as it must be replaced according to the use case, taking the values "sdk" or "backoffice".
  • For /backoffice/* routes, use x-api-key directly on each request.
  • The /backoffice/v1/handshake endpoint is legacy, kept for backward compatibility, and is being deprecated.
  • When examples in this page use Authorization: Bearer <SessionToken>, treat them as legacy Backoffice flow.
  • In direct backoffice flow, the operational sessionId is returned in the response payload (success and error).

4.1 Handshake​

Description​

The Fortface API has a proprietary session creation system. After going through the accreditation stage, the user can create temporary sessions with restricted access to actions previously defined by the system, built through the Handshake.

Before detailing the Handshake header fields and processing steps, it is important to explain the encryption and decryption process of the device fingerprint.

All data handling related to internal Fortface processes follows a strict security protocol. One of the most used pieces of data in all processes is the device fingerprint, and a specific contract is used to securely encapsulate it in the request.

Once the encryption/decryption process is explained, let’s return to the Handshake header fields:

  • Content-Type: Indicates the reading format application/json
  • x-api-key: Security key configured for the client

Below is the required body for the Handshake. The X-API-KEY header field is mandatory to identify the requesting client and its permissions.

Endpoint: /handshake

Method: POST

Payload:

  • galleryId*: User's gallery identifier.
  • accountName*: User's account identifier.
  • action*: Action to be executed: document.
  • deviceRequestInfo*: Encrypted information of the device originating the event.
  • externalTransactionId: External transaction used to group sessions. (optional) The user identifier is externalUserId (used in enroll, identify, and capture endpoints).

Request (Example)​

context: sdk or backoffice

  • sdk/handshake: Generates a valid session for actions through SDK
  • backoffice/handshake: Generates a valid session for actions through Backoffice

Example: A session generated from sdk/handshake will not be valid for the backoffice/liveness endpoint, only for sdk/liveness.

curl --request POST \
  --url https://api-sandbox.fortface.ai/{context}/v1/handshake \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: string' \
  --data '{
    "galleryId": "string",
    "accountName": "string",
    "action": "document",
    "deviceRequestInfo": "string",
    "externalTransactionId": "string"
  }'

Response (Example)​

{
  "body": {
    "sessionToken": "SESSION TOKEN TO ACCESS API RESOURCES",
    "sessionKey": "SESSION KEY USED BY THE SDK",
    "sessionId": "SESSION IDENTIFIER GENERATED BY HANDSHAKE"
  }
}

Processing Steps​

  1. The device fingerprint is encrypted and extracted from the deviceRequestInfo field, and then decrypted.

  2. A hash verification is performed on the decrypted device fingerprint. This hash is generated by a function that associates a hash to each field of deviceInfo. The Fortface API uses the same system as the SDK to generate the local hash. This creates a verification layer for data reliability and structural integrity.

  3. A session is created if the galleryId exists. The API key associated with this gallery must have permission to perform Handshake.

4.2 Document Data Extraction and 1:1 Identification​

Fortface allows extracting data from the document and from the identification provider using the /document endpoint. It also enables 1:1 user identity validation.

Note: The documentGroupId field is a request grouping identifier, but it is optional.

Request Details​

  • Handshake action: document
  • Endpoint: /document
  • Method: POST

Headers​

  • Content-Type: application/json (Defines the request format)
  • Authorization: Bearer {SessionToken} (Token generated via /handshake) for SDK and legacy Backoffice flow.
  • x-api-key: Recommended header for direct Backoffice calls (without handshake).

Payload​

  • imgData (required): Image or PDF file data. Encrypted by the SDK or provided as Base64 via Backoffice.
  • externalUserId (optional): User identifier in the client's system. Required if a comparison with a previously registered face is needed.
  • documentGroupId: (optional)
  • referenceSessionId: (optional)
  • key (required): AES encryption key, protected by an asymmetric algorithm. (Used in SDK)
  • data (required): Encrypted user data. (Used in SDK)
  • returnFile (optional): Indicates if the file/photo should be returned in the response. (Used in SDK)

Request Example​

Context: SDK

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/sdk/v1/document' \
  --header 'Authorization: Bearer (SessionToken from handshake)' \
  --header 'Content-Type: application/json' \
  --data '{
    "imgData": "String <Returns from SDK> or <Base64 from BackOffice>",
    "externalUserId": "String",
    "key": "String <Returns from SDK>",
    "data": "String <Returns from SDK>",
    "returnFile": "Boolean <Returns from SDK>",
    "documentGroupId": "String <Request grouping identifier>",
    "referenceSessionId": "String <Reference session identifier>"
  }'

Response (Example)​

{
  "providers": {
    "typifier": {
      "status": "string",
      "documentType": "string",
      "documentSide": "string",
      "occlusion": "boolean",
      "occlusionReason": "string",
      "country": "string",
      "confidence": "number",
      "isPdf": "boolean",
      "hasCertificate": "boolean",
      "faceStatus": "string",
      "version": "string",
      "pipeline": "string",
      "analysisNote": "string"
    },
    "identify": {
      "matchLevel": {
        "value": "number"
      },
      "status": "string"
    }
  },
  "hash": "string",
  "documentGroupId": "string",
  "api": {
    "env": "string",
    "timestamp": "number",
    "version": "string"
  },
  "fileData": "string"
}

Possible Document Types​

  • NATIONAL_ID: Civil identification documents issued by a national government for its own citizens.
  • FOREIGN_ID: Documents issued by a country different from the individual’s country of origin, intended for legally residing foreigners.
  • PASSPORT: International travel document issued by the citizen's home country for identification abroad.
  • DRIVER_LICENSE: Document that authorizes and identifies drivers of motor vehicles.
  • MILITARY_ID: Document issued by military institutions for identifying active or retired military personnel.
  • STUDENT_ID: Proof of student affiliation with an educational institution.
  • PROFESSIONAL_ID: Documents issued by professional boards or regulatory bodies (e.g., OAB, CRM).
Last updated on by Henrique Scarabele