---
title: "List employments"
method: GET
path: "/api/br/employments/"
tags: ["Employments Brazil"]
---

# List employments

`GET /api/br/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 <a href="https://developers.belvo.com/docs/belvo-pagination-tips" target="_blank">Pagination Tips</a> 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 <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> article.

## Query parameters

- `link` string, uuid, required
- `page_size` integer
- `page` integer
- `id` string, uuid
- `id__in` string[]
- `link__in` string[]
- `omit` string
- `fields` string
- `start_date` string, date
- `start_date__gt` string, date
- `start_date__gte` string, date
- `start_date__lt` string, date
- `start_date__lte` string, date
- `start_date__range` string[]
- `end_date` string, date
- `end_date__gt` string, date
- `end_date__gte` string, date
- `end_date__lt` string, date
- `end_date__lte` string, date
- `end_date__range` string[]
- `created_at` string, date
- `created_at__gt` string, date
- `created_at__gte` string, date
- `created_at__lt` string, date
- `created_at__lte` string, date
- `created_at__range` string[]

## Response `200`

Ok

- object
  - `count` integer — The total number of results in your Belvo account.
  - `next` string, uri, nullable — 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`).
  - `previous` string, uri, nullable — The URL to the previous page of results. If there is no previous page, the value is `null`.
  - `results` EmploymentBrazil[] — Array of employment objects.
    - `id` string, uuid, required — Belvo's unique identifier for the current item.
    - `link` string, uuid, nullable, required — The `link.id` the data belongs to.
    - `created_at` string, date-time, required — The ISO-8601 timestamp of when the data point was created in Belvo's database.
    - `collected_at` string, date-time, required — The ISO-8601 timestamp when the data point was collected.
    - `start_date` string, date, required — The employee's start date at the employer, in `YYYY-MM-DD` format.
    - `end_date` string, date, nullable, required — The employee's end date at the employer, in `YYYY-MM-DD` format. If `null`, the employee is still working at the employer.
    - `employer_data` EmployerDataBrazil, required — Details regarding the employer.
      - `name` string, required — The name of the employer.
      - `code` string, required — The institution's unique code for the employer.
      - `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.
    - `occupations` OccupationBrazil[], required — The employee's occupations at the employer.
      - `start_date` string, date, required — The date that the employee started the position, in `YYYY-MM-DD` format.
      - `end_date` string, date, nullable, 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.
      - `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).
      - `name` string, required — The employees occupation, as provided by the employer.
      - `locale` string, required — Where the employee fufilled their duties. For Brazil, this can be either: - `Urbana` (Urban) - `Rural` (Rural) - `Não Identificado` - `null`
    - `salaries` SalaryBrazil[], required — The salaries the employee received from the employer.
      - `base_amount` number, float, required — The base amount of the salary, before any deductions or bonuses.
      - `retained_amount` number, float, required — The amount retained by Brazil's *Instituto Nacional do Seguro Social* (INSS).
      - `type` 'REGULAR' | 'THIRTEENTH' | 'VOLUNTARY' | 'RETIREMENT' | 'null', nullable — The type of salary. We return one of the following values: - `REGULAR` - `THIRTEENTH` - `VOLUNTARY` - `RETIREMENT` - `null`
      - `month` string, required — The month that the employee received their salary, in `YYYY-MM` format.
      - `currency` string, required — The three-letter currency code (ISO-4217).

## Other responses

- `401` — Unauthorized
- `403` — Access to Belvo API denied
- `404` — Not Found Error
- `408` — Request Timeout
- `500` — Unexpected Error

---

[API](https://skmtc.net/belvo/apis/belvo-api-docs.md) · [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/versions/3423c786ece5/schema)