# List employment records

## ▶️ Usage

With the List Employment Records method, you can:

1. List employment records related to a specific link.id (using the link query parameter).
2. Get the details of a specific employment-record.id (using the id query parameter).
3. [Not Recommended] List all employment records related to your Belvo account (without using any query parameters).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

Endpoint: GET /api/employment-records/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string)
    The link.id you want to filter by.

ℹ️ We highly recommend adding the link.id filter in order to improve your performance.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `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.

  - `id` (string)
    Return information only for this resource id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `id__in` (array)
    Return information for these resource ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `link__in` (array)
    Return results only for these link.ids.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `internal_identification` (string)
    The internal_identification you want to filter by.
    Example: "BLPM951331IONVGR54"

  - `internal_identification__in` (array)
    One or more internal_identifications you want to filter by.
    Example: ["BLPM951331IONVGR54"]

  - `collected_at` (string)
    Return items that were retrieved from the institution on this date (YYYY-MM-DD or full ISO-8601 timestamp).
    Example: "2022-05-01"

  - `collected_at__gt` (string)
    Return items that were retrieved from the institution after this date (YYYY-MM-DD or full ISO-8601 timestamp).
    Example: "2022-05-05"

  - `collected_at__gte` (string)
    Return items that were retrieved from the institution after or on this date (YYYY-MM-DD or full ISO-8601 timestamp).
    Example: "2022-05-04"

  - `collected_at__lt` (string)
    Return items that were retrieved from the institution before this date (YYYY-MM-DD or full ISO-8601 timestamp).
    Example: "2022-04-01"

  - `collected_at__lte` (string)
    Return items that were retrieved from the institution before or on this date (YYYY-MM-DD or full ISO-8601 timestamp).
    Example: "2022-03-30"

  - `collected_at__range` (array)
    Return items that were retrieved from the institution between two dates (YYYY-MM-DD or full ISO-8601 timestamp). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of employment record objects.

  - `results.id` (string)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `results.link` (string,null)
    The link.id the data belongs to.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `results.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"

  - `results.collected_at` (string)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `results.report_date` (string)
    The date when the employment record report was generated, in YYYY-MM-DD format.
    Example: "2023-01-19"

  - `results.internal_identification` (string)
    Unique ID for user according to the institution. For IMSS and ISSSTE Mexico, this is the CURP.
    Example: "BLPM951331IONVGR54"

  - `results.personal_data` (object)
    Details regarding the personal information of the individual.

  - `results.personal_data.official_name` (string,null)
    The legal name of the individual.
    Example: "Bruce Banner del Torro"

  - `results.personal_data.first_name` (string,null)
    The first name of the individual.
    Example: "Bruce"

  - `results.personal_data.last_name` (string,null)
    The last name of the individual.
    Example: "Banner del Torro"

  - `results.personal_data.birth_date` (string,null)
    The date of birth of the individual, in YYYY-MM-DD format.
    Example: "2022-02-09"

  - `results.personal_data.entitlements` (object)
    Details regarding the benefits the individual is entitled to.

  - `results.personal_data.entitlements.entitled_to_health_insurance` (boolean)
    Indicates whether or not the individual is entitled to health insurance.
    Example: true

  - `results.personal_data.entitlements.entitled_to_company_benefits` (boolean)
    Indicates whether or not the individual is entitled to company benefits.
    Example: true

  - `results.personal_data.entitlements.valid_until` (string,null)
    Date until when the individual is covered by health insurance and/or company benefits. If null the employee is currently working and no end date is required.

  - `results.personal_data.entitlements.status` (string)
    Indicates the employment status of the individual. We return one of the following responses:
  
  - EMPLOYED
  - RETIRED
  - UNEMPLOYED
  - null
    Enum: "EMPLOYED", "RETIRED", "UNEMPLOYED", "null"

  - `results.personal_data.document_ids` (array)
    Details regarding the individual's ID documents.

  - `results.personal_data.document_ids.document_type` (string,null)
    The type of document related to the individual. We return one of the following values:

  - NSS
  - CURP
  - RFC
    Enum: "NSS", "CURP", "RFC"

  - `results.personal_data.document_ids.document_number` (string,null)
    The ID document's number (as a string).
    Example: "10277663582"

  - `results.personal_data.email` (string,null)
    The email address of the individual.
    Example: "bruce.banner@avengers.com"

  - `results.social_security_summary` (object,null)
    Details regarding the individual's social security contributions, according to the IMSS.

