Private Payroll Manual - Worker Inquiries
- Issuance Flow (previous)
- Issuance and Formalization (next)
At the beginning of the active flow for issuing a private payroll debt, it is necessary to perform two main inquiries related to the worker:
-
Employment relationships inquiry: performed by providing only the worker's CPF. This operation returns the list of the worker's active relationships, along with the eligibility of each one for credit operations.
-
Worker data inquiry: performed based on a specific relationship, providing the employer's document number and registration number obtained from the employment relationships inquiry. This operation returns detailed additional information about the selected relationship, including personal data, consignable margin, relationship history, and any alerts.
To perform any of these inquiries, it is mandatory to send an Authorization term. This term must be created from the collection of evidence that the borrower provided express consent (opt-in) authorizing the execution of the inquiries. The evidence — such as timestamp, IP address, and session identifier — must be included in the request to ensure traceability and regulatory compliance of the process.
These inquiries, along with the Authorization term, are fundamental steps to validate the worker's eligibility and obtain the necessary data before formalizing the credit operation.
QI Tech webhooks should not be strictly mapped. Additional fields may be included in the webhook payloads returned by our APIs.
You can consult and resend webhooks by following the detailed instructions in the documentation: Webhook Resending.
1 - Worker employment relationships inquiry:
The employment relationships inquiry is an asynchronous operation. When sending the request, QI Tech will process the inquiry in the background and return the result through a webhook when completed.
The webhook will be sent to the URL configured in your environment.
Request
Case 1: The worker is the signer of the Authorization term.
Request Body
{
"document_number": "12345678909",
"authorization_term": {
"signature": {
"signer": {
"name": "Nome do tomador",
"email": "email_do_tomador@email.com",
"phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
},
"document_number": "12345678909"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "2025-03-24T12:19:08Z",
"ip_address": "255.255.255.255",
"fingerprint": {},
"session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2"
}
}
}
}
Case 2: The legal representative is the signer of the Authorization term.
Request Body
{
"document_number": "12345678909",
"authorization_term": {
"legal_representative_document_number": "32165498709",
"signature": {
"signer": {
"name": "Nome do tomador",
"email": "email_do_tomador@email.com",
"phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
},
"document_number": "12345678909"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "2025-03-24T12:19:08Z",
"ip_address": "255.255.255.255",
"fingerprint": {},
"session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2"
}
}
}
}
In cases where there is a legal representative, it is necessary to fill the "legal_representative_document_number" field with the legal representative's CPF, and the "signer" object data must be filled with the same person's data.
Response
Response Body
{
"employment_relationships_inquiry_key": "<UUID>",
"employment_relationships_inquiry_status": "pending_inquiry"
}
The possible values for the employment_relationships_inquiry_status enumerator are listed in the section Employment relationships inquiry status.
Webhooks
Employment relationships inquiry result:
Webhook Body
{
"key": "<Employment Relationships Inquiry Key>",
"status": "completed",
"webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
"event_datetime": "2025-03-24T15:28:31Z",
"data": {
"authorization_term": {
"status": "authorized",
"authorization_term_key": "<UUID>",
"signed_at": "2025-03-24T12:19:08Z",
"expiration_date": "2025-04-24"
},
"employment_relationships": [
{
"eligible": true,
"document_number": "47812365409",
"registration_number": "99999999999-A",
"employer_document_type": "cpf",
"employer_document_number": "34848037034"
},
{
"eligible": false,
"document_number": "47812365409",
"registration_number": "11111111111-B",
"employer_document_type": "cnpj",
"employer_document_number": "33296860000173"
}
]
}
}
Webhook Body
{
"key": "<Employment Relationships Inquiry Key>",
"status": "failed",
"webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
"event_datetime": "2025-03-24T15:28:31Z",
"data": {
"enumerator": "ineligible_worker_cpf",
"description": "CPF not found in database or worker CPF ineligible",
"translation": "CPF não encontrado na base ou CPF do trabalhador inelegível"
}
}
To simulate a failure in sandbox environment, perform an inquiry with a CPF starting with digit 2.
2 - Worker data inquiry:
The worker data inquiry is an asynchronous operation. When sending the request, QI Tech will process the inquiry in the background and return the result through a webhook when completed.
The webhook will be sent to the URL configured in your environment.
There are two possible scenarios for performing the inquiry:
- Using an Authorization term previously sent in the employment relationships inquiry
- Sending a new Authorization term along with the inquiry
In both cases, it is necessary to provide the worker's registration number obtained from the employment relationships inquiry.
Request
Case 1: Worker data inquiry with previously sent Authorization term.
Request Body
{
"document_number": "<CPF FUNCIONÁRIO>",
"registration_number": "<NÚMERO DE MATRÍCULA>",
"employer_document_number": "<CNPJ EMPREGADOR>"
}
Case 2: Worker data inquiry with Authorization term sending.
Request Body
{
"document_number": "<CPF FUNCIONÁRIO>",
"registration_number": "<NÚMERO DE MATRÍCULA>",
"employer_document_number": "<CNPJ EMPREGADOR>",
"authorization_term": {
"legal_representative_document_number": "<CPF DO REPRESENTANTE LEGAL>", // Caso aplicável
"signature": {
"signer": {
"name": "<NOME DO ASSINANTE>",
"email": "<EMAIL DO ASSINANTE>",
"phone": {
"number": "<NUMERO DO ASSINANTE>",
"area_code": "<DDD DO ASSINANTE>",
"country_code": "55"
},
"document_number": "<CPF DO ASSINANTE>"
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "<DATA E HORA DA ASSINATURA>",
"ip_address": "<IP DO ASSINANTE>",
"fingerprint": {},
"session_id": "<ID DA SESSÃO DO ASSINANTE>"
}
}
}
}
In cases where there is a legal representative, it is necessary to fill the "legal_representative_document_number" field with the legal representative's CPF, and the "signer" object data must be filled with the same person's data.
Response
Response Body
{
"balance_inquiry_key": "<Balance Inquiry Key>",
"balance_inquiry_status": "pending_inquiry"
}
The possible values for the balance_inquiry_status enumerator are listed in the section Worker data inquiry status.
Webhooks
Worker data inquiry result:
Webhook Body
{
"key": "<Balance Inquiry Key>",
"status": "completed",
"webhook_type": "laas.private_payroll.balance_inquiry_status_change",
"event_datetime": "2024-02-21T14:30:25Z",
"data": {
"document_number": "99999999999",
"registration_number": "99999999999-A",
"employer_document_number": "99999999999962",
"name": "JOÃO SILVA",
"gender": "male",
"birth_date": "1985-07-20",
"worker_category_code": 101,
"eligible": true,
"available_margin_amount": 5000.00,
"base_margin_amount": 4500.00,
"total_due_amount": 8207.54,
"admission_date": "2020-03-15",
"termination_date": null,
"termination_reason_code": null,
"political_exposition": "not_exposed",
"suspended_loans_count": 2,
"block_type": "no_block",
"blocked_at": null,
"employer_name": "EMPRESA XYZ LTDA",
"mother_name": "MARIA DA SILVA",
"nationality": {
"code": 76,
"description": "BRASIL"
},
"occupation": {
"code": 724325,
"description": "SOLDADOR ELETRICO"
},
"economic_activity": {
"code": 2833000,
"description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA, PECAS E ACESSORIOS, EXCETO PARA IRRIGACAO"
},
"ineligibility_reason": "not_informed",
"employer_activity_start_date": "2010-05-12",
"legacy_loans": [],
"alerts": [
{
"alert_type": "leave",
"reference_date": "2025-02-11",
"event_id": 123456,
"leave_reason_code": 3,
"leave_start_date": "2025-02-11",
"leave_end_date": "2025-03-11"
},
{
"alert_type": "termination",
"reference_date": "2025-02-11",
"event_id": 789012,
"termination_reason_code": 1,
"termination_date": "2025-02-11",
"notice_period_start_date": "2025-01-11",
"notice_period_end_date": "2025-02-11"
}
]
}
}
Webhook Body
{
"key": "<Balance Inquiry Key>",
"status": "failed",
"webhook_type": "laas.private_payroll.balance_inquiry_status_change",
"event_datetime": "2024-02-21T14:30:25Z",
"data": {
"authorization_term": {
"status": "authorized",
"signed_at": "2025-08-10T17:42:05Z",
"expiration_date": "2025-09-09",
"authorization_term_key": "4444cc5b-9c60-473f-8fe4-6c43b855be6d"
}
}
}
Result in case of blocked employment relationship:
Webhook Body
{
"document_number": "99999999999",
"registration_number": "abc",
"employer_document_number": "12345678",
"block_type": "blocked_by_the_worker",
"blocked_at": "2025-12-11T10:00:00Z",
"data": {
"authorization_term": {
"status": "authorized",
"signed_at": "2025-08-10T17:42:05Z",
"expiration_date": "2025-09-09",
"authorization_term_key": "4444cc5b-9c60-473f-8fe4-6c43b855be6d"
}
}
}
To simulate a failure in sandbox environment, perform an inquiry with a CPF starting with digit 2.
Attachments
Authorization term object details
| Field | Requirement | Description |
|---|---|---|
| Name | Required | Borrower name |
| Optional | Borrower email | |
| Phone | Optional | Borrower phone |
| Document_number | Required | Borrower CPF |
| Authentication_type | Required | Mandatory "opt-in" |
| Timestamp | Required | Borrower consent timestamp, mandatory in format: 2025-08-04T23:45:30Z |
| Ip_address | Required | User session IP, either IPv4 (e.g.: 192.168.0.1) or IPv6 (e.g.: 2001:0db8:85a3:0000:0000:8a2e:0370:7334) |
| Fingerprint | Required | Object where additional evidence can be sent that contributes to the robustness of consent and assists in traceability, although required, can be sent as a null object |
| Session_id | Required | Internal identifier key of the user session, minimum length 10 and maximum 50 |
Examples of fingerprint object fields
{
"fingerprint_id": "4c188fc4-2cb4-48cc-9236-7df953570638",
"lat": "-15.82891",
"long": "-48.12751",
"name": "ALBERTO PEREIRA",
"device": "Web",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/037.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/037.36",
"browser_version": "120.0.0.0"
}
Worker data inquiry webhook details
| Field | Description |
|---|---|
| document_number | Borrower document |
| registration_number | Employment relationship registration number |
| employer_document_number | Employer document number (for CNPJ only the first 8 digits) |
| name | Borrower name |
| gender | Borrower gender |
| birth_date | Borrower birth date |
| worker_category_code | Worker category in compliance with the eSocial website |
| eligible | Relationship eligibility for payroll credit issuance |
| available_margin_amount | Consignable margin |
| base_margin_amount | Salary |
| total_due_amount | Borrower outstanding balance |
| admission_date | Admission date |
| termination_date | Termination date |
| termination_reason_code | Termination reason in compliance with the eSocial website |
| political_exposition | Borrower political exposure level, check possible enumerators in the Political exposure table |
| employer_name | Employer name |
| mother_name | Borrower mother's name |
| nationality.description | Borrower nationality |
| nationality.code | Borrower nationality code according to the numerical standard of part 1 of ISO 3166 norm |
| occupation.description | Borrower occupation according to the Brazilian Classification of Occupations (CBO) |
| occupation.code | Code according to CBO 2002 |
| economic_activity.description | Employer economic activity according to the National Classification of Economic Activities (CNAE) |
| economic_activity.code | Code according to CNAE Subclasses 2.3 |
| ineligibility_reason | Relationship ineligibility reason |
| employer_activity_start_date | Employer activity start date |
| legacy_loans | List of active loans reported by FIs, for field details check the Legacy loans object details table |
| alerts | List with history of leaves and termination warnings of the relationship, for field details check the Alerts object details table |
| suspended_loans_count | Number of suspended loans |
| block_type | Employment relationship blocking type, check possible enumerators in the Salary blocking table |
| blocked_at | Employment relationship blocking date |
Political exposure
| Enumerator | Description |
|---|---|
| not_exposed | Person not politically exposed |
| level_1 | Politically exposed person level 1 |
| level_2 | Politically exposed person level 2 |
| not_informed | No information about political exposure |
Alerts object details
| Field | Description |
|---|---|
| alert_type | Alert type, check possible enumerators in the Alert types table |
| reference_date | Event reference date |
| event_id | Event identifier |
| leave_reason_code | Leave reason in compliance with the eSocial website |
| leave_start_date | Leave start date |
| leave_end_date | Leave end date |
| termination_reason_code | Termination reason in compliance with the eSocial website |
| termination_date | Relationship termination date |
| notice_period_start_date | Notice period start date |
| notice_period_end_date | Notice period end date |
Alert types
| Enumerator | Description |
|---|---|
| leave | Leave |
| termination | Termination notice |
Legacy loans object details
| Field | Description |
|---|---|
| loan_amount | Disbursed amount |
| monthly_cet | Monthly CET |
| monthly_rate | Monthly rate |
| contract_type | Contract type, check possible enumerators in the Legacy contract types table |
| contract_number | Contract number |
| contract_end_date | Contract end date |
| paid_installments | Number of paid installments |
| total_installments | Total number of installments |
| installment_amount | Installment amount |
| contract_start_date | Contract start date |
| outstanding_balance | Outstanding balance |
| last_update_timestamp | Last update date |
| financial_institution_code | Code of the FI that reported the loan |
Legacy contract types
| Enumerator | Description |
|---|---|
| unsecured_non_consigned_loan | Unsecured non-payroll loan |
| loan_with_payroll_deductions | Loan with payroll deductions |
Employment relationships inquiry and worker data inquiry status
| Status | Description |
|---|---|
| pending_authorization | Authorization data was sent and is pending processing. |
| pending_inquiry | The inquiry is authorized and pending processing. |
| completed | The inquiry was successfully completed. |
| failed | The inquiry failed. |
Employment relationship blocking
| Enumerator | Description |
|---|---|
| no_block | Employment relationship not blocked |
| blocked_by_the_worker | Employment relationship blocked by the worker |