Objeto Natural Person

At the end of the registration process for a natural person on your platform, it is necessary to perform the fraud and KYC evaluation for that client. This must be done through the Natural Person endpoint. The data sent must be final and immutable, meaning no changes should be allowed to basic registration information such as CPF, Name, Date of Birth, and others after this process. This is crucial to ensure two main points:

Consistency of data in the Anti-Fraud database
Realistic risk assessment, preventing fraud at later stages of the operation

Natural Person Object Definition

Request Body

{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "client_category": "Premium User",
  "name": "John Sample",
  "document_number": "111.111.111-11",
  "birthdate": "1992-09-15",
  "gender": "male",
  "nationality": "BRA",
  "mother_name": "Maria Sample",
  "father_name": "John Sample",
  "monthly_income": 500000,
  "declared_assets": 7500000,
  "occupation": "Teacher",
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
    }
  ],
  "documents": {
    "rg": {
      "number": "4.366.477-8",
      "issuer": "II",
      "issuer_state": "PR",
      "issuance_date":"2002-01-12",
      "validation_type":"zaig_sdk",
      "ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
      "ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
    },
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "first_issuance_date":"2011-03-21",
      "issuance_date":"2016-06-29",
      "expiration_date":"2021-06-25",
      "category": "AB",
      "validation_type":"zaig_sdk",
      "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
    }
  },
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Bairro do Exemplo",
    "city": "Aparecida de Goiânia",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000",
    "country": "BRA",
    "validation_type":"visit",
    "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
  },
  "phones": [
    {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile",
      "validation_type": "zaig_sms",
      "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
    }
  ],
  "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"
  }
}

All information exchanges related to a registration use the following object definition. In some cases, to simplify implementation and reduce data flow between parties, certain information may be omitted.

name	type	constraints	description
id	string	1–50 characters	Analysis identifier. This number must be unique for each request (required)
registration_id	string	1–50 characters	Registration identifier in the client’s system. To perform more than one analysis for the same registration, use the same registration_id across different analyses. Defaults to the value of id if not provided.
registration_date	datetime	ISO 8601 with timezone	Date and time of registration. Format: `YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM` or `...Z`. Example: `2019-12-11T11:37:15.12-03:00` (required)
client_category	string	1–100 characters	Client category according to your platform’s classification or loyalty program
name	string	1–500 characters	Full name of the individual being registered
document_number	string	Format `XXX.XXX.XXX-XX`	CPF of the individual. Must be exactly 14 characters, including dots and hyphen (required)
birthdate	date	Format `YYYY-MM-DD`	Birthdate of the individual
gender	enum	`male` or `female`	Gender of the individual
nationality	string	3 uppercase letters	Nationality in ISO 3166-1 alpha-3 code. Example: `BRA`
mother_name	string	1–500 characters	Full name of the mother
father_name	string	1–500 characters	Full name of the father
monthly_income	integer	1 to 100,000,000,000	Gross monthly income in cents of BRL
declared_assets	integer	1 to 100,000,000,000,000	Declared assets in cents of BRL
occupation	string	1–100 characters	Occupation of the individual being registered
emails	List of Email	—	List of Email-type objects describing the individual’s email addresses
documents	Document	—	Objects of type CNH, RG and other identification documents
address	Address	—	Address-type object describing the individual’s residential address
phones	List of Phone	—	List of Phone-type objects containing the individual’s phone numbers
source	Source	—	Source-type object describing information from the application used to send the registration
face	Face	—	Face-type object describing facial validation data used during registration, if applicable

Field Formats

`registration_date`

Must follow ISO 8601 format with a mandatory timezone. Examples of accepted values:

2019-12-11T11:37:15-03:00        (no fractional seconds, offset)
2019-12-11T11:37:15.123456-03:00 (fractional seconds, up to 6 digits)
2019-12-11T14:37:15Z             (UTC)

The field does not accept dates without a timezone component (e.g., 2019-12-11T11:37:15 is invalid).

`document_number` — CPF

The CPF must be sent with punctuation, in the format XXX.XXX.XXX-XX, where each X is a numeric digit. The field is exactly 14 characters long.

Valid example: 123.456.789-09

`birthdate`

Date in YYYY-MM-DD format (year-month-day), per ISO 8601.

Valid example: 1992-09-15

`nationality`

A 3-letter uppercase country code following the ISO 3166-1 alpha-3 standard.

Examples: BRA (Brazil), USA (United States), ARG (Argentina).

`monthly_income` and `declared_assets`

Both fields are integers representing monetary values in cents of BRL. To convert from BRL to the expected format, multiply by 100.

Example: BRL 5,000.00 → 500000

Submit a Natural Person

Request Body

  {
    "id": "12345",
    ...
  }

Response Body

  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }

To evaluate a Registration, simply send a Natural Person–type object to the following endpoint with the flag set appropriately.

POST https://api.caas.qitech.app/onboarding/natural_person?analyze=true

The analyze parameter exists to indicate whether the submitted registration should be analyzed by QI Tech's algorithms. If a registration is sent with the parameter set to false, it will not be analyzed or charged, but its data will still be considered by QI Tech's algorithms for future analysis. The default value of this parameter is true, so only registrations explicitly sent with the false flag will not be analyzed.

Natural Person Object Definition​

Field Formats​

registration_date​

document_number — CPF​

birthdate​

nationality​

monthly_income and declared_assets​

Submit a Natural Person​