Lending Analysis

Preliminary version

This is the first version of the Lending Analysis documentation and may undergo minor changes. We recommend following this page for future updates.

The Lending Analysis endpoint allows you to perform a complete credit analysis for a borrower, combining onboarding, credit analysis, and private payroll worker data inquiry in a single request.

The operation is asynchronous: when you send the request, the API returns a synchronous response with the status pending_inquiry. The final analysis result is delivered via webhook when processing is completed.

Flow

The client sends a POST to /lending_analysis with the borrower data and desired inquiries.
The API returns a synchronous response with the lending_analysis_key and status pending_inquiry.
When processing is complete, the API sends a webhook with the full analysis result.

Available endpoints

In addition to the POST /lending_analysis described below, the API exposes two auxiliary inquiries:

Eligibility check — GET /lending_analysis to verify whether the borrower already has an active analysis before creating a new one.
Analysis status inquiry — GET /lending_analysis/{lending_analysis_key} to track the analysis state via polling, as an alternative to the webhook.

Request

ENDPOINT

/lending_analysis

METHOD

POST

Request Body

{
    "request_identifier_key": "12345678901",
    "document_number": "46276658812",
    "lending_analysis_type": "private_payroll",
    "purchaser_document_number": "12345678000199",
    "private_payroll": {
        "employer_document_number": "12345678000199",
        "registration_number": "12345678901"
    },
    "authorization_term": {
        "legal_representative_document_number": "98765432100",
        "signature": {
            "signer": {
                "document_number": "46276658812",
                "name": "João da Silva",
                "email": "joao.silva@email.com",
                "phone": {
                    "number": "912345678",
                    "area_code": "11",
                    "country_code": "55"
                }
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2026-03-12T10:00:00Z",
                "ip_address": "192.168.1.100",
                "fingerprint": {},
                "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            }
        }
    },
    "analysis_data": {
        "name": "João da Silva"
    }
}

Body Params

Field	Type	Description	Characters
`request_identifier_key`	string	Idempotent request key. Must be unique per analysis.	-
`document_number`	string	Borrower's CPF (digits only).	11
`lending_analysis_type`	string	Credit analysis type.	Lending Analysis Type Enumerators
`purchaser_document_number`	string	Purchaser/assignee CNPJ. (optional)	14
`private_payroll`	object	Borrower's private payroll data.	Private Payroll Object
`authorization_term`	object	Borrower's authorization term.	Authorization Term Object
`analysis_data`	object	Additional borrower data for the analysis.	Analysis Data Object

Private Payroll Object

Field	Type	Description	Characters
`employer_document_number`	string	Employer's CNPJ.	14
`registration_number`	string	Worker's registration number.	-

Authorization Term Object

Attention

When there is a legal representative, you must fill in the legal_representative_document_number field with the representative's CPF, and the signer object data must be filled with the representative's information.

For more information about the authorization_term object, see the official documentation: Worker Inquiries - Worker Data Inquiry

Field	Type	Description	Characters
`legal_representative_document_number`	string	Legal representative's CPF (required only when there is a legal representative).	11
`signature.signer.document_number`	string	Signer's CPF.	11
`signature.signer.name`	string	Signer's name.	-
`signature.signer.email`	string	Signer's email. (optional)	-
`signature.signer.phone.number`	string	Signer's phone number. (optional)	-
`signature.signer.phone.area_code`	string	Signer's area code. (optional)	2
`signature.signer.phone.country_code`	string	Country code (e.g., `"55"`). (optional)	3
`signature.authentication_type`	string	Authentication type. Must be `"opt_in"`.	-
`signature.authenticity.timestamp`	string	Consent date and time (ISO 8601 format: `2026-03-12T10:00:00Z`).	-
`signature.authenticity.ip_address`	string	User session IP (IPv4 or IPv6).	-
`signature.authenticity.fingerprint`	object	Additional traceability evidence (can be an empty object `{}`).	-
`signature.authenticity.session_id`	string	User session identifier (min. 10, max. 50 characters).	50

Analysis Data Object

Field	Type	Description	Characters
`name`	string	Borrower's name. (optional)	-

Response

STATUS

202

Response Body

{
    "analysis_status": "pending_inquiry",
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
}

Field	Type	Description
`analysis_status`	string	Current analysis status. Returns `pending_inquiry` in the synchronous response.
`lending_analysis_key`	string	Analysis UUID key, used to correlate with the webhook.

STATUS

400

Response Body

{
    "title": "Bad Request",
    "description": "Invalid or missing required fields in the request body. Check 'document_number', 'lending_analysis_type', 'private_payroll', and 'authorization_term'.",
    "translation": "Campos obrigatórios ausentes ou inválidos no corpo da requisição. Verifique 'document_number', 'lending_analysis_type', 'private_payroll' e 'authorization_term'.",
    "extra_fields": {},
    "code": "LAS000001"
}

STATUS

409

Returned when the request_identifier_key field has already been used in a previous request.

Response Body

{
    "title": "Conflict",
    "description": "A lending analysis with the provided 'request_identifier_key' already exists. Each analysis must use a unique identifier.",
    "translation": "Já existe uma análise de crédito com o 'request_identifier_key' informado. Cada análise deve utilizar um identificador único.",
    "extra_fields": {
        "existing_lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
    },
    "code": "LAS000002"
}

Eligibility check

Verifies whether the borrower has an active (non-expired) analysis for a given product. If none exists, indicates that a new analysis can be created with POST /lending_analysis.

ENDPOINT

/lending_analysis

METHOD

GET

Query Params

Field	Type	Description	Characters
`document_number`	string	Borrower's CPF (digits only).	11
`product_name`	string	Product name. Currently the only accepted value is `private_payroll`.	-
`purchaser_document_number`	string	Purchaser/assignee CNPJ. (optional)	14

Example call

GET /lending_analysis?document_number=46276658812&product_name=private_payroll

Response — Borrower with an active analysis

STATUS

200

Response Body

{
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "analysis_status": "approved",
    "expires_at": "2026-03-17T10:00:00Z"
}

Field	Type	Description
`lending_analysis_key`	string	UUID of the borrower's active analysis.
`analysis_status`	string	Current analysis status. See Analysis Status.
`expires_at`	string	Date and time (ISO 8601) when the analysis expires. After this date, the borrower becomes eligible for a new analysis.

Response — Borrower without an active analysis

STATUS

404

Returned when no active analysis exists for the borrower under the provided combination. The client may proceed with POST /lending_analysis to start a new analysis (provided an active AnalysisConfiguration exists for the same requester_key, product, and purchaser_document_number).

Response Body

{
    "code": "LAS000009",
    "title": "No active lending analysis found",
    "description": "No active lending analysis found for product_name=<X>, purchaser_document_number=<Y>. The borrower has no active analysis for the given product.",
    "translation": "Nenhuma analise de credito ativa encontrada para product_name=<X>, purchaser_document_number=<Y>. O tomador nao possui analise ativa para o produto informado."
}

Fires when no Analysis exists for the tuple (requester_key, product_name, document_number, purchaser_document_number) that is non-failed and still within its validity period (expires_at in the future).

Analysis status inquiry

Returns the full state of a specific analysis, including the status transition history, individual steps executed, and data from the inquiries (inquiries) performed. Useful when the client prefers polling instead of relying solely on the completion webhook.

ENDPOINT

/lending_analysis/{lending_analysis_key}

METHOD

GET

Path Params

Field	Type	Description
`lending_analysis_key`	string	Analysis UUID, returned by `POST /lending_analysis` upon creation.

Example call

GET /lending_analysis/06666318-c9e9-416b-ae2f-460355a3d8e8

Response

STATUS

200

Response Body

{
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "analysis_status": "approved",
    "expires_at": "2026-03-17T10:00:00Z",
    "request_identifier_key": "12345678901",
    "document_number": "46276658812",
    "additional_data": {
        "private_payroll": {
            "employer_document_number": "12345678000199",
            "registration_number": "12345678901"
        },
        "analysis_data": {
            "name": "João da Silva"
        }
    },
    "status_events": [
        {
            "status": "pending_inquiry",
            "created_at": "2026-03-12T10:00:00Z"
        },
        {
            "status": "approved",
            "created_at": "2026-03-12T10:05:00Z"
        }
    ],
    "inquiries": [
        {
            "inquiry_key": "0a1b2c3d-e5f6-7890-abcd-ef1234567890",
            "inquiry_type": "private_payroll",
            "inquiry_status": "success",
            "inquiry_data": {}
        }
    ],
    "steps": [
        {
            "analysis_step_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
            "order": 1,
            "step_type": "onboarding_natural_person",
            "step_status": "approved"
        },
        {
            "analysis_step_key": "a9b8c7d6-e5f4-3210-abcd-ef1234567890",
            "order": 2,
            "step_type": "credit_analysis_natural_person",
            "step_status": "approved"
        }
    ]
}

Top-level fields

Field	Type	Description
`lending_analysis_key`	string	Analysis UUID.
`analysis_status`	string	Current analysis status. See Analysis Status.
`expires_at`	string	Analysis expiration date and time (ISO 8601).
`request_identifier_key`	string	Idempotency key supplied in the original request.
`document_number`	string	Borrower's CPF.
`additional_data`	object	Original data submitted to `POST /lending_analysis` (`private_payroll`, `authorization_term`, `analysis_data`).
`status_events`	array	Status transition history. Status Events Object
`inquiries`	array	Inquiries performed during the analysis. Inquiries Object (response)
`steps`	array	Individual steps executed. Steps Object

Status Events Object

Each item records a status transition with its timestamp, in chronological order.

Field	Type	Description
`status`	string	Status assumed by the analysis at this transition. See Analysis Status.
`created_at`	string	Transition date and time (ISO 8601).

Inquiries Object (response)

Field	Type	Description
`inquiry_key`	string	Inquiry UUID.
`inquiry_type`	string	Inquiry type. Currently the only value is `private_payroll`.
`inquiry_status`	string	Inquiry status: `pending`, `success`, or `failed`.
`inquiry_data`	object	Data returned by the inquiry. For `private_payroll`, follows the same format displayed in the webhook — see Inquiry data (`inquiry_data`).
`failure_reason`	string	Failure reason when `inquiry_status` is `failed`. (optional)

Steps Object

Each step represents an individual analysis (onboarding, credit analysis) executed during processing.

Field	Type	Description
`analysis_step_key`	string	Step UUID.
`order`	integer	Step execution order (1, 2, ...).
`step_type`	string	Step type: `onboarding_natural_person` or `credit_analysis_natural_person`.
`step_status`	string	Current step status: `created`, `pending`, `approved`, `reproved`, or `failed`.

STATUS

404

Returned when the provided lending_analysis_key does not match any existing analysis.

Response Body

{
    "title": "Not Found",
    "description": "Lending analysis with the provided key was not found.",
    "translation": "Não foi encontrada uma análise de crédito com a chave informada.",
    "extra_fields": {},
    "code": "LAS000005"
}

Webhooks

Attention!

QI Tech webhooks should not be strictly mapped. Additional fields may be included in the returned webhook payloads.

Webhook type: laas.lending_analysis.status_change

The webhook is sent to the URL configured in the client's environment when the analysis is completed.

Completed analysis webhook

Response Body

{
    "key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "12345678901",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding_natural_person",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis_natural_person",
                "analysis_step_status": "reproved",
                "reason": "Score do Serasa menor que 500",
                "output_data": {
                    "analysis_score": 100,
                    "credit_model_score": 100,
                    "maximum_monthly_interest_rate": 0.00,
                    "minimum_monthly_interest_rate": 0.00,
                    "maximum_installments_number": 10,
                    "minimum_installments_number": 1,
                    "maximum_disbursed_issue_amount": 4500.00,
                    "minimum_disbursed_issue_amount": 0.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_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",
                    "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"
                    },
                    "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 field descriptions

Field	Type	Description
`key`	string	`lending_analysis_key` returned in the synchronous response.
`status`	string	Webhook status.
`webhook_type`	string	Webhook type.
`event_datetime`	string	Event date and time (ISO 8601).
`data.request_identifier_key`	string	Idempotent key provided in the original request.
`data.analysis_status`	string	Final analysis status. Analysis Status
`data.analysis_steps`	array	List of analysis steps performed. Analysis Steps Object
`data.inquiries`	array	Data returned from performed inquiries. See Inquiry data (inquiry_data) section.

Analysis Steps Object

Field	Type	Description
`analysis_step_type`	string	Step type. Individual Analysis Types
`analysis_step_status`	string	Individual step status (`approved` or `reproved`).
`reason`	string	Approval or rejection reason, defined by client rules.
`output_data`	object	Step-specific output data.

`output_data` for `credit_analysis`

Important

All output_data fields are configurable in the analysis rules. If a rule is not configured to return a specific field, it will be returned empty or not be present in the payload.

Field	Type	Description
`analysis_score`	number	Credit analysis score.
`credit_model_score`	number	Credit model score.
`maximum_monthly_interest_rate`	number	Maximum monthly interest rate.
`minimum_monthly_interest_rate`	number	Minimum monthly interest rate.
`maximum_installments_number`	number	Maximum number of installments.
`minimum_installments_number`	number	Minimum number of installments.
`maximum_disbursed_issue_amount`	number	Maximum disbursement amount.
`minimum_disbursed_issue_amount`	number	Minimum disbursement amount.

Inquiry data (`inquiry_data`)

The inquiries array in the webhook contains data returned from the inquiries performed during the analysis. Each item has the fields inquiry_type (inquiry type) and inquiry_data (returned data).

For the private_payroll type, the inquiry_data object follows the same response format as the Worker data inquiry from the private payroll module, including personal data, consignable margin, employment bond history, active loans, and alerts.

The full documentation of inquiry_data fields, enumerators, and response examples is available at:

Worker Inquiries — 2. Worker data inquiry

Enumerators