Remote Contracts API
The Contracts API from Remote — 14 operation(s) for contracts.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Contracts API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Contracts
paths:
/v1/contract-amendments/schema:
get:
callbacks: {}
deprecated: false
description: 'Returns the json schema of the `contract_amendment` form for a specific employment.
This endpoint requires a company access token, as forms are dependent on certain
properties of companies and their current employments.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View contract amendments (`contract_amendment:read`) | Manage contract amendments (`contract_amendment:write`) |
'
operationId: get_v1_contract-amendments_schema
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: The ID of the employment concerned by the contract amendment request.
example: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d
in: query
name: employment_id
required: true
schema:
type: string
- description: Country code according to ISO 3-digit alphabetic codes.
example: CAN
in: query
name: country_code
required: true
schema:
type: string
- description: Name of the desired form
example: contract_amendment
in: query
name: form
required: false
schema:
enum:
- contract_amendment
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
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractAmendmentFormResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- contract_amendment:read
- contract_amendment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- contract_amendment:read
- contract_amendment:write
- employments
- all:write
- all:read
summary: Show form schema
tags:
- Contracts
/v1/probation-completion-letter/{id}:
get:
callbacks: {}
deprecated: false
description: 'Show a single probation completion letter.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View probation documents (`probation_document:read`) | Manage probation documents (`probation_document:write`) |
'
operationId: get_v1_probation-completion-letter_id
parameters:
- description: probation completion letter ID
example: 93t3j-probation_completion_letter_id-9suej43
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProbationCompletionLetterResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- probation_document:read
- probation_document:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- probation_document:read
- probation_document:write
- employment_documents
- all:write
- all:read
summary: Show probation completion letter
tags:
- Contracts
/v1/employments/{employment_id}/contract-documents:
get:
callbacks: {}
deprecated: false
description: 'Only contractor employment types are supported. Lists contract documents for a specific employment with pagination, filtering by status, and sorted by updated_at descending (latest first).
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |
'
operationId: get_v1_employments_employment_id_contract-documents
parameters:
- description: Employment ID
example: 1a716003-ae89-4810-aa00-25df6e799162
in: path
name: employment_id
required: true
schema:
type: string
- description: Filter by contract document statuses
example:
- finished
- awaiting_signatures
in: query
name: statuses
required: false
schema:
items:
$ref: '#/components/schemas/ContractorContractDocumentStatus'
type: array
- description: Exclude contract documents with specific statuses
example:
- draft
in: query
name: except_statuses
required: false
schema:
items:
$ref: '#/components/schemas/ContractorContractDocumentStatus'
type: array
- 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/IndexContractDocumentsResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- document:read
- document:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- document:read
- document:write
- employment_documents
- all:write
- all:read
summary: List contract documents for an employment
tags:
- Contracts
/v1/probation-completion-letter:
post:
callbacks: {}
deprecated: false
description: 'Create a new probation completion letter request.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | - | Manage probation documents (`probation_document:write`) |
'
operationId: post_v1_probation-completion-letter
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProbationCompletionLetterParams'
description: Work Authorization Request
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProbationCompletionLetterResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- probation_document:write
- employment_documents
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- probation_document:write
- employment_documents
- all:write
summary: Create probation completion letter
tags:
- Contracts
/v1/probation-extensions:
post:
callbacks: {}
deprecated: false
description: 'Create a probation extension request.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | - | Manage probation documents (`probation_document:write`) |
'
operationId: post_v1_probation-extensions
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProbationExtensionParams'
description: ProbationExtension
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProbationExtensionResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- probation_document:write
- employment_documents
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- probation_document:write
- employment_documents
- all:write
summary: Create Probation Extension
tags:
- Contracts
/v1/contract-amendments:
get:
callbacks: {}
deprecated: false
description: 'List Contract Amendment requests.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View contract amendments (`contract_amendment:read`) | Manage contract amendments (`contract_amendment:write`) |
'
operationId: get_v1_contract-amendments
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
in: query
name: employment_id
required: false
schema:
type: string
- description: Contract Amendment status
in: query
name: status
required: false
schema:
$ref: '#/components/schemas/ContractAmendmentStatus'
- 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/ListContractAmendmentResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- contract_amendment:read
- contract_amendment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- contract_amendment:read
- contract_amendment:write
- employments
- all:write
- all:read
summary: List Contract Amendment
tags:
- Contracts
post:
callbacks: {}
deprecated: false
description: 'Creates a Contract Amendment request.
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 [Contract Amendments](#tag/Contract-Amendments) 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 contract amendments (`contract_amendment:write`) |
'
operationId: post_v1_contract-amendments
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/CreateContractAmendmentParams'
description: Contract Amendment
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractAmendmentResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- contract_amendment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- contract_amendment:write
- employments
- all:write
summary: Create Contract Amendment
tags:
- Contracts
/v1/employments/{employment_id}/employment-agreement/download:
get:
callbacks: {}
deprecated: false
description: 'Downloads a PDF of the auto-generated Employment Agreement for an employment.
The document is rendered as a draft (no signatures) and is not persisted. EA preview is only
available for countries that have a published Employment Agreement automation template — see the
`employment_agreement_preview_available` flag on the [Countries](#tag/Countries) endpoint.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |
'
operationId: get_v1_employments_employment_id_employment-agreement_download
parameters:
- description: Employment ID
example: 1a716003-ae89-4810-aa00-25df6e799162
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericFile'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- document:read
- document:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- document:read
- document:write
- employment_documents
- all:write
- all:read
summary: Download the Employment Agreement for an employment
tags:
- Contracts
/v1/contract-amendments/{id}:
get:
callbacks: {}
deprecated: false
description: 'Show a single Contract Amendment request.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View contract amendments (`contract_amendment:read`) | Manage contract amendments (`contract_amendment:write`) |
'
operationId: get_v1_contract-amendments_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: Contract amendment request ID
example: 93t3j-contract_amendment_id-9suej43
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractAmendmentResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- contract_amendment:read
- contract_amendment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- contract_amendment:read
- contract_amendment:write
- employments
- all:write
- all:read
summary: Show Contract Amendment
tags:
- Contracts
/v1/employments/{employment_id}/contract-eligibility:
post:
callbacks: {}
deprecated: false
description: 'Create contract eligibility for an employment.
This will create a new contract eligibility for the employment.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | - | Manage contract eligibility (`contract_eligibility:write`) |
'
operationId: post_v1_employments_employment_id_contract-eligibility
parameters:
- description: Employment ID
example: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d
in: path
name: employment_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContractEligibilityParams'
description: Contract Eligibility Create Parameters
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'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
- contract_eligibility:write
- employment_documents
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- contract_eligibility:write
- employment_documents
- all:write
summary: Create contract eligibility
tags:
- Contracts
/v1/contract-amendments/automatable:
post:
callbacks: {}
deprecated: false
description: 'Check if a contract amendment request is automatable.
If the contract amendment request is automatable, then after submission, it will instantly amend the employee''s contract
and send them an updated document.
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 [Contract Amendments](#tag/Contract-Amendments) 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 contract amendments (`contract_amendment:write`) |
'
operationId: post_v1_contract-amendments_automatable
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/CreateContractAmendmentParams'
description: Contract Amendment
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractAmendmentAutomatableResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- contract_amendment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- contract_amendment:write
- employments
- all:write
summary: Automatable Contract Amendment
tags:
- Contracts
/v1/employment-contracts/{employment_id}/pending-changes:
get:
callbacks: {}
deprecated: false
description: 'Get all the pending changes (waiting for aproval or signature) for the employment contract.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View contracts (`contract:read`) | - |
'
operationId: get_v1_employment-contracts_employment_id_pending-changes
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
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmploymentContractPendingChangesResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-contracts-api-openapi.yml