Legal Person Object
At the end of registering a company on your platform, it is necessary to perform the fraud and KYC assessment for this entity, which must be carried out through the Legal Person endpoint. The data submitted must be final and must not be changed under any circumstances. That is, after this process, it should not be possible to modify basic registration data such as CNPJ, Company Name, Incorporation Date, and others. This is very important to ensure two key points:
- Consistency of the data in the Anti-Fraud database
- Realistic risk assessment, avoiding fraud in future operations
Legal Person Object Definition
Request Body
{
"id": "12345678",
"registration_id": "12345678",
"registration_date": "2019-12-11T11:37:15.12-03:00",
"client_category" : "Premium Account",
"legal_name": "John's Company",
"trading_name": "John's Barbershop",
"document_number": "11.111.111/0001-11",
"foundation_date": "1992-09-15",
"website": "www.johnsbarbershop.com.br",
"activity": "Barber Shops",
"activity_code": "96.02-5-01",
"merchant_category_code": "0742",
"tier" : "epp",
"annual_revenues": 72000000,
"emails":[
{
"email": "johnsample@test.com",
"validation_type":"zaig_api",
"validation_key": "ccc4b4b4-f91c-4475-8290-07152550aefc"
}
],
"documents": {
"ie": {
"number": "388.108.598.269",
"issuer": "JUCESP",
"issuer_state": "SP",
"issuance_date":"2002-01-12",
"validation_type": "zaig_api",
"ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
},
"company_statute": {
"ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
}
},
"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": "82473dec-8e14-4570-997a-59652818c908"
}
],
"source": {
"channel": "app",
"platform": "android",
"ip":"201.6.142.66",
"session_id": "c90ad2df-7307-4f82-8938-1da81dff2be6"
},
"legal_representatives": [
{
"name": "Frederic Attorney",
"document_number": "111.111.111-11",
"birthdate": "1987-06-12",
"gender": "male",
"nationality": "BRA",
"mother_name": "Jackie Attorney Mother",
"occupation": "Accountant",
"emails":[
{
"email": "frederic@attorney.com",
"validation_type":"zaig_api",
"validation_key": "d174d522-6003-4b05-adb2-e92e92632c67"
}
],
"documents": {
"letter_of_attorney": {
"ocr_key": "6972894d-d2ef-4b5f-b54f-10f178bf3e5d"
},
"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": "Avenida de Exemplo",
"number": "99",
"neighborhood": "Vila do Exemplo",
"city": "Jundiaí",
"uf": "SP",
"complement": "Ap 82",
"postal_code": "00000-000",
"country": "BRA",
"validation_type":"visit",
"ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "999998877",
"type": "mobile",
"validation_type": "zaig_sms",
"validation_key": "e390d2b3-cb71-4991-9d94-1b7f8b43a04e"
}
],
"source": {
"channel": "app",
"platform": "ios",
"ip":"175.92.122.2",
"session_id": "93c68588-7a41-472f-95b3-835ea6ee1ede"
},
"face":
{
"type":"zaig_sdk",
"registration_key":"d2677a8c-d575-44e1-a54d-ec00f9310f34"
}
}
],
"partners": [
{
"name": "John Partner",
"document_number": "111.111.111-11",
"birthdate": "1992-09-15",
"gender": "male",
"nationality": "BRA",
"mother_name": "Maria Partner's Mother",
"occupation": "Teacher",
"emails":[
{
"email": "johnsample@test.com",
"validation_type":"zaig_api",
"validation_key": "1fac6f8c-1a16-4a12-9afc-9a2d9ae0a31e"
}
],
"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": "d1713959-4ae4-4180-befc-6931c658e908"
}
],
"source": {
"channel": "app",
"platform": "android",
"ip":"255.201.26.1",
"session_id": "79d5e442-2cb7-4a9e-82c5-7fa3717d7ada"
},
"face":
{
"type":"zaig_sdk",
"registration_key":"a2b6ae92-1394-4f9b-b8ee-5be188f93609"
}
}
]
}
All data exchanges involving a registration use the following definition for this object. In some cases, to simplify implementation and reduce the data flow between parties, some 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 | Identifier of the registration in the client’s system. To perform more than one analysis for the same registration, use the same registration_id in different analyses. Defaults to the value of id when 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 classification or loyalty program |
| legal_name | string | 1–1000 characters | Corporate name of the company being registered |
| trading_name | string | 1–1000 characters | Trade name of the company being registered |
| document_number | string | Format XX.XXX.XXX/XXXX-XX | CNPJ of the company. Must be exactly 18 characters, including dots, slash and hyphen (required) |
| foundation_date | date | Format YYYY-MM-DD | Company foundation date |
| website | string | up to 10,000 characters | Website of the company being registered |
| activity | string | 1–1000 characters | Business sector of the company being registered |
| activity_code | string | Format XX.XX-X-XX | CNAE code of the company’s activity. Must be exactly 10 characters. Example: 96.02-5-01 |
| merchant_category_code | string | enum (see list) | MCC (Merchant Category Code) for the activity sector according to card network standards |
| tier | string | 1–10 characters | Company size (e.g.: mei, epp, me, medio, grande) |
| annual_revenues | integer | 0 to 10,000,000,000,000 | Company’s gross annual revenue in cents of BRL |
| monthly_revenues | integer | 0 to 10,000,000,000,000 | Company’s gross monthly revenue in cents of BRL |
| emails | List of Email | — | List of Email objects describing the company’s email addresses |
| documents | Document | — | Document objects (State registration - ie, Articles of incorporation - company_statute) |
| address | Address | — | Address object describing the company’s address |
| phones | List of Phone | — | List of Phone objects describing the company’s phone numbers |
| source | Source | — | Source object describing the characteristics of the application used to send the registration |
| partners | List of Partner | — | List of Partner objects describing information about each of the company’s partners |
| legal_representatives | List of LegalRepresentative | — | List of LegalRepresentative objects describing information about each of the company’s legal representatives |
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:15is invalid).
document_number — CNPJ
The CNPJ must be sent with punctuation, in the format XX.XXX.XXX/XXXX-XX, where each X is a numeric digit. The field is exactly 18 characters long.
Valid example: 11.222.333/0001-81
foundation_date
Date in YYYY-MM-DD format (year-month-day), per ISO 8601.
Valid example: 1992-09-15
activity_code — CNAE
The CNAE code must be sent in the format XX.XX-X-XX, with exactly 10 characters including separators.
Valid example: 96.02-5-01
annual_revenues and monthly_revenues
Both fields are integers representing monetary values in cents of BRL. To convert from BRL to the expected format, multiply by 100.
Example: BRL 720,000.00 → 72000000
Submit a Legal Person
Request Body
{
"id": "12345",
...
}
Response Body
{
"id": "12345",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
To perform the evaluation of a Registration, simply send an object of type Legal Person to the following endpoint with the flag properly set:
POST https://api.caas.qitech.app/onboarding/legal_person?analyze=true
The analyze parameter is used to determine 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 evaluations. The default value for this parameter is true, meaning that only registrations explicitly sent with the false flag will not be analyzed.