Employment aggregation

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


Asynchronous workflows

We highly recommend you implement asynchronous workflows when interating with employment aggregation data. This ensures a smoother data retrieval flow and removes the risk your integration receiving timeout errors.

Employment Records Mexico

Employment Records Mexico asynchronous workflow for single links

Employment Records Mexico asynchronous workflow for single links

Our employment records resource for Mexico 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)
  • fetch_resouces: A list of resources that Belvo will asynchronously retrieve and notify you about when the data is available. For IMSS, you can send the following resources: EMPLOYMENT_RECORDS, OWNERS.
  "institution": "imss_mx_employment",
  "username": "the_user_curp",
  "fetch_resources": ["EMPLOYMENT_RECORDS", "OWNERS"]
  "id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "institution": "imss_mx_employment",
  "access_mode": "single",
  "last_accessed_at": "2019-09-27T13:02:03.584Z",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "external_id": "56ab5706-6e00-48a4-91c9-ca55968678d9",
  "institution_user_id": "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c=",
  "status": "valid",
  "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09",
  "refresh_rate": null,
  "credentials_storage": "265d",
  "fetch_resources": ["EMPLOYMENT_RECORDS", "OWNERS"],
  "stale_in": "365d"

When the link is created successfully, Belvo will asynchronously retrieve the Employment and Owner data for the user and notify you via webhook that the information is ready to be retrieved:

   "link_id":"2f5d361d-dad6-45d4-a0bf-26d479766067", // Use this ID in your GET request
   "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
   "external_id": "your_external_id",
      "total_employment_record_profiles": 1 // The total number of employment record profiles found for the link
curl --request GET 'https://api.belvo.com/api/employment-records/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
  "count": 1,
  "next": "null",
  "previous": null,
  "results": [
      "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04",
      "link": "2f5d361d-dad6-45d4-a0bf-26d479766067",
      "created_at": "2020-04-23T21:32:55.336854+00:00",
      "collected_at": "2020-04-23T21:32:55.336854+00:00",
      "report_date": "2023-01-19",
      "internal_identification": "BLPM951331IONVGR54",
      "personal_data": {
        "official_name": "Bruce Banner del Torro",
        "first_name": "Bruce",
        "last_name": "Banner del Torro",
        "birth_date": "2022-02-09",
        "entitlements": {
          "entitled_to_health_insurance": true,
          "entitled_to_company_benefits": true,
          "valid_until": null,
          "status": "EMPLOYED"
        "document_ids": [
            "document_type": "NSS",
            "document_number": "10277663582"
      "social_security_summary": {
        "weeks_redeemed": 0,
        "weeks_reinstated": 0,
        "weeks_contributed": 188
      "employment_records": [
          "collected_at": "2020-04-23T21:32:55.336854+00:00",
          "employer": "Batman Enterprises CDMX",
          "employer_id": "780-BAT-88769-CDMX",
          "start_date": "2019-10-10",
          "end_date": "2019-12-31",
          "weeks_employed": 12,
          "state": "DISTRITO FEDERAL",
          "most_recent_base_salary": 762.54,
          "monthly_salary": 0,
          "currency": "MXN",
          "employment_status_updates": [
              "event": "HIRED",
              "base_salary": 1033.09,
              "update_date": "2021-09-01"
      "files": [
          "type": "ReporteSemanasCotizadas_190123",
          "value": "=PDF_BINARY="

IMSS-specific error messaging

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

Belvo error_codeError MessageReason
400 invalid_credentialsEl NSS no fue localizado en el IMSSThe NSS number is not present in the IMSS system.
400 invalid_credentialsEl NSS capturado no coincide con la CURPThe associated NSS does not match the CURP number.
400 login_errorEl CURP proporcionado no fue localizado en la entidad externa RENAPOThe CURP 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.

Employments Brazil

Employments Brazil asynchronous flow for single links

Employments Brazil asynchronous flow for single links

Our employments resource for Brazil lets you get a comprehensive view of your user's current employment history and salary information.

For each user, we return the:

  • work history (including occupations and employer data)
  • historical and current salary information (per employer)

At the moment, the employments resource is available for:

  • 🇧🇷 Brazil (INSS)

For a list of available endpoints and methods, see our API reference.