👍
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

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
employment score
An employment score provides insight into the likelihood of a user meeting their future financial obligations in a given period. For each employment record we provide a score for the upcoming 3, 6, and 12 months.
and more!

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

🇲🇽 Mexico (IMSS)

Endpoints	Method	Description
Retrieve	POST	Retrieve all employment historical data related to a specific link.
List	GET	List all the employment historical data for all the Links already associated with your Belvo account.
Detail	GET	Get the details of a specific individual's employment data.
Destroy	GET	Delete 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:

{
   "webhook_id":"03d1ca0d62db4f769488265d141047b7",
   "webhook_type":"EMPLOYMENT_RECORDS", 
   "webhook_code":"historical_update", 
   "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",
   "data":{
      "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_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.

Employments Brazil

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.

Employment aggregation

👍
Asynchronous workflows

Employment Records Mexico

Creating a link with Mexico's IMSS

IMSS-specific error messaging

Employments Brazil

👍Asynchronous workflows

Employment Records Mexico

Creating a link with Mexico's IMSS

IMSS-specific error messaging

Employments Brazil

👍
Asynchronous workflows