Integrating SDK data

QI Tech's SDKs (facial biometrics, document OCR and Device Scan) do not send data directly to the registration analysis. Each one returns a key to your backend, and it is up to you to attach those keys to the onboarding payload.

This page covers where each key goes — which differs between Natural Person and Legal Person.

Block	What it carries	Source of the key
`face`	Facial biometrics	Biometrics SDK
`documents`	Document OCR	OCR SDK/API
`source`	Device and session data	Device Scan SDK

The difference that causes the most rework

In Natural Person, all three blocks are at the root of the payload.

In Legal Person, face and identity documents go inside legal_representatives[] — but source stays at the root. Details in Legal Person.

Where each block goes

Block	Natural Person	Legal Person
`source` (`session_id`)	Root	Root — required for it to show on the dashboard
`face`	Root	Inside `legal_representatives[]`
`documents` (RG, CNH, passport)	Root	Inside `legal_representatives[]`
`documents` (`ie`, `company_statute`, `proof_of_address`)	—	Root

`source` — Device Scan and `session_id`

The session_id is the key returned by the Device Scan SDK. It is what connects the registration analysis to the device, geolocation and behavior data collected in the app or on the website.

session_idstringoptional — but see the warningSession identifier generated by the Device Scan SDK. 1 to 500 characters.channelstringoptionalChannel the registration originated from. E.g.: app, web, backoffice. 1 to 100 characters.platformstringoptionalPlatform. E.g.: android, ios, web. 1 to 100 characters.ipstringoptionalSource IP. Accepts IPv4 and IPv6. A malformed value returns HTTP 400.os_versionstringoptionalOperating system version. 1 to 100 characters.gps_dataobjectoptionalCoordinates of the capture.

gps_data fields:

latnumberoptionalLatitude, between -90 and 90.lonnumberoptionalLongitude, between -180 and 180.

source — always at the root, Natural Person and Legal Person
{
  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
    "os_version": "14",
    "gps_data": {
      "lat": -23.5613,
      "lon": -46.6565
    }
  }
}

Legal Person: session_id must be at the root

In Legal Person, source.session_id must be in the source object at the root of the payload — not inside legal_representatives[].

If this field is not filled in at the root, the device data does not show up on the Legal Person registration analysis dashboard. The schema accepts source inside legal_representatives[], but that is not where the Legal Person dashboard reads the session from — putting it only there causes the data to be silently ignored in the analysis.

`face` — facial biometrics

typeenumoptionalHow the biometrics were captured. It defines which of the fields below you must fill in.registration_keystringoptionalKey returned by the biometrics SDK. Use it with type: "zaig_sdk". UUID format.imagestringoptionalBase64 image. Use it with type: "base_64" when no SDK is involved.

`type` values

Value	Field to fill in
`zaig_sdk`	`registration_key`
`base_64`	`image`

face via SDK
{
  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
}

face via Base64
{
  "face": {
    "type": "base_64",
    "image": "iVBORw0KGgoAAAANSUhEUg..."
  }
}

`documents` — OCR

The OCR keys (ocr_key, ocr_front_key, ocr_back_key) come from the OCR SDK/API and go inside the corresponding document.

Documents accepted in Natural Person

At the root of the Natural Person payload, documents accepts:

Field	What it is	Accepted keys
`rg`	Brazilian ID card (Registro Geral)	`ocr_front_key`, `ocr_back_key`, `ocr_key`
`cnh`	Brazilian driver's license	`ocr_key`, `ocr_front_key`, `ocr_back_key`
`passport`	Passport	`ocr_key` (required)
`ctps`	Work permit (Carteira de Trabalho)	`ocr_front_key` and `ocr_back_key` (both required)
`cin_digital`	Digital national ID card	`ocr_key`
`national_registry_of_foreigners`	RNE — National Registry of Foreigners	`ocr_key`, `ocr_front_key`, `ocr_back_key`
`national_migration_registry`	RNM — National Migration Registry	`ocr_key`, `ocr_front_key`, `ocr_back_key`
`class_entity_registry`	Professional association card (OAB, CRM…)	`ocr_key` (required)
`military_registry`	Military document	`ocr_key` (required)
`letter_of_emancipation`	Letter of emancipation	`ocr_key` (required)
`company_statute`	Articles of association / bylaws	`ocr_key`, `document_analysis_id`
`proof_of_address`	Proof of address	`document_analysis_id`
`others`	Other documents	`ocr_front_key` and `ocr_back_key` (both required)

