Extract Employment Information in Brazil (API)

So, want to get employment data about your users in Brazil? Well, you've come to the right place 😎

In this guide, we walk you through everything you need to extract employment data about your users using our API. This includes:

  • A general overview of the data flow
  • Generating your API keys
  • Providing a webhook URL (to receive events from Belvo)
  • Creating a link
  • Getting employment and owner information

📘

What data can I get about my users?

For a detailed list of data that our Employment Record API returns for your users, see our:

General flow of data

👍

Average time to retrieve employment data

The average time it takes for Belvo to retrieve employment data from an employment institution and send you a webhook event is 15 seconds. However, this can vary depending on the institution's responsiveness and their current request load.

Belvo uses asynchronous workflows to improve your data flow (check the diagram below).

Whenever you create a link, Belvo automatically extracts all the Employment data for you in the background, and once we have all the data, we notify you via a webhook that the data is ready to be retrieved (see the purple WEBHOOK sections in the diagram below). So that we can notify you once the data is ready, you need to provide a URL to where we can send events.

Employment Records Asynchronous Workflow

Employment Records Asynchronous Workflow

Generate API Keys

To use our API, you will need to generate some API keys to authenticate all your request.

To generate your API keys:

  1. Sign in to your Belvo Dashboard.
  2. Choose the Production environment to create your API keys.

    Note: Currently, employment data for Brazil is only supported in the production environment.

  3. Go to Developers -> API Keys.
  4. Click on Generate API Keys, which will automatically generate your API keys.
  5. In the pop-up, copy and securely save the values for Secret ID and Secret Password.
    Note: In the pop-up, you also have the option of forking Belvo's API collection. For more information on how to use Postman and Belvo's collection, see our Getting started in 10 minutes guide.

✳️ Done! You've just generated your API keys! But before you can start making API calls, you just need to set up a webhook where we can send events to.

Add a webhook URL

📘

Just testing out?

If you're just starting your integration and aren't sure how to get a URL for a webhook, you can use a service like Pipedream. Check out our Getting started in 10ish minutes to see how it's done!

To set up a new webhook:

  1. Sign in to your Belvo Dashboard.
  2. Choose the Production environment to receive webhook events.
  3. Go to Developers -> Webhooks.
  4. Click +New webhook.
  5. Fill in the New webhook form with the required information.
    1. URL: the URL to receive the webhook notifications.
    2. Authorization: an optional bearer token to use if your URL is protected.
  6. Click Create webhook.

✳️ Done! You've now created a webhook and can start creating links and receiving events!

Whitelisting Belvo IP addresses

Belvo will send events to your webhook URL from the IP addresses listed below. Your security team may want to add these to their list of IP addresses that they allow events from (otherwise, your system may block events from reaching your system).

  • 3.130.254.46
  • 18.220.61.186
  • 18.223.45.212

Create a link

👍

What's a link?

A link is Belvo's term for a connection between your user (CURP) and the employment institution (IMSS). Whenever you want to extract information from a new user, you'll need to create a link.

To create a link for INSS Brazil, you will need to make two API requests:

  1. POST Register a new link
  2. PATCH Complete a links request

POST Register a new link

The initial POST call will include the user's login information. However, INSS Brazil requires an MFA token to be entered in order to complete the login process. So, after you make the initial POST call, our API will respond with a 428 - Token Required with the link ID and session. You will need to ask your user to provide you the MFA token and then make a PATCH Complete a links request.

curl --location 'https://production.belvo.com/api/links/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD) \
--data '{see examples below}'
{
  "institution": "inss_br_employment",
  "username": "user_cpf",
  "password": "user_inss_password",
  "fetch_resources": ["EMPLOYMENTS","OWNERS"],
  "access_mode": "single",
  "external_id": "COHORT_32_User_6790023X5"
}
ParameterTypeRequiredDescriptionExample
institutionstringtrueThe institution where you want to create the link- inss_br_employment for Production
usernamestringtrueThe CPF of the individual.

