API docs by Redocly

Remote API (0.1.0)

Download OpenAPI specification:Download

Offboarding

offboarding.done Deprecated Webhook

This event is triggered when an offboarding request is done.

Deprecated since April 2024 in favour of offboarding.submitted_to_payroll webhook.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
offboarding_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "offboarding.done",
  • "offboarding_request_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

offboarding.completed Webhook

This event is triggered when an offboarding request is completed.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
offboarding_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "offboarding.completed",
  • "offboarding_request_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

offboarding.submitted_to_payroll Webhook

This event is triggered when an offboarding request has been submitted to payroll.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
offboarding_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "offboarding.submitted_to_payroll",
  • "offboarding_request_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

offboarding.review_started Webhook

This event is triggered whenever an offboarding request starts being reviewed.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
offboarding_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "offboarding.review_started",
  • "offboarding_request_id": "ba310525-9282-40c9-8977-14d844bf891a"
}

offboarding.deleted Webhook

This event is triggered whenever an offboarding request is deleted.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
offboarding_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "offboarding.deleted",
  • "offboarding_request_id": "ba310525-9282-40c9-8977-14d844bf891a"
}

offboarding.submitted Webhook

This event is triggered when an offboarding request is submitted.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
offboarding_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "offboarding.submitted",
  • "offboarding_request_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

List Offboarding

Lists Offboarding requests.

Authorizations:
OAuth2
query Parameters
employment_id
string
Example: employment_id=93t3j-employment-id-9suej43

Filter by Employment ID

type
string
Example: type=paid

Filter by offboarding type

include_confidential
string
Example: include_confidential=true

By default, the results do not include confidential termination requests. Send include_confidential=true to include confidential requests in the response.

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "offboardings": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Create Offboarding

Creates an Offboarding request.

Authorizations:
OAuth2
Request Body schema: application/json

Offboarding

employment_id
required
string
required
object (TerminationDetailsParams)
type
required
string
Value: "termination"

The type of the offboarding request. For now, only termination is allowed.

Responses

Request samples

Content type
application/json
{
  • "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
  • "termination_details": {
    },
  • "type": "termination"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show Offboarding

Shows an Offboarding request.

Authorizations:
OAuth2
path Parameters
id
required
string

Offboarding request ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Incentives

incentive.deleted Webhook

This event is triggered whenever an incentive is deleted.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
incentive_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "incentive.deleted",
  • "incentive_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

incentive.updated Webhook

This event is triggered whenever an incentive is updated.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
incentive_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "incentive.updated",
  • "incentive_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

incentive.paid Webhook

This event is triggered whenever an incentive is paid

Request Body schema: application/json
event_type
required
string
employment_id
required
string
incentive_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2610f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "incentive.paid",
  • "incentive_id": "0078fcb5-b669-4e4a-b963-2a47744e75a1"
}

incentive.created Webhook

This event is triggered when an incentive is created

Request Body schema: application/json
event_type
string
employment_id
string
incentive_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "incentive.created",
  • "incentive_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

incentive.processing_started Webhook

This event is triggered when an incentive has its processing started

Request Body schema: application/json
event_type
string
employment_id
string
incentive_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "incentive.processing_started",
  • "incentive_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

List Incentives

Lists all Incentives of a company

Authorizations:
OAuth2
query Parameters
employment_id
string
Example: employment_id=93t3j-employment-id-9suej43

Filter by Employment ID

status
string
Example: status=paid

Filter by Incentive status

recurring_incentive_id
string
Example: recurring_incentive_id=2f900aaf-4952-4ec4-ac7c-2b917a2b4da9

Filter by Recurring Incentive id

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "incentives": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Create Incentive

Creates an Incentive.

Incentives use the currency of the employment specified provided in the employment_id field.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Incentive

amount
required
integer

The amount (in the currency of the employment) to be given to the employee.

This field accepts fractional amounts as well. However to avoid precision issues and errors that can arise from storing fractional amounts, the Remote API only accepts currencies and their fractional amounts as integers. This means you should append fractional amounts to the end of the amount you're passing in with this field.

For example, if the incentive you're offering is EUR 500.25, you would specify 50025 as the amount for this field.

amount_tax_type
required
string (AmountTaxType)
Enum: "gross" "net"

Whether the amount given accounts for taxes or not.

gross indicates that the amount given is the amount to be paid before taxes are subtracted.

net indicates that the amount given is the amount which will be paid to the employee after taxes. Remote will gross this up to ensure the taxes are included and employee receives the amount requested without further reduction.

effective_date
required
string <date>

The date at which the incentive should take effect.

Note that the incentive is not paid out on the effective date, but during the next payroll cycle. The effective date determines which payroll cycle the incentive will be paid out in.

The effective date needs to be today or a future date.

Note for recurring incentives: since the months don't have the same amount of days, if day of month of effective_date is one of [28, 29, 30, 31] it will be transformed to the last day of each month, avoiding the possibility of skipping a month in the recurrence.

note
string or null
employment_id
required
string
type
required
string
Enum: "acting_up_allowance" "allowance" "car_allowance" "health_and_wellness_allowance" "internet_allowance" "meal_allowance" "on_call_allowance" "parenthood_allowance" "phone_allowance" "relocation_allowance" "travel_allowance" "work_from_home_allowance" "bonus" "holiday_bonus" "referral_bonus" "retention_bonus" "commission" "other" "overtime" "stipend" "signing_bonus"

Responses

Request samples

Content type
application/json
{
  • "amount": 50000,
  • "amount_tax_type": "net",
  • "effective_date": "2021-12-20",
  • "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
  • "note": "Bonus for moving start date to an earlier date",
  • "type": "signing_bonus"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an Incentive

Delete an incentive.

one_time incentives that have the following status CANNOT be deleted:

  • processing
  • paid
Authorizations:
OAuth2
path Parameters
id
required
string

Incentive ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show Incentive

Show an Incentive's details

Authorizations:
OAuth2
path Parameters
id
required
string

Incentive ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Incentive

Updates an Incentive.

Incentives use the currency of the employment specified provided in the employment_id field.

The API doesn't support updating paid incentives.

Authorizations:
OAuth2
path Parameters
id
required
string

Incentive ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Incentive

amount
integer

The amount (in the currency of the employment) to be given to the employee.

This field accepts fractional amounts as well. However to avoid precision issues and errors that can arise from storing fractional amounts, the Remote API only accepts currencies and their fractional amounts as integers. This means you should append fractional amounts to the end of the amount you're passing in with this field.

For example, if the incentive you're offering is EUR 500.25, you would specify 50025 as the amount for this field.

amount_tax_type
string (AmountTaxType)
Enum: "gross" "net"

Whether the amount given accounts for taxes or not.

gross indicates that the amount given is the amount to be paid before taxes are subtracted.

net indicates that the amount given is the amount which will be paid to the employee after taxes. Remote will gross this up to ensure the taxes are included and employee receives the amount requested without further reduction.

effective_date
string <date>

The date at which the incentive should take effect.

Note that the incentive is not paid out on the effective date, but during the next payroll cycle. The effective date determines which payroll cycle the incentive will be paid out in.

The effective date needs to be today or a future date.

Note for recurring incentives: since the months don't have the same amount of days, if day of month of effective_date is one of [28, 29, 30, 31] it will be transformed to the last day of each month, avoiding the possibility of skipping a month in the recurrence.

note
string or null
type
string

A valid type according to the payment frequency

Responses

Request samples

Content type
application/json
{
  • "amount": 50000,
  • "amount_tax_type": "net",
  • "effective_date": "2021-12-20",
  • "note": "Bonus for moving start date to an earlier date",
  • "type": "signing_bonus"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Incentive

Updates an Incentive.

Incentives use the currency of the employment specified provided in the employment_id field.

The API doesn't support updating paid incentives.

Authorizations:
OAuth2
path Parameters
id
required
string

Incentive ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Incentive

amount
integer

The amount (in the currency of the employment) to be given to the employee.

This field accepts fractional amounts as well. However to avoid precision issues and errors that can arise from storing fractional amounts, the Remote API only accepts currencies and their fractional amounts as integers. This means you should append fractional amounts to the end of the amount you're passing in with this field.

For example, if the incentive you're offering is EUR 500.25, you would specify 50025 as the amount for this field.

amount_tax_type
string (AmountTaxType)
Enum: "gross" "net"

Whether the amount given accounts for taxes or not.

gross indicates that the amount given is the amount to be paid before taxes are subtracted.

net indicates that the amount given is the amount which will be paid to the employee after taxes. Remote will gross this up to ensure the taxes are included and employee receives the amount requested without further reduction.

effective_date
string <date>

The date at which the incentive should take effect.

Note that the incentive is not paid out on the effective date, but during the next payroll cycle. The effective date determines which payroll cycle the incentive will be paid out in.

The effective date needs to be today or a future date.

Note for recurring incentives: since the months don't have the same amount of days, if day of month of effective_date is one of [28, 29, 30, 31] it will be transformed to the last day of each month, avoiding the possibility of skipping a month in the recurrence.

note
string or null
type
string

A valid type according to the payment frequency

Responses

Request samples

Content type
application/json
{
  • "amount": 50000,
  • "amount_tax_type": "net",
  • "effective_date": "2021-12-20",
  • "note": "Bonus for moving start date to an earlier date",
  • "type": "signing_bonus"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Contract Amendments

contract_amendment.review_started Webhook

This event is triggered whenever a contract amendment request status is updated to 'in review'.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
employment_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "employment_request_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33",
  • "event_type": "contract_amendment.review_started"
}

contract_amendment.done Webhook

This event is triggered whenever a contract amendment status is updated to done.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
employment_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "employment_request_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33",
  • "event_type": "contract_amendment.done"
}

contract_amendment.canceled Webhook

This event is triggered whenever a contract amendment request status is updated to canceled.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
employment_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "employment_request_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33",
  • "event_type": "contract_amendment.canceled"
}

