# List employments

## ▶️ Usage

With the List Employments method, you can:

1. [Required] List employments related to a specific link.id (using the link query parameter).
2. Get the details of a specific employment.id (using the id query parameter).

## 📖 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/br/employments/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string, required)
    The link.id you want to filter by.
    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

  - `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"]

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

  - `start_date` (string)
    Return employments that started on this date, in YYYY-MM-DD format.
    Example: "2022-05-05"

  - `start_date__gt` (string)
    Return employments that started after this date, in YYYY-MM-DD format.
    Example: "2022-05-06"

  - `start_date__gte` (string)
    Return employments that started on or after this date, in YYYY-MM-DD format.
    Example: "2022-05-04"

  - `start_date__lt` (string)
    Return employments that started before this date, in YYYY-MM-DD format.
    Example: "2022-03-02"

  - `start_date__lte` (string)
    Return employments that started on or before this date, in YYYY-MM-DD format.
    Example: "2022-03-01"

  - `start_date__range` (array)
    Return employments that started within these two dates, in YYYY-MM-DD,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"]

  - `end_date` (string)
    Return employments that finished on this date, in YYYY-MM-DD format.
    Example: "2022-05-05"

  - `end_date__gt` (string)
    Return employments that finished after this date, in YYYY-MM-DD format.
    Example: "2022-05-06"

  - `end_date__gte` (string)
    Return employments that finished on or after this date, in YYYY-MM-DD format.
    Example: "2022-05-04"

  - `end_date__lt` (string)
    Return employments that finished before this date, in YYYY-MM-DD format.
    Example: "2022-03-02"

  - `end_date__lte` (string)
    Return employments that finished on or before this date, in YYYY-MM-DD format.
    Example: "2022-03-01"

  - `end_date__range` (array)
    Return employments that finished within these two dates, in YYYY-MM-DD,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"]

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

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

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

  - `results.created_at` (string, required)
    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, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `results.start_date` (string, required)
    The employee's start date at the employer, in YYYY-MM-DD format.
    Example: "2022-01-01"

  - `results.end_date` (string,null, required)
    The employee's end date at the employer, in YYYY-MM-DD format. If null, the employee is still working at the employer.
    Example: "2023-01-01"

  - `results.employer_data` (object, required)
    Details regarding the employer.

  - `results.employer_data.name` (string, required)
    The name of the employer.
    Example: "Wayne Industries"

  - `results.employer_data.code` (string, required)
    The institution's unique code for the employer.
    Example: "49430669"

  - `results.employer_data.economic_activity` (string, required)
    The main economic activity the employer is involved in. For Brazil, this is the Classificação Nacional de Atividades Econômicas (CNAE) code.
    Example: "6421-2 - BANCOS COMERCIAIS"

  - `results.occupations` (array, required)
    The employee's occupations at the employer.

  - `results.occupations.start_date` (string, required)
    The date that the employee started the position, in YYYY-MM-DD format.
    Example: "2022-01-01"

  - `results.occupations.end_date` (string,null, required)
    The date that the employee stopped working in this position, in YYYY-MM-DD format. If null, this means that the employee is still holds this position.
    Example: "2023-01-01"

  - `results.occupations.description` (string, required)
    The position the employee held. For Brazil, this description must be according to the Ministry of Labour and listed in the Classificação Brasileira de Ocupações (CBO).
    Example: "ANALISTA DE PRODUTOS BANCARIOS"

  - `results.occupations.name` (string, required)
    The employees occupation, as provided by the employer.
    Example: "ANALISTA DE PRODUTOS BANCARIOS - 2525-40"

  - `results.occupations.locale` (string, required)
    Where the employee fufilled their duties. For Brazil, this can be either:
  -  Urbana (Urban)
  - Rural (Rural)
  - Não Identificado
  - null
    Example: "Urbana"

  - `results.salaries` (array, required)
    The salaries the employee received from the employer.

  - `results.salaries.base_amount` (number, required)
    The base amount of the salary, before any deductions or bonuses.
    Example: 1033.09

  - `results.salaries.retained_amount` (number, required)
    The amount retained by Brazil's Instituto Nacional do Seguro Social (INSS).
    Example: 0.01

  - `results.salaries.type` (string,null)
    The type of salary.

We return one of the following values:
  - REGULAR
  - THIRTEENTH
  - VOLUNTARY
  - RETIREMENT
  - null
    Enum: "REGULAR", "THIRTEENTH", "VOLUNTARY", "RETIREMENT", null

  - `results.salaries.month` (string, required)
    The month that the employee received their salary, in YYYY-MM format.
    Example: "2022-01"

  - `results.salaries.currency` (string, required)
    The three-letter currency code (ISO-4217).
    Example: "BRL"

## 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"