Remote Employment Management API
The Employment Management API from Remote — 9 operation(s) for employment management.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Employment Management API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Employment Management
paths:
/v1/employments:
get:
callbacks: {}
deprecated: false
description: '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.
'
operationId: get_v1_employments
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Company ID
example: 93t3j-company-id-9suej43
in: query
name: company_id
required: false
schema:
type: string
- description: Filters the results by employments whose login email matches the value
example: anna@example.com
in: query
name: email
required: false
schema:
type: string
- description: 'Filters the results by employments whose status matches the value.
Supports multiple values separated by commas.
Also supports the value `incomplete` to get all employments that are not onboarded yet.
'
in: query
name: status
required: false
schema:
type: string
- description: Filters the results by employments whose employment product type matches the value
example: contractor
in: query
name: employment_type
required: false
schema:
type: string
- description: 'Filters the results by employments whose employment model matches the value.
Possible values: `global_payroll`, `peo`, `eor`
'
example: global_payroll
in: query
name: employment_model
required: false
schema:
enum:
- global_payroll
- peo
- eor
type: string
- description: Filters the results by the employment's short ID. Returns at most one result.
example: aB1cD2
in: query
name: short_id
required: false
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
default: 1
minimum: 1
type: integer
- description: Number of items per page
example: 20
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListEmploymentsResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
summary: List employments
tags:
- Employment Management
post:
callbacks: {}
deprecated: false
description: 'Creates an employment. We support creating employees and contractors.
## Global Payroll Employees
To create a Global Payroll employee, pass `global_payroll_employee` as the `type` parameter,
and provide the id of the specific legal entity that the employee will be engaged by and billed to as the `engaged_by_legal_entity_id` parameter.
## HRIS Employees
To create a HRIS employee, pass `hris` as the `type` parameter.
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.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v1_employments
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Version of the form schema
example: 1
in: query
name: json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentCreateParams'
description: Employment params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentCreationResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Create employment
tags:
- Employment Management
/v1/employments/{employment_id}:
get:
callbacks: {}
deprecated: false
description: 'Shows all the information of an employment.
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.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |
'
operationId: get_v1_employments_employment_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
- description: Wether files should be excluded
example: 'true'
in: query
name: exclude_files
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentShowResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
summary: Show employment
tags:
- Employment Management
patch:
callbacks: {}
deprecated: false
description: 'Updates an employment.
**For `created` employments:** You can change all basic params and onboarding tasks or perform a per onboarding task update. You can also update basic_information.
**For `active` employments:** You can update the manager (`manager_id` field), emergency_contact_details, address_details and work_email.
**For `invited` employments:** You can update the work_email.
After onboarding, only a limited set of employment data will be available for updates, such as `emergency_contact_details`.
If you want to provide additional information for an employment, please make sure to do so **before** the employee is invited.
We block updates to some employment data because employees need to agree to amendments in certain cases, such as when there are changes to their contract_details.
Currently, these amendments can only be done through the Remote UI.
It is possible to update the `external_id` of the employment for all employment statuses.
## Global Payroll Employees
To update a Global Payment employment your input data must comply with the global payroll json schemas.
**For `active` employments:** In addition to the above list, you can update personal_details.
## Direct Employees
To update an HRIS employment your input data must comply with the HRIS json schemas.
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.
Please contact Remote if you need to update contractors via API since it''s currently not supported.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: patch_v1_employments_employment_id (2)
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Version of the address_details form schema
example: 1
in: query
name: address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the administrative_details form schema
example: 1
in: query
name: administrative_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the bank_account_details form schema
example: 1
in: query
name: bank_account_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the employment_basic_information form schema
example: 1
in: query
name: employment_basic_information_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the billing_address_details form schema
example: 1
in: query
name: billing_address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the contract_details form schema
example: 1
in: query
name: contract_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the emergency_contact_details form schema
example: 1
in: query
name: emergency_contact_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the personal_details form schema
example: 1
in: query
name: personal_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the pricing_plan_details form schema
example: 1
in: query
name: pricing_plan_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
- description: Skips the dynamic benefits part of the schema if set. To be used when benefits are set via its own API.
example: true
in: query
name: skip_benefits
required: false
schema:
type: boolean
- description: Complementary action(s) to perform when creating an employment.
example: no_invite
in: query
name: actions
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentFullParams'
description: Employment params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Update employment
tags:
- Employment Management
put:
callbacks: {}
deprecated: false
description: 'Updates an employment.
**For `created` employments:** You can change all basic params and onboarding tasks or perform a per onboarding task update. You can also update basic_information.
**For `active` employments:** You can update the manager (`manager_id` field), emergency_contact_details, address_details and work_email.
**For `invited` employments:** You can update the work_email.
After onboarding, only a limited set of employment data will be available for updates, such as `emergency_contact_details`.
If you want to provide additional information for an employment, please make sure to do so **before** the employee is invited.
We block updates to some employment data because employees need to agree to amendments in certain cases, such as when there are changes to their contract_details.
Currently, these amendments can only be done through the Remote UI.
It is possible to update the `external_id` of the employment for all employment statuses.
## Global Payroll Employees
To update a Global Payment employment your input data must comply with the global payroll json schemas.
**For `active` employments:** In addition to the above list, you can update personal_details.
## Direct Employees
To update an HRIS employment your input data must comply with the HRIS json schemas.
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.
Please contact Remote if you need to update contractors via API since it''s currently not supported.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: patch_v1_employments_employment_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Version of the address_details form schema
example: 1
in: query
name: address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the administrative_details form schema
example: 1
in: query
name: administrative_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the bank_account_details form schema
example: 1
in: query
name: bank_account_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the employment_basic_information form schema
example: 1
in: query
name: employment_basic_information_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the billing_address_details form schema
example: 1
in: query
name: billing_address_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the contract_details form schema
example: 1
in: query
name: contract_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the emergency_contact_details form schema
example: 1
in: query
name: emergency_contact_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the personal_details form schema
example: 1
in: query
name: personal_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Version of the pricing_plan_details form schema
example: 1
in: query
name: pricing_plan_details_json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: path
name: employment_id
required: true
schema:
type: string
- description: Skips the dynamic benefits part of the schema if set. To be used when benefits are set via its own API.
example: true
in: query
name: skip_benefits
required: false
schema:
type: boolean
- description: Complementary action(s) to perform when creating an employment.
example: no_invite
in: query
name: actions
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentFullParams'
description: Employment params
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentResponse'
description: Succ
# --- truncated at 32 KB (181 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-employment-management-api-openapi.yml