contract_amendment.submitted Webhook

This event is triggered whenever a contract amendment request status is updated to submitted.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
employment_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "employment_request_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33",
  • "event_type": "contract_amendment.submitted"
}

contract_amendment.deleted Webhook

This event is triggered whenever a contract amendment request status is updated to deleted.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
employment_request_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "employment_request_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33",
  • "event_type": "contract_amendment.deleted"
}

List Contract Amendment

List Contract Amendment requests.

Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Starts fetching records after the given page

page_size
integer >= 1
Default: 20
Example: page_size=20

Number of items per page

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "contract_amendments": [
    ],
  • "current_page": 1,
  • "total_count": 1,
  • "total_pages": 1
}

Create Contract Amendment

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

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Contract Amendment

amendment_contract_id
required
string

The contract ID of the contract that needs to be amended.

contract_amendment
required
object

Contract amendment informations. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code, contract_amendment and the employment ID as request body.

employment_id
required
string

The employment ID that is related to the contract amendment request.

Responses

Request samples

Content type
application/json
{
  • "amendment_contract_id": "c15993d8-aa8a-4fbb-b395-8b7a54f57db1",
  • "contract_amendment": { },
  • "employment_id": "e31adae1-company-id-af5fba7dd803"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show Contract Amendment

Show a single Contract Amendment request.

Authorizations:
OAuth2
path Parameters
id
required
string
Example: 93t3j-contract_amendment_id-9suej43

Contract amendment request ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Automatable Contract Amendment

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

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Contract Amendment

amendment_contract_id
required
string

The contract ID of the contract that needs to be amended.

contract_amendment
required
object

Contract amendment informations. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code, contract_amendment and the employment ID as request body.

employment_id
required
string

The employment ID that is related to the contract amendment request.

Responses

Request samples

Content type
application/json
{
  • "amendment_contract_id": "c15993d8-aa8a-4fbb-b395-8b7a54f57db1",
  • "contract_amendment": { },
  • "employment_id": "e31adae1-company-id-af5fba7dd803"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show form schema

Returns the json schema of the contract_amendment form. This endpoint requires a company access token, as forms are dependent on certain properties of companies and their current employments.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Contract Amendment Form

country_code
required
string

Country code according to ISO 3-digit alphabetic codes.

employment_id
required
string

The ID of the employment concerned by the contract amendment request.

form
string
Value: "contract_amendment"

Name of the desired form

Responses

Request samples

Content type
application/json
{
  • "country_code": "string",
  • "employment_id": "string",
  • "form": "contract_amendment"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Employment Contracts

employment_contract.active_contract_updated Webhook

This event is triggered whenever a new contract becomes active for an employment.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
contract_id
required
string

Responses

Request samples

Content type
application/json
{
  • "contract_id": "ba310525-9282-40c9-8977-14d844bf891a",
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment_contract.active_contract_updated"
}

Get employment contract pending changes

Get all the pending changes (waiting for aproval or signature) for the employment contract.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 93t3j-employment_id-9suej43

Employment ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Employment Contract.

Get the employment contract history (list of all contracts active or not) for a given employment.

Authorizations:
OAuth2
query Parameters
employment_id
required
string
Example: employment_id=93t3j-employment_id-9suej43

Employment ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Payslips

payslip.released Webhook

This event is triggered when a payslip is ready and available for an employee.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
payslip_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "45b34922-2590-43a0-ac05-ad23834adb8f",
  • "event_type": "payslip.released",
  • "payslip_id": "86e56288-ca62-11ed-9702-a703c40b6c0d"
}

List payslips

Lists all payslips belonging to a company. Can also filter for a single employment belonging to that company.

Authorizations:
OAuth2
query Parameters
employment_id
string
Example: employment_id=93t3j-employment-id-9suej43

Employment ID

start_date
string
Example: start_date="2022-12-15"

Filters by payslips issued_at field, after or on the same day than the given date

end_date
string
Example: end_date="2023-12-15"

Filters by payslips issued_at field, before or or the same day than the given date

expected_payout_start_date
string
Example: expected_payout_start_date="2022-12-15"

Filters by payslips expected_payout_date field, after or on the same day than the given date

expected_payout_end_date
string
Example: expected_payout_end_date="2023-12-15"

Filters by payslips expected_payout_date field, before or or the same day than the given date

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "payslips": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Show payslip

Given an ID, shows a payslip.

Please contact api-support@remote.com to request access to this endpoint.

Authorizations:
OAuth2
path Parameters
id
required
string
Example: 93t3j-payslip-id-9suej43

Payslip ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Download payslip in the PDF format

Given a Payslip ID, downloads a payslip. It is important to note that each country has a different payslip format and they are not authored by Remote.

Authorizations:
OAuth2
path Parameters
payslip_id
required
string
Example: 93t3j-payslip-id-9suej43

Payslip ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
"string"

Identity Verification

identity_verification.verification_required Webhook

This event is triggered whenever an identity verification is required for an employment.

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "identity_verification.verification_required"
}

Get Employment Profile

Gets necessary information to perform the identity verification of an employee.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 0a8s2d1-employment-id-2e3f4th

Employment ID

Responses

Response samples

Content type
application/json
{}

Decline Identity Verification

Declines the identity verification of an employee.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: d9dabe74-f845-4a79-9e66-e52d4261c7bb

Employment ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Employments

employment.onboarding.completed Webhook

This event is triggered when an employment onboarding is completed and the employment is set to active.

An onboarding is considered complete when the employee finishes their self-enrollment and has completed all the onboarding tasks assigned to them (Personal profile, Administrative details, Emergency contact, Supporting documentation, etc).

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.onboarding.completed"
}

employment.personal_information.updated Webhook

This event is triggered whenever an employment personal details is updated. Personal details includes personal informations, home address and emergency contact.

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.personal_information.updated"
}

employment.user_status.activated Webhook

This event is triggered whenever an employment user is updated to the active status.

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.user_status.activated"
}

employment.details.updated Webhook

This event is triggered whenever an employment department or manager is updated.

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.details.updated"
}

employment.onboarding_task.completed Webhook

This event is triggered everytime an employment onboarding task (Personal profile, Administrative details, Emergency contact, Supporting documentation, etc) is completed by an employee during the self-enrollment.

Request Body schema: application/json
event_type
required
string
company_id
required
string
employment_id
required
string
object

Responses

Request samples

Content type
application/json
{
  • "company_id": "97c7ce7e-ca67-11ed-bce5-3bb70cbb9f9e",
  • "completed_task": {
    },
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.onboarding_task.completed"
}

employment.user_status.deactivated Webhook

