Extract Employment Information in Mexico (API)
So, want to get employment data about your users in Mexico? Well, you've come to the right place 😎
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
- Generating your API keys
- Providing a webhook URL (to receive events from Belvo)
- Creating a link
- Getting employment record information
What data can I get about my users?
For a detailed list of data that our Employment Record API returns for your users, see our:
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.
Employment Records Asynchronous Workflow
Generate API Keys
To use our API, you will need to generate some API keys to authenticate all your request.
To generate your API keys:
- Sign in to your Belvo Dashboard.
- Choose the environment you want to create API keys for (Sandbox or Production). If you're just starting to use the Belvo API, we recommend using the Sandbox environment.
- Go to Developers -> API Keys.
- Click on Generate API Keys, which will automatically generate your API keys.
- In the pop-up, copy and securely save the values for Secret ID and Secret Password.
Note: In the pop-up, you also have the option of forking Belvo's API collection. For more information on how to use Postman and Belvo's collection, see our Getting started in 10 minutes guide.
✳️ Done! You've just generated your API keys! But before you can start making API calls, you just need to set up a webhook where we can send events to.
Add a webhook URL
Just testing out?
If you're just starting your integration and aren't sure how to get a URL for a webhook, you can use a service like Pipedream. Check out our Getting started in 10ish minutes to see how it's done!
To set up a new webhook:
- Sign in to your Belvo Dashboard.
- Choose the environment you want to receive webhook events for (Sandbox or Production).
- Go to Developers -> Webhooks.
- Click +New webhook.
- Fill in the New webhook form with the required information.
- URL: the URL to receive the webhook notifications.
- Authorization: an optional bearer token to use if your URL is protected.
- Click Create webhook.
✳️ Done! You've now created a webhook and can start creating links and receiving events!
Whitelisting Belvo IP addresses
Belvo will send events to your webhook URL from the IP addresses listed below. Your security team may want to add these to their list of IP addresses that they allow events from (otherwise, your system may block events from reaching your system).
3.130.254.4618.220.61.18618.223.45.212
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). 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:
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}'
curl --location 'https://api.belvo.com/api/links/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD)' \
--data '{see examples below}'
{
"institution": "planet_mx_employment",
"username": "BLPM951331IONVGR54",
"fetch_resources": ["EMPLOYMENT_RECORDS","OWNERS"],
"access_mode": "single",
"external_id":"COHORT_32_User_6790023X5"
}
{
"institution": "imss_mx_employment",
"username": "valid_curp",
"fetch_resources": ["EMPLOYMENT_RECORDS","OWNERS"],
"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 | - planet_mx_employment for Sandbox- imss_mx_employment or issste_mx_employment for Production |
username | string | true | The CURP of the individual. Note: Belvo uses industry-standard AES-256 symmetric encryption to encrypt credentials. | BLPM951331IONVGR54 |
fetch_resources | array | true | The resources you want Belvo to retrieve. For employment records in Mexico, you must send through at least EMPLOYMENT_RECORDS | ["EMPLOYMENT_RECORDS","OWNERS"] |
access_mode | string | true | The type of link to create. For employment data, we recommend using single links. For more information about a link's access_mode, see our dedication section here. | single |
external_id | string | recommended | Your internal reference for this user. This is extremely useful for you as you'll be able to relate the data that Belvo retrieves for this user in your system. | COHORT_32_User_6790023X5 |
{
"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",
"OWNERS"
]
}
✳️ 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 stated, Belvo will asynchronously retrieve the employment record data for your link and then send you a webhook once the information is ready to retrieve (see the webhook example below):
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
"webhook_type": "EMPLOYMENT_RECORDS",
"webhook_code": "historical_update",
"process_type": "historical_update",
"link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", //This is the id you will use to retrieve the employment records
"request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
"external_id": "COHORT_32_User_6790023X5",
"data": {
"total_employment_record_profiles": 1 // The total number of employment record profiles found for the link
}
}
Retrieve the employment information
Once you receive the webhook, you just need to make the following GET Employment Records request to retrieve the data for the given 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": "f6c82d57-85ba-40ca-bf4b-6bf4aa8d9060",
"link": "d95301ea-6c88-43c0-9ea9-5c84ab49f4b6",
"created_at": "2024-06-28T13:06:21.213271Z",
"files": [
{
"type": "ReporteSemanasCotizadas_977509",
"value": "Maintain level rule whatever car school. Receive treatment significant campaign late. Suggest where hour although join.\nLeader movement camera morning. Begin can chance general."
},
{
"type": "ReporteSemanasCotizadas_292862",
"value": "Congress example beyond door. Music common run people whom speak American. Usually need follow miss industry.\nRise than several. Board focus building cultural candidate."
},
{
"type": "ReporteSemanasCotizadas_548585",
"value": "Cost base expect event cultural. Show rather star another. Today test character enter find new.\nCare more movie PM quality book. Country hard media necessary already audience chance might."
}
],
"report_date": "2024-06-28",
"collected_at": "2024-06-28T08:06:08.702686Z",
"personal_data": {
"email": "[email protected]",
"last_name": "Friedman",
"birth_date": "1971-12-07",
"first_name": "Joshua",
"document_ids": [
{
"document_type": "NSS",
"document_number": "6159395308"
},
{
"document_type": "CURP",
"document_number": "user_valid"
}
],
"entitlements": {
"status": "EMPLOYED",
"valid_until": "2025-06-12",
"entitled_to_company_benefits": false,
"entitled_to_health_insurance": false
},
"official_name": "Todd Cisneros"
},
"employment_records": [
{
"state": "DISTRITO FEDERAL",
"currency": "MXN",
"employer": "Cannon PLC",
"end_date": "2024-02-04",
"start_date": "2021-11-16",
"employer_id": "48250622-5f1f-4c73-8822-77a4d47f88b3",
"collected_at": "2024-06-28T08:06:08.702330Z",
"monthly_salary": 49810.77,
"weeks_employed": 119,
"most_recent_base_salary": 1838.66,
"employment_status_updates": [
{
"event": "HIRED",
"base_salary": 1574.62,
"update_date": "2024-04-17"
},
{
"event": "HIRED",
"base_salary": 1786.72,
"update_date": "2024-05-03"
}
]
},
{
"state": "DISTRITO FEDERAL",
"currency": "MXN",
"employer": "May Ltd",
"end_date": "2024-02-16",
"start_date": "2022-12-27",
"employer_id": "67801e28-fe4b-46fd-bf88-b48c324490cd",
"collected_at": "2024-06-28T08:06:08.702450Z",
"monthly_salary": 31115.51,
"weeks_employed": 48,
"most_recent_base_salary": 1544.66,
"employment_status_updates": [
{
"event": "HIRED",
"base_salary": 1922.95,
"update_date": "2024-04-07"
},
{
"event": "HIRED",
"base_salary": 1733.63,
"update_date": "2024-05-24"
},
{
"event": "HIRED",
"base_salary": 1946.74,
"update_date": "2024-06-09"
}
]
},
{
"state": "DISTRITO FEDERAL",
"currency": "MXN",
"employer": "Snow LLC",
"end_date": "2023-10-11",
"start_date": "2022-05-08",
"employer_id": "65c8bf98-8645-43c7-aa79-ee3de4c50aa2",
"collected_at": "2024-06-28T08:06:08.702527Z",
"monthly_salary": 37234.08,
"weeks_employed": 83,
"most_recent_base_salary": 1424.28,
"employment_status_updates": [
{
"event": "HIRED",
"base_salary": 1396.02,
"update_date": "2024-04-01"
},
{
"event": "HIRED",
"base_salary": 1513.9,
"update_date": "2024-04-17"
},
{
"event": "HIRED",
"base_salary": 1978.74,
"update_date": "2024-03-23"
},
{
"event": "SALARY_MODIFICATION",
"base_salary": 1006.82,
"update_date": "2024-04-01"
},
{
"event": "DISMISSED_RESIGNED",
"base_salary": 1491.67,
"update_date": "2024-05-16"
}
]
},
{
"state": "DISTRITO FEDERAL",
"currency": "MXN",
"employer": "Davenport-Ballard",
"end_date": "2023-08-11",
"start_date": "2023-02-01",
"employer_id": "b4d31eea-ffc9-4a83-95e5-0258462e869e",
"collected_at": "2024-06-28T08:06:08.702577Z",
"monthly_salary": 46207.01,
"weeks_employed": 28,
"most_recent_base_salary": 1125.43,
"employment_status_updates": [
{
"event": "SALARY_MODIFICATION",
"base_salary": 1730.8,
"update_date": "2024-04-16"
}
]
},
{
"state": "DISTRITO FEDERAL",
"currency": "MXN",
"employer": "Morrison and Sons",
"end_date": "2023-05-20",
"start_date": "2021-10-08",
"employer_id": "ee61af26-e99c-4407-904c-dda9da89fa06",
"collected_at": "2024-06-28T08:06:08.702647Z",
"monthly_salary": 34532.0,
"weeks_employed": 97,
"most_recent_base_salary": 1561.54,
"employment_status_updates": [
{
"event": "SALARY_MODIFICATION",
"base_salary": 1287.42,
"update_date": "2024-04-05"
},
{
"event": "HIRED",
"base_salary": 1751.86,
"update_date": "2024-05-19"
},
{
"event": "HIRED",
"base_salary": 1002.4,
"update_date": "2024-06-26"
},
{
"event": "SALARY_MODIFICATION",
"base_salary": 1003.09,
"update_date": "2024-03-22"
},
{
"event": "DISMISSED_RESIGNED",
"base_salary": 1898.58,
"update_date": "2024-03-30"
}
]
}
],
"internal_identification": "user_valid",
"social_security_summary": {
"weeks_redeemed": 0,
"weeks_reinstated": 34,
"weeks_contributed": 257
}
}
]
}
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | string | true | The link_id you receive in your historical_update notification. | 2f8ca7a1-c28f-46f2-bb41-21633099a280 |
For details regarding what data is retrieved, make sure to check out either our:
Wait for a webhook and get owner data
Belvo will asynchronously retrieve the owner data for your link and then send you a webhook once the information is ready to retrieve (see the webhook example below):
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
"webhook_type": "OWNERS",
"webhook_code": "historical_update",
"process_type": "historical_update",
"link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", // This is the id you will use to retrieve the owner information
"request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
"external_id": "COHORT_32_User_6790023X5",
"data": {
"total_owners": 1 // The total number of owners found for the link
}
}
Once you receive the webhook, you just need to make the following GET Owners request to retrieve the data for the given link:
curl --request GET 'https://api.belvo.com/api/owners/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
{
"count": 1,
"next": "null",
"previous": null,
"results": [
{
"id": "b617120c-fbd0-4296-b03c-6473bbbeeee6",
"link": "2f8ca7a1-c28f-46f2-bb41-21633099a280",
"collected_at": "2022-02-09T08:45:50.406032Z",
"created_at": "2022-02-09T08:46:20.406032Z",
"display_name": "Maria Martinez Martin",
"first_name": null,
"last_name": null,
"second_last_name": null,
"email": "[email protected]",
"phone_number": "90090508357",
"address": "Retorno Gran Canaria 453 723\nCancun, BRA 10447",
"document_id": {
"document_type": "CPF",
"document_number": "07690251021"
},
"internal_identification": null
}
]
}
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | string | true | The link_id you receive in your historical_update notification. | 2f8ca7a1-c28f-46f2-bb41-21633099a280 |
Updated 10 days ago