# Retrieve employment record details Retrieve employment record details for an individual. Endpoint: POST /api/employment-records/ Version: 1.222.0 Security: basicAuth ## Header parameters: - `X-Belvo-Request-Mode` (string) Recommended header parameter to make your POST request asynchronous (thus preventing timeouts and improving your data flow). When you make an asynchronous request, Belvo responds with a payload, including the . Once we have retrieved the requested information, you will receive a webhook with the link and request IDs. Enum: "async" ## Query parameters: - `omit` (string) Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article. - `fields` (string) Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article. ## Request fields (application/json): - `link` (string, required) The you want to retrieve information for. Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058" - `attach_pdf` (boolean) When set to , you will receive the PDF in binary format in the response. Example: true - `save_data` (boolean) Indicates whether or not to persist the data in Belvo. By default, this is set to and we return a 201 Created response. When set to , the data won't be persisted and we return a 200 OK response. Example: true ## Response 200 fields (application/json): - `id` (string) Belvo's unique identifier for the current item. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null) The the data belongs to. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `created_at` (string) The ISO-8601 timestamp of when the data point was created in Belvo's database. Example: "2022-02-09T08:45:50.406032Z" - `collected_at` (string) The ISO-8601 timestamp when the data point was collected. Example: "2022-02-09T08:45:50.406032Z" - `report_date` (string) The date when the employment record report was generated, in format. Example: "2023-01-19" - `internal_identification` (string) Unique ID for user according to the institution. For IMSS and ISSSTE Mexico, this is the CURP. Example: "BLPM951331IONVGR54" - `personal_data` (object) Details regarding the personal information of the individual. - `personal_data.official_name` (string,null) The legal name of the individual. Example: "Bruce Banner del Torro" - `personal_data.first_name` (string,null) The first name of the individual. Example: "Bruce" - `personal_data.last_name` (string,null) The last name of the individual. Example: "Banner del Torro" - `personal_data.birth_date` (string,null) The date of birth of the individual, in format. Example: "2022-02-09" - `personal_data.entitlements` (object) Details regarding the benefits the individual is entitled to. - `personal_data.entitlements.entitled_to_health_insurance` (boolean) Indicates whether or not the individual is entitled to health insurance. Example: true - `personal_data.entitlements.entitled_to_company_benefits` (boolean) Indicates whether or not the individual is entitled to company benefits. Example: true - `personal_data.entitlements.valid_until` (string,null) Date until when the individual is covered by health insurance and/or company benefits. If the employee is currently working and no end date is required. - `personal_data.entitlements.status` (string) Indicates the employment status of the individual. We return one of the following responses: - - - - Enum: "EMPLOYED", "RETIRED", "UNEMPLOYED", "null" - `personal_data.document_ids` (array) Details regarding the individual's ID documents. - `personal_data.document_ids.document_type` (string,null) The type of document related to the individual. We return one of the following values: - - - Enum: "NSS", "CURP", "RFC" - `personal_data.document_ids.document_number` (string,null) The ID document's number (as a string). Example: "10277663582" - `personal_data.email` (string,null) The email address of the individual. Example: "bruce.banner@avengers.com" - `social_security_summary` (object,null) Details regarding the individual's social security contributions, according to the IMSS. >: For ISSSTE Mexico, this value will return . - `social_security_summary.weeks_redeemed` (integer,null) Number of weeks the individual needed to take out of their pension. - `social_security_summary.weeks_reinstated` (integer,null) Number of weeks the individual has paid back into their pension (), after having redeemed them previously. - `social_security_summary.weeks_contributed` (integer,null) Number of weeks the individual has contributed to their social security, based on the number of weeks the individual has worked according to IMSS. Example: 188 - `employment_records` (array) Details regarding the individual's employment history. - `employment_records.collected_at` (string) The ISO-8601 timestamp when the data point was collected. Example: "2020-04-23T21:32:55.336854+00:00" - `employment_records.employer` (string) The official name of the employer. >: For ISSSTE Mexico, this is the official name of the entity along with the entity that is responsible for managing the employee's information, separated by a semicolon (). For example: SECRETARIA DE EDUCACION PUBLICA (SEP);SECRETARIA DE EDUCACION PUBLICA (SEP). Example: "Batman Enterprises CDMX" - `employment_records.employer_id` (string,null) The official ID of the employer, according to the country. >: For ISSSTE Mexico, this value will return . Example: "780-BAT-88769-CDMX" - `employment_records.start_date` (string) Date when employment started, in format. Example: "2019-10-10" - `employment_records.end_date` (string,null) Date when employment finished, in format. >: This field will return for the user's current employment. Example: "2019-12-31" - `employment_records.weeks_employed` (integer) Number of weeks that the individual was employed. Example: 12 - `employment_records.state` (string,null) In what geographical state the individual was employed, according to the country. >: For ISSSTE Mexico, this value will return . Example: "DISTRITO FEDERAL" - `employment_records.most_recent_base_salary` (number) The most recent base salary the individual earned. - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year. - For ISSSTE Mexico, this value is calculated dividing by 30 (days), and excludes the individual's perks. Example: 762.54 - `employment_records.monthly_salary` (number) The monthly salary of the individual, including any additional perks. - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year. - For ISSSTE Mexico, this value is calculated excluding perks. - `employment_records.currency` (string) The three-letter currency code in which the salary is paid. Example: "MXN" - `employment_records.employment_status_updates` (array,null) Details regarding any employment changes of the individual. - `employment_records.employment_status_updates.event` (string,null) For IMSS Mexico, this is the event that caused the change in employment status or salary. We return one of the following values: - : The employee was either dismissed or resigned. - : The employee received a salary modification (increase or decrease). - : The employee was hired. - : The employee made a voluntary contribution to IMSS. - : The employee was on absent (such as on vacation). - : The employee was on sick leave. For ISSSTE Mexico, this is the information source regarding the change in employment status or salary. We return one of the following values: - : Indicates that the information was received from the . - : Indicates that the information was received from the central database, . - : Indicates that the information was received from an affiliate institution, . Enum: "DISMISSED_RESIGNED", "SALARY_MODIFICATION", "HIRED", "VOLUNTARY_CONTRIBUTION", "ABSENCE", "SICK_LEAVE", "NORMAL", "BDUTA_CERTIFICATE", "DYE_CERTIFICATE" - `employment_records.employment_status_updates.base_salary` (number) The base salary of the individual, current as of the . - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year. - For ISSSTE Mexico, this value is calculated excluding the individual's perks. Example: 1033.09 - `employment_records.employment_status_updates.update_date` (string) The date that the employment event occurred, in format. Example: "2021-09-01" - `employment_scores` (array,null) An array of scores. Each score provides an insight into employability and income generation potential in a given period. > : This field is only available for links created with Mexico's IMSS. For other institutions, this field will return . > : This field will return for employment records retrieved before 16-04-2024. For employment records generated before 16-04-2024, you'll need to make a new POST request to retrieve employment records to calculate the scores. Example: [{"score":722,"period":3,"version":"1.0.0"},{"score":612,"period":6,"version":"1.0.0"},{"score":570,"period":12,"version":"1.0.0"}] - `employment_scores.score` (integer,null) A score between 300 and 900 that provides an insight into employability and income generation potential. - A low score (closer to 300) could indicate lower predicted employability and income generation potential, suggesting potential challenges in securing employment or achieving higher income levels in the future. - A high score (closer to 900) could suggest a greater likelihood of securing employment and generating higher income levels. The score can return if the individual has no employment history. Example: 612 - `employment_scores.period` (integer) The number of months (in the future) that the score is calculated for. For example, a period of indicates that the score is calculated for the next months. > : At present Belvo calculates the score for 3, 6, and 12 months. Example: 6 - `employment_scores.version` (string) The version of our employment score model used to perform the calculation. Example: "1.0.0" - `files` (array,null) Additional PDF binary files relating to the individual's employment. - `files.type` (string) The title of the document. Example: "ReporteSemanasCotizadas_190123" - `files.value` (string,null) The PDF binary of the file (as a string). > : In our sandbox environment, this field will return . Example: "=PDF_BINARY=" ## Response 201 fields (application/json): - `id` (string) Belvo's unique identifier for the current item. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null) The the data belongs to. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `created_at` (string) The ISO-8601 timestamp of when the data point was created in Belvo's database. Example: "2022-02-09T08:45:50.406032Z" - `collected_at` (string) The ISO-8601 timestamp when the data point was collected. Example: "2022-02-09T08:45:50.406032Z" - `report_date` (string) The date when the employment record report was generated, in format. Example: "2023-01-19" - `internal_identification` (string) Unique ID for user according to the institution. For IMSS and ISSSTE Mexico, this is the CURP. Example: "BLPM951331IONVGR54" - `personal_data` (object) Details regarding the personal information of the individual. - `personal_data.official_name` (string,null) The legal name of the individual. Example: "Bruce Banner del Torro" - `personal_data.first_name` (string,null) The first name of the individual. Example: "Bruce" - `personal_data.last_name` (string,null) The last name of the individual. Example: "Banner del Torro" - `personal_data.birth_date` (string,null) The date of birth of the individual, in format. Example: "2022-02-09" - `personal_data.entitlements` (object) Details regarding the benefits the individual is entitled to. - `personal_data.entitlements.entitled_to_health_insurance` (boolean) Indicates whether or not the individual is entitled to health insurance. Example: true - `personal_data.entitlements.entitled_to_company_benefits` (boolean) Indicates whether or not the individual is entitled to company benefits. Example: true - `personal_data.entitlements.valid_until` (string,null) Date until when the individual is covered by health insurance and/or company benefits. If the employee is currently working and no end date is required. - `personal_data.entitlements.status` (string) Indicates the employment status of the individual. We return one of the following responses: - - - - Enum: "EMPLOYED", "RETIRED", "UNEMPLOYED", "null" - `personal_data.document_ids` (array) Details regarding the individual's ID documents. - `personal_data.document_ids.document_type` (string,null) The type of document related to the individual. We return one of the following values: - - - Enum: "NSS", "CURP", "RFC" - `personal_data.document_ids.document_number` (string,null) The ID document's number (as a string). Example: "10277663582" - `personal_data.email` (string,null) The email address of the individual. Example: "bruce.banner@avengers.com" - `social_security_summary` (object,null) Details regarding the individual's social security contributions, according to the IMSS. >: For ISSSTE Mexico, this value will return . - `social_security_summary.weeks_redeemed` (integer,null) Number of weeks the individual needed to take out of their pension. - `social_security_summary.weeks_reinstated` (integer,null) Number of weeks the individual has paid back into their pension (), after having redeemed them previously. - `social_security_summary.weeks_contributed` (integer,null) Number of weeks the individual has contributed to their social security, based on the number of weeks the individual has worked according to IMSS. Example: 188 - `employment_records` (array) Details regarding the individual's employment history. - `employment_records.collected_at` (string) The ISO-8601 timestamp when the data point was collected. Example: "2020-04-23T21:32:55.336854+00:00" - `employment_records.employer` (string) The official name of the employer. >: For ISSSTE Mexico, this is the official name of the entity along with the entity that is responsible for managing the employee's information, separated by a semicolon (). For example: SECRETARIA DE EDUCACION PUBLICA (SEP);SECRETARIA DE EDUCACION PUBLICA (SEP). Example: "Batman Enterprises CDMX" - `employment_records.employer_id` (string,null) The official ID of the employer, according to the country. >: For ISSSTE Mexico, this value will return . Example: "780-BAT-88769-CDMX" - `employment_records.start_date` (string) Date when employment started, in format. Example: "2019-10-10" - `employment_records.end_date` (string,null) Date when employment finished, in format. >: This field will return for the user's current employment. Example: "2019-12-31" - `employment_records.weeks_employed` (integer) Number of weeks that the individual was employed. Example: 12 - `employment_records.state` (string,null) In what geographical state the individual was employed, according to the country. >: For ISSSTE Mexico, this value will return . Example: "DISTRITO FEDERAL" - `employment_records.most_recent_base_salary` (number) The most recent base salary the individual earned. - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year. - For ISSSTE Mexico, this value is calculated dividing by 30 (days), and excludes the individual's perks. Example: 762.54 - `employment_records.monthly_salary` (number) The monthly salary of the individual, including any additional perks. - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year. - For ISSSTE Mexico, this value is calculated excluding perks. - `employment_records.currency` (string) The three-letter currency code in which the salary is paid. Example: "MXN" - `employment_records.employment_status_updates` (array,null) Details regarding any employment changes of the individual. - `employment_records.employment_status_updates.event` (string,null) For IMSS Mexico, this is the event that caused the change in employment status or salary. We return one of the following values: - : The employee was either dismissed or resigned. - : The employee received a salary modification (increase or decrease). - : The employee was hired. - : The employee made a voluntary contribution to IMSS. - : The employee was on absent (such as on vacation). - : The employee was on sick leave. For ISSSTE Mexico, this is the information source regarding the change in employment status or salary. We return one of the following values: - : Indicates that the information was received from the . - : Indicates that the information was received from the central database, . - : Indicates that the information was received from an affiliate institution, . Enum: "DISMISSED_RESIGNED", "SALARY_MODIFICATION", "HIRED", "VOLUNTARY_CONTRIBUTION", "ABSENCE", "SICK_LEAVE", "NORMAL", "BDUTA_CERTIFICATE", "DYE_CERTIFICATE" - `employment_records.employment_status_updates.base_salary` (number) The base salary of the individual, current as of the . - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year. - For ISSSTE Mexico, this value is calculated excluding the individual's perks. Example: 1033.09 - `employment_records.employment_status_updates.update_date` (string) The date that the employment event occurred, in format. Example: "2021-09-01" - `employment_scores` (array,null) An array of scores. Each score provides an insight into employability and income generation potential in a given period. > : This field is only available for links created with Mexico's IMSS. For other institutions, this field will return . > : This field will return for employment records retrieved before 16-04-2024. For employment records generated before 16-04-2024, you'll need to make a new POST request to retrieve employment records to calculate the scores. Example: [{"score":722,"period":3,"version":"1.0.0"},{"score":612,"period":6,"version":"1.0.0"},{"score":570,"period":12,"version":"1.0.0"}] - `employment_scores.score` (integer,null) A score between 300 and 900 that provides an insight into employability and income generation potential. - A low score (closer to 300) could indicate lower predicted employability and income generation potential, suggesting potential challenges in securing employment or achieving higher income levels in the future. - A high score (closer to 900) could suggest a greater likelihood of securing employment and generating higher income levels. The score can return if the individual has no employment history. Example: 612 - `employment_scores.period` (integer) The number of months (in the future) that the score is calculated for. For example, a period of indicates that the score is calculated for the next months. > : At present Belvo calculates the score for 3, 6, and 12 months. Example: 6 - `employment_scores.version` (string) The version of our employment score model used to perform the calculation. Example: "1.0.0" - `files` (array,null) Additional PDF binary files relating to the individual's employment. - `files.type` (string) The title of the document. Example: "ReporteSemanasCotizadas_190123" - `files.value` (string,null) The PDF binary of the file (as a string). > : In our sandbox environment, this field will return . Example: "=PDF_BINARY=" ## Response 202 fields (application/json): - `request_id` (string) The unique ID for this request. We recommend you store this value to later identify which webhook event relates to an asynchronous request. Example: "b5d0106ac9cc43d5b36199fe831f6bbe" ## Response 403 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied. Example: "access_to_resource_denied" - `message` (string) A short description of the error. For errors, the description is: - . Example: "You don't have access to this resource." - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 408 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors. Example: "request_timeout" - `message` (string) A short description of the error. For errors, the description is: - . Example: "The request timed out, you can retry asking for less data by changing your query parameters" - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 428 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 428 token_required errors. Example: "token_required" - `message` (string) A short description of the error. For errors, the description is: - . Example: "A MFA token is required by the institution to login" - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb" - `session` (string) A 32-character unique ID of the login session (matching a regex pattern of: ). Example: "2675b703b9d4451f8d4861a3eee54449" - `expiry` (integer) Session duration time in seconds. Example: 9600 - `link` (string) Unique identifier created by Belvo, used to reference the current Link. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `token_generation_data` (object) Details on how to generate the token. - `token_generation_data.instructions` (string) Instructions for token generation. Example: "Use this code to generate the token" - `token_generation_data.type` (string) Type of the data to generate the token (QR code, numeric challenge). Example: "numeric" - `token_generation_data.value` (string) Value to use to generate the token. Example: "12345" - `token_generation_data.expects_user_input` (boolean) Indicates whether the user needs to provide input in order to complete the authentication. When set to , your user may need to: - confirm the login on another device - scan a QR code You will still need to make a PATCH call to complete the request. Example: true ## Response 500 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors. Example: "unexpected_error" - `message` (string) A short description of the error. For errors, the description is: - . Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution" - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb"