Offline Balance Request

Instantly retrieves the most up-to-date saved data for a benefit.

Technical Advantages

Synchronous response — no processing queue or webhook wait;
Access to blocked benefits — returns the latest saved data in the system, even if the benefit is blocked;
Cached query — independent of Dataprev availability and does not consume API calls.

Request

ENDPOINT

/social_security/balance_request/offline

METHOD

GET

Query Params

document_numberstringrequiredBeneficiary CPF (numbers only, 11 digits).benefit_numberstringrequiredINSS benefit number.

GET /social_security/balance_request/offline?document_number=14950479032&benefit_number=22255220

Response

STATUS

200

Attributes

last_successful_balance_requestobject | nullLast successful balance request. null if there has never been a successful query.

Attributes of last_successful_balance_request:

consulted_atstringDate and time of the query (ISO 8601).dataobjectFull benefit data. Same structure as the balance request webhook. See field details.

last_blocked_statusobject | nullMost recent blocked status. null if no information is available. Automatically derived from the most recent source — whether a balance request, reservation attempt, or benefit check.

Attributes of last_blocked_status:

consulted_atstringDate and time of the most recent check (ISO 8601).statusstring"blocked" or "unblocked".

info

At least one of the two fields will be populated in a 200 response. If no data exists for the given combination, the endpoint returns 404.

{
    "last_successful_balance_request": {
        "consulted_at": "2025-01-15T14:32:10-03:00",
        "data": {
            "name": "NOME BENEFICIARIO",
            "state": "RS",
            "alimony": "not_payer",
            "birth_date": "18021978",
            "block_type": "not_blocked",
            "grant_date": "2006-05-22",
            "credit_type": "checking_account",
            "benefit_card": {
                "limit": 2259.20,
                "balance": 0
            },
            "benefit_number": "22255220",
            "benefit_status": "elegible",
            "payroll_card": {
                "limit": 2259.20,
                "balance": 0
            },
            "assistance_type": "retirement_invalidity_social_security",
            "document_number": "14950479032",
            "benefit_end_date": null,
            "consigned_credit": {
                "balance": 0
            },
            "benefit_situation": "active",
            "last_inquiry_date": "2018-06-18",
            "max_total_balance": 635.40,
            "used_total_balance": 635.40,
            "politically_exposed": {
                "type": "not_politically_exposed",
                "is_politically_exposed": false
            },
            "has_power_of_attorney": false,
            "available_total_balance": 0,
            "has_judicial_concession": false,
            "number_of_portabilities": 0,
            "disbursement_bank_account": {
                "bank_code": "748",
                "account_digit": "4",
                "account_branch": "0155",
                "account_number": "000070963"
            },
            "has_entity_representation": false,
            "social_benefit_max_balance": 635.40,
            "social_benefit_used_balance": 635.40,
            "benefit_quota_expiration_date": null,
            "number_of_active_reservations": 3,
            "number_of_suspended_reservations": 0,
            "number_of_refinanced_reservations": 0,
            "number_of_active_suspended_reservations": 3
        }
    },
    "last_blocked_status": {
        "consulted_at": "2025-01-15T14:32:10-03:00",
        "status": "unblocked"
    }
}

Data fields

namestringBeneficiary name.document_numberstringBeneficiary CPF.benefit_numberstringINSS benefit number.benefit_statusstringBenefit status (elegible, inelegible).block_typestringBlock type (not_blocked, blocked_by_tbm, etc.).benefit_situationstringBenefit situation (active, inactive, etc.).assistance_typestringAssistance/retirement type.available_total_balancenumberTotal available balance for consignment.consigned_creditobjectConsigned credit balance (balance).payroll_cardobjectPayroll card (balance, limit).benefit_cardobjectBenefit card (balance, limit).number_of_active_reservationsintegerNumber of active reservations.disbursement_bank_accountobjectDisbursement bank account details (bank_code, account_digit, account_branch, account_number).

Response scenarios

Scenario	`last_successful_balance_request`	`last_blocked_status.status`
Only successful queries	Last query data	`"unblocked"`
Only blocked queries	`null`	`"blocked"`
Success followed by later block	Last query data	`"blocked"`
Block followed by success	Last query data	`"unblocked"`

Errors

HTTP Code	QI Code	Description
401/403	(standard)	Missing or invalid authentication headers
404	`SSC000101`	No data found for the given `document_number` + `benefit_number` combination

404 response example

{
    "title": "Offline Balance Not Found",
    "description": "No balance data found for document_number {document_number} and benefit_number {benefit_number}.",
    "translation": "Nenhum dado de saldo encontrado para document_number {document_number} e benefit_number {benefit_number}",
    "code": "SSC000101"
}