This event is triggered whenever an employment user is updated to the inactive status.

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.user_status.deactivated"
}

employment.account.updated Webhook

This event is triggered whenever an employment account email is updated.

Request Body schema: application/json
event_type
required
string
employment_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "employment.account.updated"
}

Show employment

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

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 93t3j-employment-id-9suej43

Employment ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update employment

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 and address_details.

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

Automatically inviting an employee

When you submit the contract_details and pricing_plan_details, Remote should have all the required data to automatically send an invite to the employee. You can tell if an automatic invite has been sent by looking at the employment_lifecycle_stage field value. If its value is employee_self_enrollment, it means the employee has received an email to join the Remote platform at their personal_email.

After an automatic invite is sent to an employee, you will not be able to update employment data through the Remote API. 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.

Please contact Remote if you need to update contractors via API since it's currently not supported.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 93t3j-employment-id-9suej43

Employment ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment params

One of
address_details
object

Home address information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and address_details as path parameters.

administrative_details
object

Administrative information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and administrative_details as path parameters.

bank_account_details
object

Bank account information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and bank_account_details as path parameters.

billing_address_details
object

Billing address information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and billing_address_details as path parameters.

company_id
string
contract_details
object

Contract information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and contract_details as path parameters.

object (Country)

A supported country on Remote

emergency_contact_details
object

Emergency contact information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and emergency_contact_details as path parameters.

full_name
required
string
job_title
required
string
manager_id
string

The user id of the manager, who should have an admin, owner or people_manager role. You can find these users by querying the Company Managers endpoint. Update of this field is only available for active employments.

personal_details
object

Personal details information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and personal_details as path parameters.

personal_email
required
string
object (PricingPlanDetails)

Selected type of payment.

provisional_start_date
string <date> (ProvisionalStartDate)

Indicates the expected start date of the employee or contractor.

Required for employees, but optional for contractors. Date format is in ISO8601 without the time component.

See the Date and Time Format documentation for more details on how the Remote API works with dates.

seniority_date
string <date-time> (EmploymentSeniorityDate)

The date the employee first started working for your company. If you don’t include a seniority date, the employee’s start date with Remote will be deemed as the start of the employee’s seniority.

Example: Your employee started working for your company on Feb 1, 2022. On Aug 1, 2022, you transferred the employee to Remote and started managing them on the platform. Feb 1, 2022 would be their seniority date. Aug 1, 2022 would be their starting date.

Responses

Request samples

