# 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 historical employment record information - Getting current employment record information Current Employments Coming Soon! This guide currently mentions a new resource that's currently in development: **Current Employments**. This resource will be available in the coming days, and we will update this guide once it's ready. For now, you can only extract **Employment Records**. ## 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. ```mermaid sequenceDiagram participant App as Application participant Belvo as Belvo participant EI as Employment Institution App->>Belvo: POST /links/ Note over App,Belvo: fetch_resources =
["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"] Belvo->>EI: Connect and confirm link creation Belvo-->>App: 201 - Created EI-->>Belvo: Belvo retrieves historical employment information for the link ID Note over App,EI: For each resource listed in fetch_resources, you will receive a historical_update webhook. Belvo->>App: WEBHOOK
historical_update (EMPLOYMENT_RECORDS) App->>Belvo: GET /employment-records/?link={id} Belvo-->>App: 200 + Employment Record Details Belvo->>App: WEBHOOK
historical_update (CURRENT_EMPLOYMENTS) App->>Belvo: GET /current-employments/?link={id} Belvo-->>App: 200 + Current Employment Details Note over App,EI: If using recurrent links, at the scheduled refresh frequency you will receive a webhook. Belvo->>App: WEBHOOK
new_employment_records_available App->>Belvo: GET /employment-records/?link={id} Belvo-->>App: 200 + Employment Record Details ``` ## 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 ```curl 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}' ``` ```json Sandbox Request Body { "institution": "planet_mx_employment", "username": "BLPM951331IONVGR54", "fetch_resources": ["EMPLOYMENT_RECORDS"], "access_mode": "single", "external_id":"COHORT_32_User_6790023X5" } ``` Production ```curl Production Request URL 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}' ``` ```json Production Request Body { "institution": "imss_mx_employment", "username": "valid_curp", "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], "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 can send through: `EMPLOYMENT_RECORDS` and `CURRENT_EMPLOYMENTS`. **Note**: `CURRENT_EMPLOYMENTS` is not available in the sandbox environment. | `["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]` | | `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` | ```json Example Link Response { "id": "74c01cb4-edf1-44d6-8876-b1dc2aebcb14", // [!code highlight] "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", "CURRENT_EMPLOYMENTS" ] } ``` **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. When Errors Occur In the table below, we also indicate when the error can occur in **Occurs During** column. The possible values are: - **Link Creation**: Errors that occur when creating the link. - **Data Extraction**: Errors that occur when extracting data after the link is created. You will received this error in a webhook notification. | Belvo error_code | Error Message | Reason | Occurs During | | --- | --- | --- | --- | | `400 invalid_credentials` | El NSS capturado no coincide con la CURP | The associated NSS does not match the CURP number. | Data Extraction | | `400 login_error` | El NSS no fue localizado en el IMSS | The NSS number is not present in the IMSS system. | Link Creation | | `400 login_error` | El CURP proporcionado no fue localizado en la entidad externa RENAPO | The CURP was not found in the RENAPO system. | Data Extraction | | `400 login_error` | CURP es incorrecto | The CURP is incorrect (might have a typo, not enough characters, or poorly formatted) | Link Creation | | `400 login_error` | Por favor, ingresa un CURP válido. Debe contener 18 caracteres | The CURP provided has more or less than 18 characters. | Link Creation | | `400 login_error` | La persona no cuenta con NSS | The individual does not have a *Número de Seguridad Social* (NSS) number. | Link Creation | | `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. | Data Extraction | | `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. | Data Extraction | | `400 login_error` | El correo ya está registrado con otro CURP | The email address is already registered with another CURP. | Data Extraction | | `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. | Data Extraction | ## Wait for a webhook and get Employment Record 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. ```json 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: ```shell Employment Records GET Request curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \ -u SECRET_ID:SECRET_PASSWORD ``` | Query Parameter | Description | Example | | --- | --- | --- | | `link` | The `link_id` you received in the webhook notification. | `2f5d361d-dad6-45d4-a0bf-26d479766067` | ## Wait for a webhook and get Current Employment data As soon as your employment link (for Mexico) is created, we asynchronously retrieve the Current Employments for the link and send you the following webhook: | Webhook Code | Description | | --- | --- | | `historical_update` | The total number of Current Employment records found for the link. | In the webhook payload we include the number of Current Employment records found for the link. ```json Current Employments Historical Update Example { "webhook_id": "03d1ca0d62db4f769488265d141047b7", "webhook_type": "CURRENT_EMPLOYMENTS", "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_current_employments": 1 // The total number of Current Employment records found for the link } } ``` Once you receive the notification, you can get further details by making the following request: ```shell Current Employments GET Request curl --request GET 'https://api.belvo.com/api/mx/current-employments/?link=link_id' \ -u SECRET_ID:SECRET_PASSWORD ``` | Query Parameter | Description | Example | | --- | --- | --- | | `link` | The `link_id` you received in the webhook notification. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |