Employment aggregation

Use our Employment product to access employment data such as work history and salaries in Mexico.


Owner information

With our employment aggregation product, you also have access to owner information for each of your users. To retrieve owner information for your users, just use the same resource as for our banking aggregation product.

Employment Records

Our employment records resource lets you get a comprehensive view of your user’s current social security contributions and employment history.

With Belvo's employment records resource, you can access information about your user's current social security contributions and employment history. For each user, we return the:

  • personal data
  • work history
  • historical and current daily base salary
  • and more!

At the moment, the employment records resource is available for:

  • 🇲🇽 Mexico (IMSS)
RetrievePOSTRetrieve all employment historical data related to a specific link.
ListGETList all the employment historical data for all the Links already associated with your Belvo account.
DetailGETGet the details of a specific individual's employment data.
DestroyGETDelete specific employment data from your Belvo account.

Creating a link with Mexico's IMSS

To be able to use the employment records resource, you'll first need to create a link using our Register a new link method, providing the following parameters:

  • username: The user's CURP number. (Required)
  • username2: The user's email address. (Optional)

When the link is created successfully, you'll receive the link id in the response, which you'll need to use in order to retrieve the specific information for the individual when making a Retrieve employment records request.

IMSS-specific error messaging

In addition to our standard errors, our API also returns custom messaging specific for IMSS:

Belvo error_codeError MessageReason
400 login_errorEl CURP proporcionado no fue localizado en la entidad externa RENAPOThe CURP is was not found in the RENAPO system.
400 login_errorCURP es incorrectoThe CURP is incorrect (might have a typo, not enough characters, or poorly formatted)
400 login_errorPor favor, ingresa un CURP válido. Debe contener 18 caracteresThe CURP provided has more or less than 18 characters.
400 missing_credentialsLos 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 missing_credentialsLa persona no cuenta con NSSThe individual does not have a Número de Seguridad Social (NSS) number.
403 forbidden_by_hostHas 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.