Content type
application/json
Example
{
  • "address_details": { },
  • "administrative_details": { },
  • "bank_account_details": { },
  • "billing_address_details": { },
  • "company_id": "e31adae1-company-id-af5fba7dd803",
  • "contract_details": { },
  • "country": {
    },
  • "emergency_contact_details": { },
  • "full_name": "Jane Smith",
  • "job_title": "Backend Engineer",
  • "manager_id": "string",
  • "personal_details": { },
  • "personal_email": "jane@smith.com",
  • "pricing_plan_details": {
    },
  • "provisional_start_date": "2021-07-03",
  • "seniority_date": "2022-03-21",
  • "basic_information": {
    },
  • "country_code": "AUS",
  • "department_id": "3bb56f01-3243-412b-bfaa-a5cfaaf2e431",
  • "manager": "Taylor Johnson"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update employment

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 and address_details.

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

Automatically inviting an employee

When you submit the contract_details and pricing_plan_details, Remote should have all the required data to automatically send an invite to the employee. You can tell if an automatic invite has been sent by looking at the employment_lifecycle_stage field value. If its value is employee_self_enrollment, it means the employee has received an email to join the Remote platform at their personal_email.

After an automatic invite is sent to an employee, you will not be able to update employment data through the Remote API. 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.

Please contact Remote if you need to update contractors via API since it's currently not supported.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 93t3j-employment-id-9suej43

Employment ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment params

One of
address_details
object

Home address information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and address_details as path parameters.

administrative_details
object

Administrative information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and administrative_details as path parameters.

bank_account_details
object

Bank account information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and bank_account_details as path parameters.

billing_address_details
object

Billing address information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and billing_address_details as path parameters.

company_id
string
contract_details
object

Contract information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and contract_details as path parameters.

object (Country)

A supported country on Remote

emergency_contact_details
object

Emergency contact information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and emergency_contact_details as path parameters.

full_name
required
string
job_title
required
string
manager_id
string

The user id of the manager, who should have an admin, owner or people_manager role. You can find these users by querying the Company Managers endpoint. Update of this field is only available for active employments.

personal_details
object

Personal details information. As its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and personal_details as path parameters.

personal_email
required
string
object (PricingPlanDetails)

Selected type of payment.

provisional_start_date
string <date> (ProvisionalStartDate)

Indicates the expected start date of the employee or contractor.

Required for employees, but optional for contractors. Date format is in ISO8601 without the time component.

See the Date and Time Format documentation for more details on how the Remote API works with dates.

seniority_date
string <date-time> (EmploymentSeniorityDate)

The date the employee first started working for your company. If you don’t include a seniority date, the employee’s start date with Remote will be deemed as the start of the employee’s seniority.

Example: Your employee started working for your company on Feb 1, 2022. On Aug 1, 2022, you transferred the employee to Remote and started managing them on the platform. Feb 1, 2022 would be their seniority date. Aug 1, 2022 would be their starting date.

Responses

Request samples

Content type
application/json
Example
{
  • "address_details": { },
  • "administrative_details": { },
  • "bank_account_details": { },
  • "billing_address_details": { },
  • "company_id": "e31adae1-company-id-af5fba7dd803",
  • "contract_details": { },
  • "country": {
    },
  • "emergency_contact_details": { },
  • "full_name": "Jane Smith",
  • "job_title": "Backend Engineer",
  • "manager_id": "string",
  • "personal_details": { },
  • "personal_email": "jane@smith.com",
  • "pricing_plan_details": {
    },
  • "provisional_start_date": "2021-07-03",
  • "seniority_date": "2022-03-21",
  • "basic_information": {
    },
  • "country_code": "AUS",
  • "department_id": "3bb56f01-3243-412b-bfaa-a5cfaaf2e431",
  • "manager": "Taylor Johnson"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Invite employment

Invite an employment to start the self-enrollment.

Requirements for the invitation to succeed:

  • Employment needs to have the following JSON Schema forms filled: contract_details and pricing_plan_details
  • provisional_start_date must consider the minimum onbaording time of the employment's country

If there are validations errors, they are returned with a Conflict HTTP Status (409) and a descriptive message. HTTP Status OK (200) is returned in case of success.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d

Employment ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List 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 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 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 tool.

Authorizations:
OAuth2
query Parameters
company_id
string
Example: company_id=93t3j-company-id-9suej43

Company ID

email
string
Example: email=anna@example.com

Filters the results by employments whose login email matches the value

status
string
Example: status=active

Filters the results by employments whose status matches the value

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "employments": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Create employment

Creates an employment. We support creating employees and contractors.

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

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment params

One of
basic_information
object

Employment basic information. When using this field, the same other root level fields (name, personal_email, job_title, provisional_start_date, and seniority_date) will be ignored. Its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and employment_basic_information as path parameters.

company_id
string

This optional field is deprecated.

country_code
required
string
type
string
Enum: "employee" "contractor"

If not provided, it will default to employee.

Responses

Request samples

Content type
application/json
Example
{
  • "basic_information": {
    },
  • "company_id": "string",
  • "country_code": "AUS",
  • "type": "employee",
  • "full_name": "Jane Smith",
  • "job_title": "Engineer",
  • "personal_email": "jane@smith.com",
  • "provisional_start_date": "2022-07-10"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Complete onboarding

Completes the employee onboarding. When all tasks are completed, the employee is marked as in review status

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment slug

employment_id
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Time Off

timeoff.canceled Webhook

This event is triggered when a timeoff has status changed to canceled.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.canceled",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

timeoff.taken Webhook

This event is triggered when a timeoff is set as taken.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.taken",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

timeoff.approved Webhook

This event is triggered when a timeoff is set as approved.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.approved",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

timeoff.date_changed Webhook

This event is triggered when a timeoff has its date changed.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.date_changed",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

timeoff.updated Webhook

This event is triggered when a timeoff is updated.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.updated",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

timeoff.declined Webhook

This event is triggered when a timeoff is declined

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.declined",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

timeoff.requested Webhook

This event is triggered when a timeoff is requested

Request Body schema: application/json
event_type
required
string
employment_id
required
string
timeoff_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "timeoff.requested",
  • "timeoff_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1"
}

Show Time Off

Shows a single Time Off record

Authorizations:
OAuth2
path Parameters
id
required
string
Example: 93t3j-timeoff-id-9suej43

Timeoff ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Time Off

Updates a Time Off record. This endpoint can also be used for cancelling a time off.

Authorizations:
OAuth2
path Parameters
id
required
string
Example: 93t3j-timeoff-id-9suej43

Timeoff ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

UpdateTimeoff

approved_at
string <date-time> (DateTimeIso8601)

UTC date time in ISO 8601 format.

approver_id
string or null (NullableApproverId)

The field matches the id of a user in the Remote Platform that has permission to approve time off requests. Available users can be found fetching the List Company Manager endpoint.

cancel_reason
required
string

The reason for cancelling a time off. Required when updating to status cancelled.

object (TimeoffDocumentParams)

Timeoff document params

edit_reason
required
string

The reason for the update. Required when updating the time off data but not changing the status.

end_date
string <date> (Date)

UTC date in ISO 8601 format

notes
string
start_date
string <date> (Date)

UTC date in ISO 8601 format

status
string
Enum: "approved" "cancelled"
Array of objects (TimeoffDaysParams)
timeoff_type
string (TimeoffType)
Enum: "paid_time_off" "sick_leave" "public_holiday" "unpaid_leave" "extended_leave" "in_lieu_time" "maternity_leave" "paternity_leave" "parental_leave" "bereavement" "military_leave" "other"
timezone
string (Timezone)

Responses

Request samples

Content type
application/json
{
  • "approved_at": "2021-07-15T18:18:17Z",
  • "approver_id": "51546f60-dd71-4223-9312-4efede68a497",
  • "cancel_reason": "string",
  • "document": {
    },
  • "edit_reason": "string",
  • "end_date": "2021-07-01",
  • "notes": "string",
  • "start_date": "2021-07-01",
  • "status": "approved",
  • "timeoff_days": [
    ],
  • "timeoff_type": "sick_leave",
  • "timezone": "Etc/UTC"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Time Off

Updates a Time Off record. This endpoint can also be used for cancelling a time off.

Authorizations:
OAuth2
path Parameters
id
required
string
Example: 93t3j-timeoff-id-9suej43

Timeoff ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

UpdateTimeoff

approved_at
string <date-time> (DateTimeIso8601)

UTC date time in ISO 8601 format.

approver_id
string or null (NullableApproverId)

The field matches the id of a user in the Remote Platform that has permission to approve time off requests. Available users can be found fetching the List Company Manager endpoint.

cancel_reason
required
string

The reason for cancelling a time off. Required when updating to status cancelled.

object (TimeoffDocumentParams)

Timeoff document params

edit_reason
required
string

The reason for the update. Required when updating the time off data but not changing the status.

end_date
string <date> (Date)

UTC date in ISO 8601 format

notes
string
start_date
string <date> (Date)

UTC date in ISO 8601 format

status
string
Enum: "approved" "cancelled"
Array of objects (TimeoffDaysParams)
timeoff_type
string (TimeoffType)
Enum: "paid_time_off" "sick_leave" "public_holiday" "unpaid_leave" "extended_leave" "in_lieu_time" "maternity_leave" "paternity_leave" "parental_leave" "bereavement" "military_leave" "other"
timezone
string (Timezone)

Responses

Request samples

Content type
application/json
{
  • "approved_at": "2021-07-15T18:18:17Z",
  • "approver_id": "51546f60-dd71-4223-9312-4efede68a497",
  • "cancel_reason": "string",
  • "document": {
    },
  • "edit_reason": "string",
  • "end_date": "2021-07-01",
  • "notes": "string",
  • "start_date": "2021-07-01",
  • "status": "approved",
  • "timeoff_days": [
    ],
  • "timeoff_type": "sick_leave",
  • "timezone": "Etc/UTC"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Time Off

Lists all Time Off records.

Authorizations:
OAuth2
query Parameters
employment_id
string
Example: employment_id=31b8e49b-aa1c-47af-849c-3d0a53e20e0d

Only show time off for a specific employment

timeoff_type
string (TimeoffType)
Enum: "paid_time_off" "sick_leave" "public_holiday" "unpaid_leave" "extended_leave" "in_lieu_time" "maternity_leave" "paternity_leave" "parental_leave" "bereavement" "military_leave" "other"
Example: timeoff_type=sick_leave

Filter time off by its type

status
string (TimeoffStatus)
Enum: "approved" "cancelled" "declined" "requested" "taken" "cancel_requested"
Example: status=approved

Filter time off by its status

order
string
Enum: "asc" "desc"
Example: order=asc

Sort order

sort_by
string
Enum: "timeoff_type" "status"
Example: sort_by=timeoff_type

Field to sort by

page
integer >= 1
Default: 1
Example: page=1

Starts fetching records after the given page

page_size
integer >= 1
Default: 20
Example: page_size=20

Number of items per page

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "timeoffs": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Create Time Off

Creates a Time Off record

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Timeoff

object (TimeoffDocumentParams)

Timeoff document params

employment_id
required
string
end_date
required
string <datetime>
notes
string
start_date
required
string <datetime>
required
Array of objects (TimeoffDaysParams)
timeoff_type
required
string (TimeoffType)
Enum: "paid_time_off" "sick_leave" "public_holiday" "unpaid_leave" "extended_leave" "in_lieu_time" "maternity_leave" "paternity_leave" "parental_leave" "bereavement" "military_leave" "other"
timezone
required
string (Timezone)
approved_at
required
string <date-time> (DateTimeIso8601)

UTC date time in ISO 8601 format.

approver_id
required
string or null (NullableApproverId)

The field matches the id of a user in the Remote Platform that has permission to approve time off requests. Available users can be found fetching the List Company Manager endpoint.

status
required
string
Value: "approved"

Responses

Request samples

Content type
application/json
{
  • "document": {
    },
  • "employment_id": "string",
  • "end_date": "string",
  • "notes": "string",
  • "start_date": "string",
  • "timeoff_days": [
    ],
  • "timeoff_type": "sick_leave",
  • "timezone": "Etc/UTC",
  • "approved_at": "2021-07-15T18:18:17Z",
  • "approver_id": "51546f60-dd71-4223-9312-4efede68a497",
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Time Off Types

Lists all time off types that can be used for the timeoff_type parameter

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Expenses

expense.deleted Webhook

This event is triggered when an expense is deleted by an employee or canceled by an admin.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
expense_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "expense.deleted",
  • "expense_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

expense.reimbursed Webhook

This event is triggered when an expense is reimbursed.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
expense_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "expense.reimbursed",
  • "expense_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

expense.submitted Webhook

This event is triggered when an expense is submitted by an employee.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
expense_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "expense.submitted",
  • "expense_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

expense.declined Webhook

This event is triggered when an expense is declined.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
expense_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "expense.declined",
  • "expense_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

expense.approved Webhook

This event is triggered when an expense is approved.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
expense_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "expense.approved",
  • "expense_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

expense.updated Webhook

This event is triggered whenever an expense is updated.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
expense_id
required
string

Responses

Request samples

Content type
application/json
{
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "expense.updated",
  • "expense_id": "129d02bc-dd6a-11ed-ac99-cb057df06a33"
}

List expenses

Lists all expenses records

Authorizations:
OAuth2
query Parameters
page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "expenses": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Create expense

Creates an approved expense

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Expenses

amount
required
integer
category
string
Enum: "education_training" "home_office" "meals" "other" "phone_utilities" "tech_equipment" "travel" "coworking"

Categories allowed for an expense

currency
required
string

The three-letter code for the expense currency.
Examples: "USD", "EUR", "CAD"

employment_id
required
string

The ID for the employment to which this expense relates.

expense_date
required
string

Date of the purchase, which must be in the past

object (Base64File)

All the params needed upload a base64 file.

Array of objects (Base64File) <= 5 items
reviewed_at
string <date>

The date and time that the expense was reviewed in ISO8601 format. If not provided, it defaults to the current datetime.

reviewer_id
string

If the person reviewing the expense is a user in Remote, you can provide its user id for this field. If a value is not provided, defaults to the user that generated the API token.

tax_amount
integer
timezone
string (Timezone)
title
required
string

Responses

Request samples

Content type
application/json
{
  • "amount": 8000,
  • "category": "home_office",
  • "currency": "EUR",
  • "employment_id": "d4ebc714-4950-47a9-a464-28e1f1ab2a90",
  • "expense_date": "2020-12-11",
  • "receipt": {
    },
  • "reviewed_at": "2023-01-11T11:12:13Z",
  • "reviewer_id": "14c14128-f5f4-475a-8ec0-6329b4832a61",
  • "tax_amount": 0,
  • "timezone": "Etc/UTC",
  • "title": "new keyboard"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show expense

Shows a single expense record

Authorizations:
OAuth2
path Parameters
id
required
string

Expense ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an expense

Updates an expense

Authorizations:
OAuth2
path Parameters
id
required
string

Expense ID

Request Body schema: application/json

Expenses

One of
status
required
string
Value: "approved"

Responses

Request samples

Content type
application/json
Example
{
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an expense

Updates an expense

Authorizations:
OAuth2
path Parameters
id
required
string

Expense ID

Request Body schema: application/json

Expenses

One of
status
required
string
Value: "approved"

Responses

Request samples

Content type
application/json
Example
{
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Download a receipt Deprecated

Downloads an expense receipt.

Deprecated since late February 2024 in favour of Download a receipt by id endpoint.

Authorizations:
OAuth2
path Parameters
expense_id
required
string
Example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d

The expense ID

Responses

Response samples

Content type
application/json
{
  • "message": "invalid {resource}"
}

Download a receipt by id

Download a receipt by id.

Authorizations:
OAuth2
path Parameters
expense_id
required
string
Example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d

The expense ID

receipt_id
required
string
Example: 6ab2e49o-ad1c-47af-849c-3d0a53e21e0e

The receipt ID

Responses

Response samples

Content type
application/json
{
  • "message": "invalid {resource}"
}

Billing Documents

billing_document.issued Webhook

This event is triggered when a new billing document is issued to the company.

Request Body schema: application/json
event_type
required
string
document_type
required
string
Enum: "prefunding_invoice" "reconciliation_invoice" "supplemental_service_invoice" "prefunding_credit_note" "reconciliation_credit_note" "supplemental_service_credit_note"
billing_document_id
required
string

Responses

Request samples

Content type
application/json
{
  • "billing_document_id": "2f2b7ce8-3f80-47fe-a0b1-57ad9217636d",
  • "document_type": "reconciliation_invoice",
  • "event_type": "billing_document.issued"
}

List Billing Documents

List billing documents for a company

Authorizations:
OAuth2
query Parameters
period
string
Example: period="2023-01"

The month for the billing documents (in ISO-8601 format)

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Download a billing document PDF

Downloads a billing document PDF

Authorizations:
OAuth2
path Parameters
billing_document_id
required
string
Example: 93t3j-billing-doc-id-9suej43

The billing document's ID

Responses

Response samples

Content type
application/json
{
  • "message": "invalid {resource}"
}

Show Billing Document

Shows a billing document details.

Please contact api-support@remote.com to request access to this endpoint.

Authorizations:
OAuth2
path Parameters
billing_document_id
required
string
Example: 93t3j-billing-doc-id-9suej43

The billing document's ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Custom Fields

custom_field.value_updated Webhook

This event is triggered when a custom field value is updated.

Request Body schema: application/json
event_type
required
string
employment_id
required
string
custom_field_id
required
string

Responses

Request samples

Content type
application/json
{
  • "custom_field_id": "0073fcb5-b669-4e4a-b963-2a47744e75a1",
  • "employment_id": "2614f814-b08e-4c8e-8c4d-ddbcc4692d99",
  • "event_type": "custom_field.value_updated"
}

Lists custom fields definitions

Returns custom fields definitions

Authorizations:
OAuth2
query Parameters
page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "custom_fields": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Show a custom field value

Returns a custom field value for a given employment

Authorizations:
OAuth2
path Parameters
custom_field_id
required
string

Custom field ID

employment_id
required
string

Employment ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cost Calculator

Creates a cost estimation of employments

Authorizations:
OAuth2
Request Body schema: application/json

Estimate params

employer_currency_slug
required
string (Slug)

Currency Slug

required
Array of objects (CostCalculatorEmploymentParam)
include_benefits
boolean
include_cost_breakdowns
boolean

Responses

Request samples

Content type
application/json
{
  • "employer_currency_slug": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
  • "employments": [
    ],
  • "include_benefits": true,
  • "include_cost_breakdowns": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show region fields

Returns required fields JSON Schema for a given region. These are required in order to calculate the cost of employment for the region. These fields are based on employer contributions that are associated with the region or any of it's parent regions.

Authorizations:
OAuth2
path Parameters
slug
required
string

Slug

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Creates a cost estimation of employments

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Estimate params

employer_currency_slug
required
string (Slug)

Currency Slug

required
Array of objects (CostCalculatorEmploymentParam)
include_benefits
boolean
include_cost_breakdowns
boolean

Responses

Request samples

Content type
application/json
{
  • "employer_currency_slug": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
  • "employments": [
    ],
  • "include_benefits": true,
  • "include_cost_breakdowns": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List countries

Lists active and processing countries

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ

Authorization header with basic authentication encoded with Base64. Check the Auth & Authorization section for more information on how to create the encoded token.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

OAuth2

Token

Endpoint to exchange tokens in the Authorization Code, Client Credentials and Refresh Token flows

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ

Authorization header with basic authentication encoded with Base64. Check the Auth & Authorization section for more information on how to create the encoded token.

Request Body schema: application/json

OAuth2Token

One of
code
required
string

The authorization code generated in Authorization Code flow

grant_type
required
string
Value: "authorization_code"

The Authorization flow

Responses

Request samples

Content type
application/json
Example
{
  • "code": "eyJhbG...xb6H0",
  • "grant_type": "authorization_code"
}

Response samples

Content type
application/json
Example
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ",
  • "company_id": "6e60f5f9-e6a6-4b04-b13c-84bced848bab",
  • "expires_in": 7200,
  • "refresh_token": "b480036a-d229-49ef-a606-7e8fba58a5eb",
  • "token_type": "Bearer",
  • "user_id": "6550e536-8655-4bce-8bd9-b295f786ad71"
}

Recurring Incentives

Delete a Recurring Incentive

Delete a Recurring Incentive, that is, a monthly paid incentive.

Internally, Remote schedules upcoming incentives. As such, when you attempt to delete a recurring incentive, Remote will ONLY delete scheduled incentives with the pending status.

Incentives payments that are already scheduled and cannot be deleted will be included in the response, in case you need to reference them.

Authorizations:
OAuth2
path Parameters
id
required
string

Recurring Incentive ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Recurring Incentive

List all Recurring Incentives of a company.

Authorizations:
OAuth2
query Parameters
status
string
Example: status=active

Filter by recurring incentive status: active or deactive.

type
string
Example: type=meal_allowance

Filter by recurring incentive type.

note
string
Example: note=meal

Filter by recurring incentives that contain the value in their notes.

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "recurring_incentives": [
    ],
  • "total_count": 1,
  • "total_pages": 1
}

Create Recurring Incentive

Create a Recurring Incentive, that is, a monthly paid incentive.

Incentives use the currency of the employment specified provided in the employment_id field.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

RecurringIncentive

amount
required
integer

The amount (in the currency of the employment) to be given to the employee.

This field accepts fractional amounts as well. However to avoid precision issues and errors that can arise from storing fractional amounts, the Remote API only accepts currencies and their fractional amounts as integers. This means you should append fractional amounts to the end of the amount you're passing in with this field.

For example, if the incentive you're offering is EUR 500.25, you would specify 50025 as the amount for this field.

amount_tax_type
required
string (AmountTaxType)
Enum: "gross" "net"

Whether the amount given accounts for taxes or not.

gross indicates that the amount given is the amount to be paid before taxes are subtracted.

net indicates that the amount given is the amount which will be paid to the employee after taxes. Remote will gross this up to ensure the taxes are included and employee receives the amount requested without further reduction.

effective_date
required
string <date>

The date at which the incentive should take effect.

Note that the incentive is not paid out on the effective date, but during the next payroll cycle. The effective date determines which payroll cycle the incentive will be paid out in.

The effective date needs to be today or a future date.

Note for recurring incentives: since the months don't have the same amount of days, if day of month of effective_date is one of [28, 29, 30, 31] it will be transformed to the last day of each month, avoiding the possibility of skipping a month in the recurrence.

note
string or null
duration_in_months
string <integer>

How many times the payment will repeat. At the moment we only fully support monthly frequency.

This field is only necessary if the recurring incentive has an end date.

employment_id
required
string
type
required
string
Enum: "acting_up_allowance" "allowance" "car_allowance" "health_and_wellness_allowance" "internet_allowance" "meal_allowance" "on_call_allowance" "parenthood_allowance" "phone_allowance" "relocation_allowance" "travel_allowance" "work_from_home_allowance" "bonus" "holiday_bonus" "referral_bonus" "retention_bonus" "commission" "other" "overtime" "stipend"

Responses

Request samples

Content type
application/json
{
  • "amount": 50000,
  • "amount_tax_type": "net",
  • "duration_in_months": 3,
  • "effective_date": "2021-12-20",
  • "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
  • "note": "Bonus for moving start date to an earlier date",
  • "type": "meal_allowance"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Sandbox

Update employment

Updates an employment. Use this endpoint to modify employment states for testing in the Sandbox environment. This endpoint will respond with a 404 outside of the Sandbox environment.

For updating an employment's parameters outside of testing purposes, use this Employment update endpoint.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: e3ee69d7-1293-4664-92fc-02625dae5247

Employment ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment params

status
string (EmploymentStatus)
Enum: "active" "created" "created_awaiting_reserve" "created_reserve_paid" "initiated" "invited" "pending" "review" "archived" "deleted"

The status of employment

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update employment

Updates an employment. Use this endpoint to modify employment states for testing in the Sandbox environment. This endpoint will respond with a 404 outside of the Sandbox environment.

For updating an employment's parameters outside of testing purposes, use this Employment update endpoint.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: e3ee69d7-1293-4664-92fc-02625dae5247

Employment ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment params

status
string (EmploymentStatus)
Enum: "active" "created" "created_awaiting_reserve" "created_reserve_paid" "initiated" "invited" "pending" "review" "archived" "deleted"

The status of employment

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create employment

Creates an employment without provisional_start_date validation.

This endpoint is only available in Sandbox and allows creating employments which provisional_start_date is in the past. This is especially helpful for:

  • Testing the Timeoff Balance endpoints
  • Testing the Offboarding endpoints
  • Testing features around probation periods

This endpoint will respond with a 404 outside of the Sandbox environment.

For creating an employment's parameters outside of testing purposes, use this Employment create endpoint

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Employment params

One of
basic_information
object

Employment basic information. When using this field, the same other root level fields (name, personal_email, job_title, provisional_start_date, and seniority_date) will be ignored. Its properties may vary depending on the country, you must query the Show form schema endpoint passing the country code and employment_basic_information as path parameters.

company_id
string

This optional field is deprecated.

country_code
required
string
type
string
Enum: "employee" "contractor"

If not provided, it will default to employee.

Responses

Request samples

Content type
application/json
Example
{
  • "basic_information": {
    },
  • "company_id": "string",
  • "country_code": "AUS",
  • "type": "employee",
  • "full_name": "Jane Smith",
  • "job_title": "Engineer",
  • "personal_email": "jane@smith.com",
  • "provisional_start_date": "2022-07-10"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Trigger a Webhook

Triggers a callback previously registered for webhooks. Use this endpoint to emit a webhook for testing in the Sandbox environment. This endpoint will respond with a 404 outside of the Sandbox environment.

Authorizations:
OAuth2
Request Body schema: application/json

Webhook Trigger Params

One of
employment_id
required
string
event_type
required
string
Enum: "billing_document.issued" "contract_amendment.canceled" "contract_amendment.deleted" "contract_amendment.done" "contract_amendment.review_started" "contract_amendment.submitted" "custom_field.value_updated" "employment_contract.active_contract_updated" "employment.account.updated" "employment.details.updated" "employment.onboarding_task.completed" "employment.onboarding.completed" "employment.personal_information.updated" "employment.user_status.activated" "employment.user_status.deactivated" "expense.approved" "expense.declined" "expense.deleted" "expense.reimbursed" "expense.submitted" "expense.updated" "identity_verification.verification_required" "incentive.created" "incentive.deleted" "incentive.paid" "incentive.processing_started" "incentive.updated" "offboarding.deleted" "offboarding.done" "offboarding.review_started" "offboarding.submitted" "offboarding.submitted_to_payroll" "offboarding.completed" "payslip.released" "timeoff.approved" "timeoff.canceled" "timeoff.date_changed" "timeoff.declined" "timeoff.requested" "timeoff.taken" "timeoff.updated"

Responses

Request samples

Content type
application/json
Example
{
  • "employment_id": "e966a8b8-1076-11ee-a5f2-9b3997a968f6",
  • "event_type": "employment.onboarding_task.completed"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Approve Contract Amendment

Approves a contract amendment request without the intervention of a Remote admin. Approvals done via this endpoint are effective immediately, regardless of the effective date entered on the contract amendment creation.

This endpoint is only available in Sandbox, otherwise it will respond with a 404.

Authorizations:
OAuth2
path Parameters
contract_amendment_request_id
required
string
Example: 6d947344-b053-4a4f-acf0-79d296cbd082

Contract amendment request ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cancel Contract Amendment

Use this endpoint to cancel an existing contract amendment request.

This endpoint is only available in Sandbox, otherwise it will respond with a 404.

Authorizations:
OAuth2
path Parameters
contract_amendment_request_id
required
string
Example: 5bdc2cb9-6bda-4cf7-bc6e-0b122791e52a

Contract amendment request ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Resignation

Download a resignation letter

Downloads a resignation letter from an employment request.

Authorizations:
OAuth2
path Parameters
employment_request_id
required
string
Example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d

The employment request ID

Responses

Response samples

Content type
application/json
{
  • "message": "invalid {resource}"
}

Show Resignation

Shows the details of a resignation with status submitted.

Authorizations:
OAuth2
path Parameters
employment_request_id
required
string
Example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d

The employment request ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validate resignation request

Validates a resignation employment request

Authorizations:
OAuth2
path Parameters
employment_request_id
required
string
Example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d

The employment request ID

Request Body schema: application/json

ValidateResignation

One of
accepts_proposed_notice
required
boolean
agrees_to_pto_amount
required
boolean
agrees_to_pto_amount_notes
string

Required if agrees_to_pto_amount is set to false.

agrees_to_resignation_reason
required
boolean
agrees_to_resignation_reason_notes
string

required if agrees_to_resignation_reason is set to false.

has_additional_information
required
boolean
has_additional_information_notes
string

required if has_additional_information is set to true.

has_more_salary_info
required
boolean
has_more_salary_info_notes
string

required if has_more_salary_info is set to true.

is_owed_outstanding_reimbursements
required
boolean
object

required if is_owed_outstanding_reimbursements is set to true.

object

Required if accepts_proposed_notice is set to false.

object (ResignationFile)

Paid time off accuracy

Typically, any vacation pay accrued and unpaid at the time of termination must be paid out to the employee. To avoid overpaying or underpaying, please make sure we have an accurate account of their paid time off by querying the Show Time Off Balance endpoint, filtering by the employment_id. This optional document should be sent in case of any discrepancies.

will_take_more_pto
required
boolean
will_take_more_pto_notes
string

required if will_take_more_pto is set to true.

Responses

Request samples

Content type
application/json
Example
{
  • "accepts_proposed_notice": false,
  • "agrees_to_pto_amount": false,
  • "agrees_to_pto_amount_notes": "I don't agree.",
  • "agrees_to_resignation_reason": false,
  • "agrees_to_resignation_reason_notes": "I don't agree.",
  • "has_additional_information": true,
  • "has_additional_information_notes": "Some extra info.",
  • "has_more_salary_info": true,
  • "has_more_salary_info_notes": "Some info about the salary.",
  • "is_owed_outstanding_reimbursements": true,
  • "owed_outstanding_reimbursements": {
    },
  • "proposed_last_date": {
    },
  • "will_take_more_pto": true,
  • "will_take_more_pto_notes": "3 more days."
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Company Department

List Company Departments

Lists all departments for the authorized company specified in the request.

Authorizations:
OAuth2
query Parameters
company_id
required
string
Example: company_id=d2091b1e-b1a4-437a-91ea-2809ffbb6d59

Company ID

paginate
boolean

Paginate option. Default: true. When true, paginates response; otherwise, does not.

page
integer >= 1
Default: 1
Example: page=1

Starts fetching records after the given page

page_size
integer >= 1
Default: 20
Example: page_size=20

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "current_page": 1,
  • "data": {
    },
  • "total_count": 1,
  • "total_pages": 1
}

Create New Department

Creates a new department in the specified company. Department names may be non-unique and must be non-empty with no more than 255 characters (Unicode code points).

Authorizations:
OAuth2
Request Body schema: application/json

Create Company Department request params

company_id
required
string

The Company ID. Required in all cases, whether the API credentials have access to multiple companies or just one.

name
required
string

The name of the company department. May be non-unique and limited to 255 characters, maximum.

Responses

Request samples

Content type
application/json
{
  • "company_id": "669f9e18-889f-4c2c-95b8-67795a3113cc",
  • "name": "Marketing"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Company Managers

List Company Managers

List all company managers of an integration. If filtered by the company_id param, it lists only company managers belonging to the specified company.

Authorizations:
OAuth2
query Parameters
company_id
string
Example: company_id=0a8s2d1-company-id-2e3f4th

A Company ID to filter the results (only applicable for Integration Partners).

page
integer
Example: page=1

Starts fetching records after the given page

page_size
integer
Example: page_size=30

Change the amount of records returned per page, defaults to 20, limited to 100

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "company_managers": [
    ],
  • "current_page": 1,
  • "total_count": 1,
  • "total_pages": 1
}

Create and invite a Company Manager

Create a Company Manager and sends the invitation email for signing in to the Remote Platform.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Company Manager params

company_id
string

The Company ID. Required if the access token can access multiple companies. Optional otherwise.

email
required
string <email>

The work email of the company manager

name
required
string

The name of the company manager

role
required
string

The role assigned for the new manager. The value should be one of the following:

  • admin: an Admin can manage most of the resources in remote.
  • onboarding_manager: an Onboarding Manager can add, see and manage new hires.
  • people_manager: a People Manager can view employee profiles of the team members they manage and approve and decline time off and expenses for their employees.

Responses

Request samples

Content type
application/json
{
  • "company_id": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "role": "string"
}

Response samples

Content type
application/json
{
  • "company_manager": {
    }
}

Deletes a Company Manager user

Deletes a Company Manager user

Authorizations:
OAuth2
path Parameters
user_id
required
string
Example: 1a8s2d1-user-id-2e3f4tz

User ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show company manager user

Shows a single company manager user

Authorizations:
OAuth2
path Parameters
user_id
required
string
Example: 1a8s2d1-user-id-2e3f4tz

User ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Identity

Get token identity

Shows information about the entities that can be controlled by the current auth token.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <ANY ACCESS TOKEN>

This endpoint works with any of the access tokens provided. You can use an access token obtained through the Client Credentials flow, the Authorization Code flow, or the Refresh Token flow.

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Files

Download file

Downloads a file.

Please contact api-support@remote.com to request access to this endpoint.

Authorizations:
OAuth2
path Parameters
id
required
string
Example: 93t3j-file-id-9suej43

File ID

Responses

Response samples

Content type
application/json
{
  • "message": "invalid {resource}"
}

Upload file

Uploads a file associated with a specified employment.

Please contact api-support@remote.com to request access to this endpoint.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <ANY ACCESS TOKEN>

This endpoint works with any of the access tokens provided. You can use an access token obtained through the Client Credentials flow, the Authorization Code flow, or the Refresh Token flow.

Request Body schema: multipart/form-data

The file to be uploaded

employment_id
required
string
file
required
string <binary>
type
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Benefit Offers By Employment

List Benefit Offers By Employment

List benefit offers by employment.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Companies

List all companies

List all companies that authorized your integration to act on their behalf. In other words, these are all the companies that your integration can manage. Any company that has completed the authorization flow for your integration will be included in the response.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <CLIENT-CREDENTIALS ACCESS TOKEN>

Requires a client credentials access token obtained through the Client Credentials flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Client Credentials flow.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a company

Creates a new company.

Creating a company with only the required request body parameters

When you call this endpoint and omit all the optional parameters in the request body, the following resources get created upon a successful response:

  • A new company with status pending.
  • A company owner for the new company with status initiated.

See the update a company endpoint for more details on how to get your company and its owner to active status.

If you'd like to create a company and its owner with active status in a single request, please provide the optional address_details parameter as well.

Accepting the Terms of Service

A required step for creating a company in Remote is to accept our Terms of Service (ToS).

Company managers need to be aware of our Terms of Service and Privacy Policy, hence it's the responsibility of our partners to advise and ensure company managers read and accept the ToS. The terms have to be accepted only once, before creating a company, and the Remote API will collect the acceptance timestamp as its confirmation.

To ensure users read the most recent version of Remote's Terms of Service, their acceptance must be done within the last fifteen minutes prior the company creation action.

To retrieve this information, partners can provide an element with any text and a description explaining that by performing that action they are accepting Remote's Term of Service. For instance, the partner can add a checkbox or a "Create Remote Account" button followed by a description saying "By creating an account, you agree to Remote's Terms of Service. Also see Remote's Privacy Policy".

Authorizations:
OAuth2
query Parameters
action
string
Example: action=get_oauth_access_tokens,send_create_password_email

Complementary action(s) to perform when creating a company:

  • get_oauth_access_tokens returns the user's access and refresh tokens
  • send_create_password_email sends a reset password token to the company owner's email so they can log in using Remote UI (not needed if integration plans to use SSO only)

If action contains send_create_password_email you can redirect the user to https://employ.remote.com/api-integration-new-password-send

header Parameters
Authorization
required
string
Example: Bearer <CLIENT-CREDENTIALS ACCESS TOKEN>

Requires a client credentials access token obtained through the Client Credentials flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Client Credentials flow.

Request Body schema: application/json

Create Company params

address_details
object

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and address_details as the form name for the placeholders. The response complies with the JSON Schema specification.

bank_account_details
object

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and bank_account_details as the form name for the placeholders. The response complies with the JSON Schema specification.

company_owner_email
required
string <email>

The company owner email.

This value cannot be changed once set.

company_owner_name
required
string

The company owner name.

This value cannot be changed from the Remote API once set.

country_code
required
string

3-letter country code of the country the company address is located in.

For a list of countries supported through the Remote API, make a call to the list countries endpoint. This endpoint will also include the 3-letter country codes you can use for this field.

desired_currency
required
string
Enum: "AUD" "CAD" "CHF" "DKK" "EUR" "GBP" "JPY" "NOK" "NZD" "SEK" "SGD" "USD"

Desired currency for invoicing and displaying converted salaries in Remote UI regardless of the employee's country.

email_domain
string

The domain of the company. Use this field to specify the company domain name when it's different from the domain in the company owner's email.

external_id
string

Id of the company as represented in the external partner system.

name
required
string

The company name

phone_number
string

A phone number the company can be contacted with.

registration_number
string

The company registration number. This field or tax_number (but not both) should be submitted.

tax_number
string

The tax identifier of the company. This field or registration_number (but not both) should be submitted.

terms_of_service_accepted_at
required
string <date-time>

Date and time the Terms of Service were accepted. To ensure users read the most recent version of Remote's Terms of Service, their action cannot have been done more than fifteen minutes ago. The UTC offset must be included in the ISO 8601 format: YYYY-MM-DD HOURS:MINUTES:SECONDSZ

Responses

Request samples

Content type
application/json
{
  • "address_details": {
    },
  • "bank_account_details": {
    },
  • "company_owner_email": "ceo@techvision.com",
  • "company_owner_name": "Joe Smith",
  • "country_code": "USA",
  • "desired_currency": "USD",
  • "external_id": "00001111",
  • "name": "Tech Vision",
  • "phone_number": "+11123123456",
  • "tax_number": "123456789",
  • "terms_of_service_accepted_at": "2022-05-05 15:03:45Z"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Show a company

Given an ID, shows a company

Authorizations:
OAuth2
path Parameters
company_id
required
string
Example: 0a8s2d1-company-id-2e3f4th

Company ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a company

Given an ID and a request object with new information, updates a company.

Getting a company and its owner to active status

If you created a company using the create a company endpoint without all the required request body parameters, you can use this endpoint to provide the missing data. Once the company and its owner have all the necessary data, both their statuses will be set to active and the company onboarding will be marked as "completed".

The following constitutes a company with "all the necessary data":

  • Complete address, with valid address, postal_code, country and state parameters (Varies by country. Use the show form schema endpoint to see which address parameters are required).
  • Company tax_number or registration_number is not nil
  • Company name is not nil (already required when creating the company)
  • Company has a desired_currency in their bank account (already required when creating the company)
  • Company has accepted terms of service (already required when creating the company)
Authorizations:
OAuth2
path Parameters
company_id
required
string
Example: 0a8s2d1-company-id-2e3f4th

Company ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Update Company params

address_details
object

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and address_details as the form name for the placeholders. The response complies with the JSON Schema specification.

bank_account_details
object

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and bank_account_details as the form name for the placeholders. The response complies with the JSON Schema specification.

country_code
string

Country of company address

desired_currency
string
Enum: "AUD" "CAD" "CHF" "DKK" "EUR" "GBP" "JPY" "NOK" "NZD" "SEK" "SGD" "USD"

Desired currency for invoicing and displaying converted salaries in Remote UI regardless of the employee's country.

This field is only accepted if company is in status pending. Please contact Remote if you wish to update it.

name
string

This field is only accepted if company is in status pending. Please contact Remote if you wish to update it.

phone_number
string

A phone number the company can be contacted with.

registration_number
string

The company registration number. This field or tax_number (but not both) should be submitted.

This field is only accepted if company is in status pending.

tax_number
string

The tax identifier of the company. This field or registration_number (but not both) should be submitted.

This field is only accepted if company is in status pending.

Responses

Request samples

Content type
application/json
{
  • "address_details": {
    },
  • "bank_account_details": {
    },
  • "country_code": "USA",
  • "desired_currency": "USD",
  • "name": "Tech Vision",
  • "phone_number": "+11123123456",
  • "tax_number": "123456789"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a company

Given an ID and a request object with new information, updates a company.

Getting a company and its owner to active status

If you created a company using the create a company endpoint without all the required request body parameters, you can use this endpoint to provide the missing data. Once the company and its owner have all the necessary data, both their statuses will be set to active and the company onboarding will be marked as "completed".

The following constitutes a company with "all the necessary data":

  • Complete address, with valid address, postal_code, country and state parameters (Varies by country. Use the show form schema endpoint to see which address parameters are required).
  • Company tax_number or registration_number is not nil
  • Company name is not nil (already required when creating the company)
  • Company has a desired_currency in their bank account (already required when creating the company)
  • Company has accepted terms of service (already required when creating the company)
Authorizations:
OAuth2
path Parameters
company_id
required
string
Example: 0a8s2d1-company-id-2e3f4th

Company ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

Update Company params

address_details
object

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and address_details as the form name for the placeholders. The response complies with the JSON Schema specification.

bank_account_details
object

Fields can vary depending on the country. Please, check the required fields structure using the Show form schema endpoint. Use the desired country and bank_account_details as the form name for the placeholders. The response complies with the JSON Schema specification.

country_code
string

Country of company address

desired_currency
string
Enum: "AUD" "CAD" "CHF" "DKK" "EUR" "GBP" "JPY" "NOK" "NZD" "SEK" "SGD" "USD"

Desired currency for invoicing and displaying converted salaries in Remote UI regardless of the employee's country.

This field is only accepted if company is in status pending. Please contact Remote if you wish to update it.

name
string

This field is only accepted if company is in status pending. Please contact Remote if you wish to update it.

phone_number
string

A phone number the company can be contacted with.

registration_number
string

The company registration number. This field or tax_number (but not both) should be submitted.

This field is only accepted if company is in status pending.

tax_number
string

The tax identifier of the company. This field or registration_number (but not both) should be submitted.

This field is only accepted if company is in status pending.

Responses

Request samples

Content type
application/json
{
  • "address_details": {
    },
  • "bank_account_details": {
    },
  • "country_code": "USA",
  • "desired_currency": "USD",
  • "name": "Tech Vision",
  • "phone_number": "+11123123456",
  • "tax_number": "123456789"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Countries

List countries

Returns a list of all countries that are supported by Remote API alphabetically ordered. The supported list accounts for creating employment with basic information and it does not imply fully onboarding employment via JSON Schema.

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <ANY ACCESS TOKEN>

This endpoint works with any of the access tokens provided. You can use an access token obtained through the Client Credentials flow, the Authorization Code flow, or the Refresh Token flow.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List all holidays of a country

List all holidays of a country for a specific year. Optionally, it can be filtered by country subdivision.

Authorizations:
OAuth2
path Parameters
country_code
required
string
Example: PRT

Country code according to ISO 3166-1 3-digit alphabetic codes

year
required
string
Example: 2022

Year for the holidays

query Parameters
country_subdivision_code
string
Example: country_subdivision_code=PT-10

Country subdivision code according to ISO 3166-2 codes

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Show form schema

Returns the json schema of a supported form. Possible form names are:

- address_details 
- administrative_details 
- bank_account_details 
- employment_basic_information 
- billing_address_details 
- contract_details 
- emergency_contact 
- employment_document_details 
- personal_details 
- pricing_plan_details

This endpoint requires a company access token, as forms are dependent on certain properties of companies and their current employments.

Authorizations:
OAuth2
path Parameters
country_code
required
string
Example: PRT

Country code according to ISO 3-digit alphabetic codes

form
required
string
Example: address_details

Name of the desired form

query Parameters
employment_id
string
Example: employment_id=663e0b79-c893-45ff-a1b2-f6dcabc098b5

Required for contract_amendment form

only_for_testing_include_scheduled_benefit_groups
boolean

FOR TESTING PURPOSES ONLY: Include scheduled benefit groups.

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhook Callbacks

Delete a Webhook Callback

Delete a callback previously registered for webhooks

Authorizations:
OAuth2
path Parameters
id
required
string

Webhook Callback ID

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a Webhook Callback

Register a callback to be used for webhooks

Authorizations:
OAuth2
header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Request Body schema: application/json

WebhookCallback

subscribed_events
Array of strings
Items Enum: "billing_document.issued" "contract_amendment.canceled" "contract_amendment.deleted" "contract_amendment.done" "contract_amendment.review_started" "contract_amendment.submitted" "custom_field.value_updated" "employment_contract.active_contract_updated" "employment.account.updated" "employment.details.updated" "employment.onboarding_task.completed" "employment.onboarding.completed" "employment.personal_information.updated" "employment.user_status.activated" "employment.user_status.deactivated" "expense.approved" "expense.declined" "expense.deleted" "expense.reimbursed" "expense.submitted" "expense.updated" "identity_verification.verification_required" "incentive.created" "incentive.deleted" "incentive.paid" "incentive.processing_started" "incentive.updated" "offboarding.deleted" "offboarding.done" "offboarding.review_started" "offboarding.submitted" "offboarding.submitted_to_payroll" "offboarding.completed" "payslip.released" "timeoff.approved" "timeoff.canceled" "timeoff.date_changed" "timeoff.declined" "timeoff.requested" "timeoff.taken" "timeoff.updated"
url
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Time Off Balances

Show Time Off Balance

Shows the time off balance for the given employment_id.

Please note, this endpoint is only supported for employments in certain countries. For countries where it's not supported, this endpoint will respond with a 404 Not Found.

Authorizations:
OAuth2
path Parameters
employment_id
required
string
Example: 03675381-50c9-492d-b8ed-e84e99046091

Employment ID for which to show the time off balance

header Parameters
Authorization
required
string
Example: Bearer <COMPANY-SCOPED ACCESS TOKEN>

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Benefit Offers

List Benefit Offers

List benefit offers for each country.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}