Documents accepted in Legal Person

At the root of the Legal Person payload, documents accepts only company documents:

Field	What it is	Accepted keys
`ie`	State registration (inscrição estadual)	`ocr_key` — requires the `number` field
`company_statute`	Articles of association / bylaws	`ocr_key`, `document_analysis_id`
`proof_of_address`	Proof of address	`document_analysis_id`

RG and CNH do not exist at the root of Legal Person

Identity documents (rg, cnh, passport…) are not accepted at the root of the Legal Person payload — the schema uses additionalProperties: false and the request returns HTTP 400.

They belong to the legal representative, inside legal_representatives[].

OCR keys per document

The accepted keys per document are in the tables above. Worth highlighting:

Front and back: for two-sided documents (rg, ctps, others), the standard is to send ocr_front_key and ocr_back_key. In ctps and others both are required.
Single key: when the OCR returns a single key for the whole document, use ocr_key.
document_analysis_id: used in company_statute and proof_of_address, which go through Document Analysis rather than identity OCR.

In rg and cnh, the issuer_state field accepts state abbreviations in uppercase or lowercase.

documents with OCR keys (Natural Person)
{
  "documents": {
    "rg": {
      "number": "4.366.477-8",
      "issuer": "SSP",
      "issuer_state": "PR",
      "issuance_date": "2002-01-12",
      "ocr_front_key": "a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
      "ocr_back_key": "b6df0d9e-3f77-45a1-b8ec-9b6cd81d2c87"
    },
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "first_issuance_date": "2011-03-21",
      "issuance_date": "2016-06-29",
      "expiration_date": "2031-06-25",
      "category": "AB",
      "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
    }
  }
}

Natural Person

All three blocks are at the root:

POST /onboarding/natural_person
{
  "id": "12345678",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "111.111.111-11",
  "name": "John Sample",

  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },

  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  },

  "documents": {
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
    }
  }
}

Legal Person

source at the root; face and identity documents inside legal_representatives[]:

POST /onboarding/legal_person
{
  "id": "87654321",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "11.111.111/1111-11",
  "legal_name": "Empresa Exemplo LTDA",

  "source": {
    "channel": "web",
    "platform": "web",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },

  "documents": {
    "company_statute": {
      "ocr_key": "d8fa2fb0-5199-47c3-daae-bd8ef03f4ea9"
    },
    "proof_of_address": {
      "document_analysis_id": "e9ab3ac1-62aa-48d4-ebbf-ce9fa14a5fb0"
    }
  },

  "legal_representatives": [
    {
      "id": "rep-001",
      "name": "Maria Sample",
      "document_number": "222.222.222-22",
      "birthdate": "1985-03-22",

      "face": {
        "type": "zaig_sdk",
        "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
      },

      "documents": {
        "cnh": {
          "register_number": "05163811694",
          "issuer_state": "SP",
          "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
        }
      }
    }
  ]
}

Why the biometrics live in the representative

Biometrics and the identity document belong to a person, not to the company. In a Legal Person, the one who goes through biometric validation is the legal representative — that is why face and identity documents live inside legal_representatives[].

Device data, on the other hand, belongs to the session in which the registration was made, which is unique for the whole request — that is why source stays at the root.

Common errors

Symptom	Cause	Fix
Device data does not show up on the Legal Person dashboard	`session_id` missing at the root, or sent only inside `legal_representatives[]`	Fill in `source.session_id` at the root of the payload
HTTP 400 when sending `rg`/`cnh` in Legal Person	Identity document at the root of Legal Person	Move it to `legal_representatives[].documents`
HTTP 400 on `passport`	Object sent without `ocr_key`	`ocr_key` is required in `passport`
HTTP 400 on `source.ip`	Malformed IP	Send a valid IPv4 or IPv6
HTTP 400 with no obvious field	Field outside the schema (`additionalProperties: false`)	Check the `description` in the response

Checklist

source.session_id at the root, both in Natural Person and in Legal Person.
In Legal Person, confirmed that the device data shows up on the registration analysis dashboard.
In Legal Person, face and identity documents inside legal_representatives[].
In Legal Person, only ie, company_statute and proof_of_address at the root of documents.
passport, when sent, with ocr_key.

Integrating SDK data

Where each block goes​

source — Device Scan and session_id​

face — facial biometrics​

type values​

documents — OCR​

Documents accepted in Natural Person​

Documents accepted in Legal Person​

OCR keys per document​

Natural Person​

Legal Person​

Common errors​

Checklist​