Social Assistance Beneficiaries - Status

Description

Polls the status of a previously initiated social assistance beneficiaries check. While the check is still processing, the response will contain status: "IN_PROGRESS". Once completed, the benefit data will be returned and the status field will be absent.

The Social Assistance Beneficiaries IDV Solution checks if the person being consulted is a beneficiary of government social and welfare benefits such as: Bolsa Família, Seguro Defeso and Benefício de Prestação Continuada (BPC).

Asynchronous Flow

This API uses an asynchronous two-step process:

1. Initiate the check — returns a ref ticket with status IN_PROGRESS (HTTP 202).
2. Poll for results — use the ref ticket to poll until the result is available (HTTP 200).

---

Step 2 — Poll for results

Use the ref value returned in Step 1 to poll this endpoint. While the check is still processing, the response will contain status: "IN_PROGRESS". Once completed, the benefit data will be returned and the status field will be absent.

HTTP method GET

Endpoint

https://api.msla-id.com/experience-idv-financial-api-v1/api/idv-govcheck/v1/br-identity/{CPF}/financial-info/status/{ref}

[SANDBOX Environment]

For testing purposes, use the base domain: apidev.msla-id.com

Request header parameter

NAME	REQUIRED	TYPE	DESCRIPTION
Authorization	✅	string	Bearer JWT token

URI request parameters

NAME	REQUIRED	TYPE	DESCRIPTION
CPF	✅	string	CPF number (digits only).
ref	✅	string	Reference ticket obtained from Step 1.

Status code responses

Code	Description
200	IN_PROGRESS (keep polling) or completed result
400	Bad request
401	Unauthorized
403	Forbidden
500	Internal server error

Response 200 status code — In Progress

{
  "ref": "06479633377-fi-a1b2c3d4",
  "status": "IN_PROGRESS"
}

Response 200 status code — Completed

{
    "traceId": "db38dabb541fe662",
    "timestamp": "2026-03-31 20:56:35",
    "data": {
        "ref": "06471456542-fi-eeb8f7fe",
        "status": "FINISHED",
        "bolsaFamilia": {
            "programName": "Bolsa Família",
            "registered": false
        },
        "seguroDefeso": {
            "programName": "Seguro Defeso",
            "registered": false
        },
        "beneficioPrestacaoContinuada": {
            "programName": "Benefício de Prestação Continuada",
            "registered": false
        }
    }
}

Response body fields — Benefit object

FIELD	TYPE	DESCRIPTION
registered	boolean	Whether the person is registered in this program.
program_name	string	Name of the social assistance program.
state	string	State abbreviation (UF).
municipality	string	Municipality name.
monthly_amount_brl	number	Monthly benefit amount in BRL.
last_benefit_date	string	Date of the last benefit received.
last_update_date	string	Date when this record was last updated.

Response 400 status code

{
    "traceId": "542fc743fffda052",
    "timestamp": "2023-05-05 11:20:46",
    "code": "IDV-3001",
    "message": "Bad request - Invalid or incomplete input data"
}

Response 500 status code

{
    "traceId": "43a20f33d4e8730d",
    "timestamp": "yyyy-mm-dd HH:MM:SS",
    "code": "IDV-1008",
    "message": "Error in the source of origin, please contact an administration."
}