>Note: For ISSSTE Mexico, this value will return null.

  - `results.social_security_summary.weeks_redeemed` (integer,null)
    Number of weeks the individual needed to take out of their pension.

  - `results.social_security_summary.weeks_reinstated` (integer,null)
    Number of weeks the individual has paid back into their pension (AFORE), after having redeemed them previously.

  - `results.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

  - `results.employment_records` (array)
    Details regarding the individual's employment history.

  - `results.employment_records.employer` (string)
    The official name of the employer.

>Note: 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"

  - `results.employment_records.employer_id` (string,null)
    The official ID of the employer, according to the country.

>Note: For ISSSTE Mexico, this value will return null.
    Example: "780-BAT-88769-CDMX"

  - `results.employment_records.start_date` (string)
    Date when employment started, in YYYY-MM-DD format.
    Example: "2019-10-10"

  - `results.employment_records.end_date` (string,null)
    Date when employment finished, in YYYY-MM-DD format.

>Note: This field will return null for the user's current employment.
    Example: "2019-12-31"

  - `results.employment_records.weeks_employed` (integer)
    Number of weeks that the individual was employed.
    Example: 12

  - `results.employment_records.state` (string,null)
    In what geographical state the individual was employed, according to the country.

>Note: For ISSSTE Mexico, this value will return null.
    Example: "DISTRITO FEDERAL"

  - `results.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 monthly_salary by 30 (days), and excludes the individual's perks.
    Example: 762.54

  - `results.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.
    Example: 23193.925

  - `results.employment_records.currency` (string)
    The three-letter currency code in which the salary is paid.
    Example: "MXN"

  - `results.employment_records.employment_status_updates` (array,null)
    Details regarding any employment changes of the individual.

  - `results.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:
  
  - DISMISSED_RESIGNED: The employee was either dismissed or resigned.
  - SALARY_MODIFICATION: The employee received a salary modification (increase or decrease).
  - HIRED: The employee was hired.
  - VOLUNTARY_CONTRIBUTION: The employee made a voluntary contribution to IMSS.
  - ABSENCE: The employee was on absent (such as on vacation).
  - SICK_LEAVE: 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:

  - NORMAL: Indicates that the information was received from the Instituto de Seguridad y Servicios Sociales de los Trabajadores del Estado (ISSSTE).
  - BDUTA_CERTIFICATE: Indicates that the information was received from the central database, Base de Datos Única de Trabajadores Activos (BDUTA).
  - DYE_CERTIFICATE: Indicates that the information was received from an affiliate institution, Dependencia y Entidad (DYE).
    Enum: "DISMISSED_RESIGNED", "SALARY_MODIFICATION", "HIRED", "VOLUNTARY_CONTRIBUTION", "ABSENCE", "SICK_LEAVE", "NORMAL", "BDUTA_CERTIFICATE", "DYE_CERTIFICATE"

  - `results.employment_records.employment_status_updates.base_salary` (number)
    The base salary of the individual, current as of the update_date.

  - 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

  - `results.employment_records.employment_status_updates.update_date` (string)
    The date that the employment event occurred, in YYYY-MM-DD format.
    Example: "2021-09-01"

  - `results.employment_scores` (array,null)
    An array of employment_record scores. Each score provides an insight into employability and income generation potential in a given period.

> Note 1: This field is only available for links created with Mexico's IMSS. For other institutions, this field will return null.

> Note 2: This field will return null 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"}]

  - `results.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 null if the individual has no employment history.
    Example: 612

  - `results.employment_scores.period` (integer)
    The number of months (in the future) that the score is calculated for.

For example, a period of 6 indicates that the score is calculated for the next 6 months.

> Note: At present Belvo calculates the score for 3, 6, and 12 months.
    Example: 6

  - `results.employment_scores.version` (string)
    The version of our employment score model used to perform the calculation.
    Example: "1.0.0"

  - `results.files` (array,null)
    Additional PDF binary files relating to the individual's employment.

  - `results.files.type` (string)
    The title of the document.
    Example: "ReporteSemanasCotizadas_190123"

  - `results.files.value` (string,null)
    The PDF binary of the file (as a string).

> Note: In our sandbox environment, this field will return null.
    Example: "=PDF_BINARY="

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) 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 access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    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: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). 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 (request_timeout) 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 request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    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: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) 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 unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    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: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"