Extract Employment Records (API)

Looking to access employment history data for your users 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 API. This includes:

A general overview of the data flow
Creating a link (via API)
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 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.

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 or ISSSTE). Whenever you want to extract information from a new user, you'll need to create a link.

To create a link, you just need to make the following POST Register a new link request:

Sandbox Request URL

curl --location 'https://sandbox.belvo.com/api/links/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD)' \
--data '{see examples below}'

Sandbox Request Body

{
  "institution": "planet_mx_employment",
  "username": "BLPM951331IONVGR54",
  "fetch_resources": ["EMPLOYMENT_RECORDS"],
  "access_mode": "single",
  "external_id":"COHORT_32_User_6790023X5"
}

Parameter	Type	Required	Description	Example
`institution`	string	true	The institution where you want to create the link. You can choose: `planet_mx_employment` for Sandbox `imss_mx_employment` or `issste_mx_employment` for Production	`planet_mx_employment`
`username`	string	true	The CURP of the individual. Belvo uses industry-standard AES-256 symmetric encryption to encrypt credentials.	`BLPM951331IONVGR54`
`fetch_resources`	array of strings	true	The resources you want Belvo to retrieve. For Employment Records in Mexico, you must send through: `EMPLOYMENT_RECORDS`.	`["EMPLOYMENT_RECORDS"]`
`access_mode`	string	true	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.	`single`
`external_id`	string	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). For more details, see the Adding your own identifier section of our Link creation best practices guide.	`COHORT_32_User_6790023X5`

Example Link Response

{
    "id": "74c01cb4-edf1-44d6-8876-b1dc2aebcb14", 
    "institution": "planet_mx_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_RECORDS",
    ]
}

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.

Common errors when creating a link

When you create a link with IMSS Mexico, you might receive specific errors due to the CURP you provide. Below you can see a couple of common errors along with the explanations as to why they occur:

Belvo error_code	Error Message	Reason
`400 invalid_credentials`	El NSS capturado no coincide con la CURP	The associated NSS does not match the CURP number.
`400 login_error`	El NSS no fue localizado en el IMSS	The NSS number is not present in the IMSS system.
`400 login_error`	El CURP proporcionado no fue localizado en la entidad externa RENAPO	The CURP was not found in the RENAPO system.
`400 login_error`	CURP es incorrecto	The CURP is incorrect (might have a typo, not enough characters, or poorly formatted)
`400 login_error`	Por favor, ingresa un CURP válido. Debe contener 18 caracteres	The CURP provided has more or less than 18 characters.
`400 login_error`	La persona no cuenta con NSS	The individual does not have a Número de Seguridad Social (NSS) number.
`400 login_error`	Los datos registrados en el IMSS asociados a la CURP, presentan alguna inconsistencia, por favor acude a tu Subdelegación para obtener tu Número de Seguridad Social.	There is an inconsistency with the information provided to login and what the institution has.
`400 login_error`	Es necesario que acudas a la subdelegación más cercana a tu domicilio a presentar tu trámite	The user associated with the CURP needs to go to their nearest IMSS office in order to submit additional paperwork for the operation to be carried out.
`400 login_error`	El correo ya está registrado con otro CURP	The email address is already registered with another CURP.
`403 forbidden_by_host`	Has agotado el número de solicitudes permitidas por día.	The user's CURP has been used more than three times to log in to the institution within a 24-hour period. We recommend you retry retrieving data the next day.

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`