Note: Belvo uses industry-standard AES-256 symmetric encryption to encrypt credentials.
07690251021
fetch_resourcesarraytrueThe resources you want Belvo to retrieve. For employment records in Mexico, you must send through at least EMPLOYMENT_RECORDS["EMPLOYMENTS","OWNERS"]
access_modestringtrueThe type of link to create. For employment data, we recommend using single links. For more information about a link's access_mode, see our dedication section here.single
external_idstringrecommendedYour internal reference for this user. This is extremely useful for you as you'll be able to relate the data that Belvo retrieves for this user in your system.COHORT_32_User_6790023X5
[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32", // Save this ID
        "expiry": "120",
        "link": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // Save this ID
        "token_generation_data": {
            "instructions": "Use your app or device to generate a token",
            "type": "inputless",
            "value": null,
          	"expects_user_input": true
        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1"
    }
]

Once you receive the 428 - Token Required response, you will need do the following:

  1. Ask your user to provide you with the MFA token required to access their account.
  2. Save the values for link and session as they're needed in the PATCH Complete a links request.

PATCH Complete a links request

As soon as your user provides your with the MFA token to access INSS Brazil, you can make the following PATCH request to complete the link creation:

curl --location 'https://production.belvo.com/api/links/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD) \
--data '{see example below}'
{
  "link": "link_id_from_428_response",
  "session": "session_id_from_428_response",
  "token": "mfa_token_provided_by_user",
}
ParameterTypeRequiredDescriptionExample
linkstringtrueThe link ID you received in the 428 - Token Required response.2f8ca7a1-c28f-46f2-bb41-21633099a280
sessionstringtrueThe session ID you received in the 428 - Token Required response.be7a15d5f0b84d8ea60f6c12cb2a7b32
tokenstringtrueThe MFA token your user provided you to login to the institution.453288976

{
    "id": "74c01cb4-edf1-44d6-8876-b1dc2aebcb14",
    "institution": "inss_br_employment",
    "access_mode": "single",
    "status": "valid",
    "refresh_rate": null,
    "created_by": "6e9be884-4781-4143-b673-aca02475ee8c",
    "last_accessed_at": "2024-06-26T16:25:54.344113Z",
    "external_id": "COHORT_32",
    "created_at": "2024-06-26T16:25:54.334413Z",
    "institution_user_id": "BidIxnZkKvQx0_F0oSYVx6Jnsh4Zmoat2ot2iOoG018=",
    "credentials_storage": "365d",
    "stale_in": null,
    "fetch_resources": [
        "EMPLOYMENT",
        "OWNERS"
    ]
}

✳️ Done! Belvo will now connect to the institution and validate that the provided CPF is correct. Once validated and your link is created, Belvo will asynchronously load the employment data.We will send you a webhook once we have retrieved the data for the given link, and you can then extract it with a get request.

Wait for a webhook and get employment data

As soon as your banking recurrent link is created, we asynchronously load the employment information available for the link and will send you the following webhook:

Webhook CodeDescription
historical_updateThe total number of employments found for the link.

In the webhook payload we include the number of employments found for the link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employments": 1 // The total number of employment record profiles found for the link
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/api/br/employments/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
Query ParameterDescriptionExample
linkThe link_id you received in the webhook notification.2f5d361d-dad6-45d4-a0bf-26d479766067

👍

For details about the response body, make sure to check out our List Employments (Brazil) API reference documentation or Employment (Brazil) Data Dictionary.

Wait for a webhook and get owner data

As soon as your banking link is created, we asynchronously load the owner information available for the link and will send you the following webhook:

Webhook CodeDescription
historical_updateThe total number of owners found for the link.

In the webhook payload we include the number of owners found for the link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_owners": 2 // Total number of owners
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]
Query ParameterDescriptionExample
linkThe link_id you received in the webhook notification.2f5d361d-dad6-45d4-a0bf-26d479766067