# 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.


```mermaid
sequenceDiagram
    participant App as Application
    participant Belvo as Belvo
    participant Institution as Employment Institution

    App->>Belvo: POST /token/
    Note over App,Belvo: fetch_resources = [EMPLOYMENTS, OWNERS]
    Belvo-->>App: 200 - Token Generated
    
    App->>Belvo: Direct your user to the Hosted Widget
    Belvo->>Institution: User logs in to their institution
    Belvo-->>App: User redirected back to your application + link generated

    Belvo->>Institution: Belvo retrieves historical<br/>EMPLOYMENT and OWNER<br/>information for the Link ID

    Note over Belvo,App: EMPLOYMENTS

    Belvo->>App: WEBHOOK: historical_update
    App->>Belvo: GET /br/employments/{link-id}
    Belvo-->>App: 200 + Employment Details

    Note over Belvo,App: OWNERS

    Belvo->>App: WEBHOOK: historical_update
    App->>Belvo: GET /owners/{link-id}
    Belvo-->>App: 200 + Owner Details

    Note over App, Institution: If using recurrent Links, at the scheduled refresh frequency<br/>you will receive a new_{resource}_available webhook.

    Belvo->>App: WEBHOOK: new_employments_available
    App->>Belvo: GET /br/employments/{link-id}
    Belvo-->>App: 200 + Employment Details
```

## 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 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'
```

Employments Brazil
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENTS", "OWNERS"], // [!code highlight]
  "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/"
    },
    "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. |


## Start the widget in your application for your user

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:


```shell Hosted Widget URL
https://widget.belvo.io/
  ?access_token={access_code} # [!code ++]
  &locale=pt # [!code ++]
  &institutions=inss_br_employment # [!code warning]
  &access_mode=single # [!code warning]
  &external_id=HJLSI-897809 # [!code warning]
```

| 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 link is created, we asynchronously load the employment information available for the link and will send you the following webhook:


```json 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:


```curl Example Request
curl --request GET 'https://api.belvo.com/api/br/employments/?link={id}' \
-u SECRET_ID:SECRET_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.


```json Historical Webhook Example
{
  "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 Example Request
curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u SECRET_ID:SECRET_PASSWORD
```

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