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

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

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 Request URL

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

Sandbox Request Body

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENT_RECORDS"],
  "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/",
      "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 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 must send through `["EMPLOYMENT_RECORDS"]`.
`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.

Example Token Response

{
  "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3Mz...", 
  "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0O...."
}

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=mx
  &institutions=planet_mx_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 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 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.

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:

Employment Records GET Request

curl --request GET 'https://api.belvo.com/api/employment-records/?link=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`