Changelog

2023-09-21

Feature

Active employment can be updated with manager_id field and address_details , emergency_contact_details json schema.

2023-09-05

Feature

Introducing new sort option for outstanding payments and refunds

Introduced the sort_by field invoice_period on the /api/v1/employer/outstanding-payments-and-refunds endpoint

2023-08-24

Feature

Introducing Expense Webhook Events

Introduced the expense.deleted and expense.updated webhook events. For more information, see the API Spec pages.

2023-08-02

Feature

Introducing a new endpoint for inviting employees

Introduced the POST v1/employments/:employment_id/invite endpoint for inviting an employee to start the self-enrollment in the Remote Platform. More information is on the API Spec page.

2023-07-26

Features

Introducing support for direct employees

Now, the List employments and Show employment endpoints also include direct_employee s in their responses. A direct_employee is a person employed directly by the employer, without the involvement of Remote's entities.

2023-07-11

Features

Introducing Offboarding Endpoints

Added 3 new endpoints for creating, listing, and reading offboarding entries for employments. These new endpoints and their HTTP methods are as follows:

  • GET /offboardings: Get a list of offboarding entries for all employments in your company.
  • GET /offboardings/:id: Get the offboarding entry identified with :id, for an employment in your company.
  • POST /offboardings: Create an offboarding entry for an employment in your company. The employment_id is expected in the request body.

API documentation for the endpoint can be found here.

2023-06-26

Improvements

Introducing Detailed Metadata for the Contract Details - Benefits Field

Added a x-jsf-presentation keyword under the benefits field’s options in the contract_details JSON schema. The x-jsf-presentation keywords contain a meta keyword, which presents detailed information regarding the benefit option.

Previously, the benefits field only contained a label for the various benefit options, such as the following example:

json
1"benefits": {
2  "properties": {
3    "health": {
4      "oneOf": [
5				{
6				  "const": "Standard - Employee Only (Canada Life - Standard Health Employee Only; Canada Life - Standard Dental Employee Only; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability)",
7				  "title": "Standard - Employee Only - $130.00/mo + variable costs",
8				},
9				{ ... another tier ... }
10				{ ... another tier ... }
11			]
12		}
13	}
14}

This data significantly lacked in detail and omitted detailed information about the benefit, otherwise available through the Remote Employ platform.

With the new meta keyword, significantly more information is provided through the JSON schema:

json
1"benefits": {
2  "properties": {
3    "health": {
4      "oneOf": [
5				{
6				  "const": "Standard - Employee Only (Canada Life - Standard Health Employee Only; Canada Life - Standard Dental Employee Only; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability)",
7				  "title": "Standard - Employee Only - $130.00/mo + variable costs",
8				  "x-jsf-presentation": {
9				    "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (1x annual Salary), Dependant and Spouse Life, long and short term disability (66.7% weekly earnings - maximums apply).",
10				    "inputType": "radio",
11				    "meta": {
12				      "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-standard-single",
13				      "displayCost": "$130.00/mo + variable costs",
14				      "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
15				      "providerName": "Canada Life",
16							"tierName": "Standard"
17				    }
18				  }
19				},
20				{ ... another tier ... }
21				{ ... another tier ... }
22			]
23		}
24	}
25}

This meta aims to allow Remote API developers to match the Remote Employ UI as closely as possible.

Please visit the Working with Benefits guide for more details, API specs, and demo.

2023-06-14

Improvements

Improving the Time Off Balance endpoint’s entitlement expiration date parameter

  • Added a can_expire parameter to the GET /timeoff-balances response, indicating whether a time off entitlement can expire or not.
  • Improved the expiry_date parameter of the GET /timeoff-balances response. Previously, when a time off entitlement did not have an expiry date, the expiry_date parameter’s value would be "" (empty string). With this change, its value will be null.
json
1Previously, when entitlement had no expiry date:
2{
3  "data": {
4    "timeoff_balance": {
5      "timeoff_entitlements": [
6        {
7          "expiry_date": "",
8          ...
9        },
10        ...
11      ],
12      ...
13    }
14  }
15}
16

17Now, when entitlement has no expiry date:
18{
19  "data": {
20    "timeoff_balance": {
21      "timeoff_entitlements": [
22        {
23          "expiry_date": null,
24          "can_expire": false,
25          ...
26        },
27        ...
28      ],
29      ...
30    }
31  }
32}

Other Improvements

  • The default page size for paginated results was increased to 20. Previously, there was no standard for the default page size, but all default page sizes were less than 20.

2023-05-25

Introducing Employment Custom Fields Endpoints

Added new endpoints for reading employment's custom fields. These new endpoints and their HTTP methods are as follows:

  • GET /custom-fields: Get the list of all custom fields created in the company.
  • GET /custom-fields/:custom_field_id/values/:employment_id: Get the value of a given custom field for employment.

Please see the API docs for more details on how to interpret the response.

2023-05-04

Features

Introducing a new endpoint for Time Off Balance

Added a new endpoint for retrieving a summary of time off balance for employments. The new endpoint and its HTTP method is as follows:

GET /timeoff-balances/:employment_id

