Extract Employment Data in Brazil

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 a widget access token and creating a link
Getting employment and owner information

Prerequisites

Before you proceed with your integration, make sure that you have Gone through our getting started guide. In the getting started guide, you will create a Belvo account, generate some sandbox API keys, and set up a webhook URL. For testing purposes and developing your integration, we highly recommend using the Sandbox environment where possible.

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 your user successfully creates a link using the Hosted Widget, 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.

Generate an access token

For the widget to appear to your end users, you need to generate an access token in your server-side and send it to Belvo. Once we receive the request, you'll receive an object with two keys: access and refresh. Pass the value of the access key when starting the hosted widget.

The returned values are valid for 10 minutes and we invalidate the token as soon as a user successfully connects their account.

To generate an access token, simply make a call from your server-side to Belvo:

cURL Request Headers

curl -X POST \
  https://production.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: production.belvo.com' \
  -d 'see example payloads below'

Request Body

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENTS", "OWNERS"],
  "widget": {
    "callback_urls": {
      "success": "your_deeplink_here://success",
      "exit": "your_deeplink_here://exit",
      "event": "your_deeplink_here://error"
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/",
      "overlay_background_color": "#F0F2F4",
      "social_proof": true
    },
    "theme": [] // See our dedicated widget customization article
  }
}

Parameter	Type	Required	Description
`id`	string	true	Replace `YOUR_SECRET_ID` with the secretID you generated in the Belvo dashboard.
`password`	string	true	Replace `YOUR_SECRET_PASSWORD` with the secretPassword you generated in the Belvo dashboard
`scopes`	string	true	The `scopes` parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown.
`stale_in`	string	optional	The stale_in parameter allows you to control for how long Belvo stores user-derived data. For more information, check out the `stale_in` section of our Data retention controls article.
`credentials_storage`	string	optional	The `credentials_storage` parameter allows you to control how long Belvo should store credentials for users. If you create recurrent links, this must be set to `store`. For more information, check out the `credentials_storage` section of our Data retention controls article.
`fetch_resources`	array of strings	true	In the `fetch_resources` parameter, you provide a list of resources that you want Belvo to asynchronously retrieve for the user. For employment data in Brazil, you must send through `["EMPLOYMENTS", "OWNERS"]`
`widget.callback_urls`	object	true	In the `callback_urls` object, you must add links to where your user should be redirected to in the following cases: success (your user successfully connected their accounts) exit (your user exited the widget before they completed the process) event (an error occurred during the connection process)For more information, check out the callback_urls section in our Hosted Widget (OFDA) guide.Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (OFDA) guide.
`widget.branding`	object	true	In the `branding` object, you must add your: `company_icon` `company_logo` `company_name` `company_terms_url`. You can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected. For more information about the branding and customization options of the widget, check out our dedicated guide.
`widget.theme`	array of objects	optional	You can optionally add your brand colors to the widget using the `theme` parameter. For more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide.

Next, you will need to redirect your user to the widget in a webview inside your application, using the access token you received from the /api/token/ request:

Hosted Widget URL

https://widget.belvo.io/
	?access_token={access_code}
  &locale=pt
  &institutions=inss_br_employment
  &access_mode=single
  &external_id=HJLSI-897809

Parameter	Required	Description
`access_token`	true	Replace `access_code` with the access token you received.
`locale`	true	For the hosted widget to function correctly for your users in Brazil, you must set the locale query parameter to `pt`.
`institutions`	false	With the `institutions` parameter, you can provide one (or more) institutions that should display in the widget. In the case of Employments in Brazil, we recommend setting this parameter to `inss_br_employment`.
`access_mode`	false	You can use the `access_mode` parameter to define which type of link you want to create (`single` or `recurrent`). By default, Belvo creates `recurrent` links.
`external_id`	highly recommended	You can add an additional identifier to be associated with the link in the Belvo database. The `external_id` that you provide: should be a unique ID for each user in your database. must be at least three characters long. can only be composed of letters, numbers, dashes (`-`), and underscores (`_`). cannot contain any personally identifiable information about the user (email, name, phone number, credit card number, and so on).

Additionally, check out our Starting the widget and callback events sections of our Hosted Widget (Multi-Region) guide.

✳️ 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 employment webhook

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:

Historical Webhook Example

{
  "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:

Example Request

curl --request GET 'https://api.belvo.com/api/br/employments/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Wait for owner webhook

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

Webhook Code	Description
historical_update	The total number of owners found for the link.

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