# Extract Employment Records (Widget)

> In Mexico? This guide will walk you through the process of using our API to securely and efficiently extract employment records, enabling you to verify employment, understand career history, and more.


## Introduction

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

- A general overview of the data flow
- Generating a widget access token and creating a link
- Getting employment record information


Current Employments Coming Soon!
This guide currently mentions a new resource that's currently in development: **Current Employments**. This resource will be available in the coming days, and we will update this guide once it's ready. For now, you can only extract **Employment Records**.

## 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 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. So that we can notify you once the data is ready, you'll need to provide a URL where we can send events to.


```mermaid
sequenceDiagram
  autonumber

  participant App as Application
  participant Belvo as Belvo
  participant EI as Employment Institution

  App->>Belvo: POST /token/<br/>fetch_resources =<br/>["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]
  Belvo-->>App: 200 - Token Generated
  App->>App: Direct your user to the Hosted Widget
  App->>EI: User logs in to their institution
  EI-->>Belvo: Belvo retrieves historical employment information for the link ID
  Belvo-->>App: User redirected back to your application. You receive a link ID for the user.

  Note over App,EI: For each resource listed in fetch_resources, you will receive a historical_update webhook.

  Belvo->>App: WEBHOOK historical_update (EMPLOYMENT_RECORDS)
  App->>Belvo: GET /employment-records/?link={id}
  Belvo-->>App: 200 + Employment Record Details

  Belvo->>App: WEBHOOK historical_update (CURRENT_EMPLOYMENTS)
  App->>Belvo: GET /current-employments/?link={id}
  Belvo-->>App: 200 + Current Employment Details

  Note over App,EI: If using recurrent links, at the scheduled refresh frequency you will receive a webhook.

  Belvo->>App: WEBHOOK new_employment_records_available
  App->>Belvo: GET /employment-records/?link={id}
  Belvo-->>App: 200 + Employment Record Details
```

## Generate an access token

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

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.

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

Sandbox

```shell Sandbox Request URL
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'see example payload below'
```

Employments Records Mexico
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], // [!code highlight]
  "widget": {
    "callback_urls": {
      "success": "your-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-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
  }
}
Production

```shell Production Request URL
curl -X POST \
  https://production.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'see example payload below'
```

Employments Records Mexico
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], // [!code highlight]
  "widget": {
    "callback_urls": {
      "success": "your-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-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 | Example |
|  --- | --- | --- | --- | --- |
| `id` | string | true | Replace `YOUR_SECRET_ID` with the secret ID you generated in the Belvo dashboard. |
| `password` | string | true | Replace `YOUR_SECRET_PASSWORD` with the secret password 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 record data in Mexico, you can send through `["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]`. **Note**: `CURRENT_EMPLOYMENTS` is not available in the sandbox environment. |
| `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. |



```json Example Token Response
{
  "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3Mz...", // [!code highlight]
  "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0O...."
}
```

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

Sandbox

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

Production

```curl Hosted Widget URL
https://widget.belvo.io/
	?access_token={access_code} # [!code ++]
  &locale=mx # [!code ++]
  &institutions=imss_mx_employment,issste_mx_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 Mexico, you must set the locale query parameter to `mx`. |
| `institutions` | false | With the `institutions` parameter, you can provide one (or more) institutions that should display in the widget. In the case of Employment Records in Mexico, we recommend setting this parameter to `imss_mx_employment,issste_mx_employment`. |
| `access_mode` | false | The type of link to create (`single` or `recurrent`). For Employment Records in Mexico, we recommend using `single` links. For more information about a link's `access_mode`, see our dedication section here. |
| `external_id`
 | highly recommended
 | Your internal reference for this user. This is extremely useful as you can the data that Belvo retrieves for this user in your system. 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 CURP 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 Record data

As soon as your employment link (for Mexico) is created, we asynchronously retrieve the Employment Records for the link and send you the following webhook:

| Webhook Code | Description |
|  --- | --- |
| `historical_update` | The total number of Employment Records found for the link. |


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


```json Employment Records Historical Update Example
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "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_employment_record_profiles": 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:


```shell Employment Records GET Request
curl --request GET 'https://api.belvo.com/api/employment-records/?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` |


## Wait for a webhook and get Current Employment data

As soon as your employment link (for Mexico) is created, we asynchronously retrieve the Current Employments for the link and send you the following webhook:

| Webhook Code | Description |
|  --- | --- |
| `historical_update` | The total number of Current Employment records found for the link. |


In the webhook payload we include the number of Current Employment records found for the link.


```json Current Employments Historical Update Example
{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "CURRENT_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_current_employments": 1 // The total number of Current Employment records found for the link
  }
}
```

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


```shell Current Employments GET Request
curl --request GET 'https://api.belvo.com/api/mx/current-employments/?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` |