Please see the API docs for more details on how to interpret the response.

2023-04-10

Features

Introducing Incentive Endpoints

Added new endpoints for managing incentives for employments. These new endpoints and their HTTP methods are as follows:

One-time Incentives:

  • GET /incentives: Get the list of all incentives that belongs to a company.
  • POST /incentives: Create a new on-time incentive.
  • GET /incentives/:id: Show an incentive, given its id.
  • PUT/PATCH /incentives/:id: Update the incentive with ID :id.
  • DELETE /incentives/:id: Delete an incentive that is not processing or was paid.

Recurring Incentives

  • POST /incentives/recurring: Create a new monthly incentive.
  • GET /incentives/recurring: Get the list of all recurring incentives that belongs to a company.
  • DELETE /incentives/recurring/:id: Delete a recurring incentive, except the occurrences that are not processing or were paid.

For more information about Incentives, please check the “Working with incentives” page.

2023-03-02

Features

Webhook callbacks registered using POST /v1/webhook-callbacks will now be provided with a signing_key in the response:

json
1{
2    "data": {
3        "webhook_callback": {
4            "id": "fbac1e8a-3f38-4e1a-acbe-f046761171bf",
5            "signing_key": "wkyzvs764ifdrpct2naqhksmq4",
6            "subscribed_events": ["subscribed.event.type"],
7            "url": "<Your URL>"
8        }
9    }
10}

You can use this signing_key to authenticate webhook requests made by Remote. To this end, Remote now includes two new headers in these webhook requests sent to your callback URLs:

  • X-Remote-Signature
  • X-Remote-Timestamp

For more details, see this guide on how to verify signatures sent by Remote.

2023-02-28

Features

Introducing Webhooks and Webhook Events

Added 2 new endpoints for managing webhooks and 3 webhook events to subscribe when registering webhook callbacks.

The 2 new endpoints for managing webhooks are as follows:

  • POST /webhook-callbacks: Register a webhook URL to be called when any one of the subscribed events take place in Remote.
  • DELETE /webhook-callbacks/:id: Delete a previously registered webhook URL so it’s no longer called when the subscribed events take place in Remote.

API documentation for registering webhook URLs can be found here.

Additionally, the 3 webhook events you can subscribe are as follows:

  • employment.onboarding.completed: Triggered when an employment’s onboarding is completed and there are no more documentations left to check.
  • employment.onboarding_task.completed: Triggered when an employment’s onboarding task is completed.
  • payslip.released: Triggered when a payslip is ready and available for an employee.

API documentation for webhook events can be found in their respective categories (Employments and Payslips).

Introducing the Payslip Download Endpoint

When the payslip.released webhook event occurs, only the ID of the payslip is included in the webhook callback request. A new endpoint has been introduced to enable downloading of payslips: GET /payslips/:payslip_id/download.

API documentation for the endpoint to download a payslip can be found here.

Introducing Expense Endpoints

Added 3 new endpoints for creating, listing, and reading expense entries for employments. These new endpoints and their HTTP methods are as follows:

  • POST /expenses: Add an approved expense entry
  • GET /expenses: Get a list of expense entries
  • GET /expenses/:id: Get the expense entry identified with :id

API documentation for the expenses endpoint can be found here.

2023-02-08

Features

Introducing Delete Company Manager Endpoint

Added a new endpoint for deleting existing company managers. More information can be found on the API Specification page for the endpoint.

Introduced a new field for following the employment lifecycle

We introduced a new field to the Employments endpoints called employment_lifecycle_stage that makes it easier to determine the employee or contractor’s onboarding stage. It's available in the response of the following endpoints:

2022-12-22

Improvements

For simplicity, the alpha_2_code has been added to countries.

2022-11-30

Features

Introducing Time Off Endpoints

Added 4 new endpoints for creating, updating, and reading time off entries for employments. These new endpoints and their HTTP methods are as follows:

  • GET /timeoff: Get a list of time off entries for all employments in your company.
  • GET /timeoff/:id: Get the time off entry identified with :id, for an employment in your company.
  • POST /timeoff: Create an approved time off entry for an employment in your company. The employment_id is expected in the request body.
  • PUT or PATCH /timeoff/:id: Update an approved time off entry for an employment in your company. The employment_id is expected in the request body.

Available Time Off Types

Some of these time off endpoints require specifying the type of time off being created/updated. A new endpoint GET /timeoff/types is available to retrieve valid types along with their descriptions.

Customers can find the documentation for these endpoints on this page.

2022-10-10

Features

Added a new PUT/PATCH sandbox/employments/:employment_id endpoint for use in the Sandbox. This new endpoint can be used to set the employment status of a newly created employment to active, allowing you to use employments for testing in the Sandbox.

Customers can find the API reference for this endpoint here. Integration partners can find the API reference for this endpoint here.

2022-09-30

Documentation

Updated the Rate Limit Policy section to include explanations and examples of the HTTP headers with Rate Limit status.

2022-05-03

Documentation

Updated the Authentication section to include the OAuth 2 flows.

2022-02-01

Documentation

API Reference documentation 0.1.0 released!