---
title: "List employments"
method: GET
path: "/v1/employments"
tags: ["Employment Management"]
---

# List employments

`GET /v1/employments`

Lists all employments, except for the deleted ones.

This endpoint requires and returns country-specific data. The exact required and returned fields will
vary depending on which country the employment is in. To see the list of parameters for each country,
see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.

Please note that the compliance requirements for each country are subject to change according to local
laws. Given its continual updates, using Remote's [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid
compliance issues and to have the latest version of a country requirements.

If you are using this endpoint to build an integration, make sure you are dynamically collecting or
displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.

For more information on JSON Schemas, see the **How JSON Schemas work** documentation.

To learn how you can dynamically generate forms to display in your UI, see the documentation for
the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.

## Query parameters

- `company_id` string
- `email` string
- `status` string
- `employment_type` string
- `employment_model` 'global_payroll' | 'peo' | 'eor'
- `short_id` string
- `page` integer
- `page_size` integer

## Headers

- `Authorization` string, required

## Response `200`

Success

- ListEmploymentsResponse — Response schema listing many employments
  - `data` object
    - `current_page` integer — The current page among all of the total_pages
    - `employments` MinimalEmployment[]
      - `country` NullableCountry, nullable, required — A supported country on Remote
        - `alpha_2_code` string, required — The ISO 3166-1 alpha-2 country code (e.g., "PT").
        - `code` string, required — The ISO 3166-1 alpha-3 country code (e.g., "PRT"). This is the primary code used across the Remote API.
        - `contractor_products_available` string[] — Contractor product names available for this country
        - `country_subdivisions` CountrySubdivision[], nullable — Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.
          - `code` string — The ISO 3166-2 subdivision code (e.g., "PT-11" for Lisboa).
          - `name` string, required — The subdivision's name (e.g., "Lisboa", "California").
          - `subdivision_type` string — The type of subdivision (e.g., "District", "State", "Province").
        - `employment_agreement_preview_available` boolean — Whether an Employment Agreement preview is available for this country.
        - `eor_onboarding` boolean — Whether EOR (Employer of Record) onboarding is available in this country.
        - `locked_benefits` string — When benefit plan selections become locked for this country (e.g., "after_first_hire" means benefits cannot be changed after the first employee is hired).
        - `name` string, required — The country's full English name.
        - `region` string — The geographic region the country belongs to (e.g., "Europe", "Asia", "Americas").
        - `subregion` string, nullable — The geographic subregion (e.g., "Southern Europe", "Southeast Asia"). Null for some countries.
        - `supported_json_schemas` string[] — The list of JSON schema form names available for this country (e.g., "address_details", "contract_details"). Use these with the Show form schema endpoint to get country-specific field requirements.
      - `department` string, nullable — Name of related department, if any. Otherwise, null.
      - `department_id` string, uuid, nullable — Unique ID of related department, if any. Otherwise, null.
      - `employment_lifecycle_stage` 'employment_creation' | 'employee_self_enrollment' | 'right_to_work_check' | 'contract_signing' | 'remote_enrollment' | 'onboarded' | 'offboarded', required — The stage of employment lifecycle. When it's `onboarded` means the employee is ready to commence or has already commenced.
      - `employment_model` 'eor' | 'peo' | 'global_payroll', nullable, required — The employment model. `eor` (Employer of Record), `peo` (Professional Employer Organization), or `global_payroll`.
      - `external_id` string, nullable, required — A unique reference code for the employment record in a non-Remote system. While uniqueness is recommended, it is not strictly enforced within Remote's system.
      - `full_name` string, required — The employee's full name.
      - `id` string, required — The unique identifier (UUID) of the employment.
      - `job_title` string, required — The employee's job title.
      - `login_email` string, email, required — The email the employee uses to log in to Remote.
      - `personal_email` string, email, required — The employee's personal email address.
      - `short_id` string, required — Unique short identifier for the employment, automatically generated and visible in select areas of the Remote platform. Not intended as a replacement for the employment `id` field.
      - `status` 'active' | 'created' | 'pre_hire' | 'created_awaiting_reserve' | 'created_reserve_paid' | 'initiated' | 'invited' | 'pending' | 'review' | 'job_title_review' | 'pending_post_self_enrollment_actions' | 'offboarding' | 'archived' | 'deleted', required — The current status of the employment record. - `active`: The employee is fully onboarded and actively working. - `created`: The employment has been created but onboarding has not started. - `pre_hire`: A pre-hire employment record, created before formal onboarding begins. - `created_awaiting_reserve`: The employment is created but waiting for a risk reserve deposit to be paid. - `created_reserve_paid`: The risk reserve has been paid and the employment can proceed with onboarding. - `initiated`: Onboarding has been started by the employer. - `invited`: The employee has been invited to complete their self-enrollment on Remote. - `pending`: The employment is pending review or further action before it can become active. - `review`: The employment is under review by Remote (e.g., contract or compliance review). - `archived`: The employment has been terminated or offboarded. - `deleted`: The employment record has been deleted.
      - `type` 'employee' | 'contractor' | 'direct_employee' | 'global_payroll_employee', required — The type of employment.
      - `work_address_details` object, required — Work address information. Its properties may vary depending on the country.
      - `work_email` string, email, nullable, required — The employee's work email address. Null if not set.
    - `total_count` integer — The total number of records in the result
    - `total_pages` integer — The total number of pages the user can go through

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Unprocessable Entity

---

[API](https://skmtc.net/remote-com/apis/remote.md) · [All operations](https://skmtc.net/remote-com/apis/remote/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/remote-com/remote/revisions/7e6a0c61ac82/schema)