Changelog

2024-02-28

Improvement

New field was added to create an expense in the existing endpoint

Both single object receipt or a 1-element list of receipts can be used to create an expense with the POST /v1/expenses endpoint.

If both receipt and receipts are in the request body, the endpoint will respond with a 400 Bad Request error.

An expense can be created using receipt request body property with POST /v1/expenses, for example:

json
1{
2 "employment_id": "9d79f993-9180-4a93-8f3e-b07fa33fc8dc",
3 "amount": 212,
4 "category": "education_training",
5 "currency": "EUR",
6 "expense_date": "2024-02-27",
7 "receipt": {
8 "content": "<binary content of the file encoded in base64>",
9 "name": "expense.pdf"
10 },
11 "tax_amount": 23,
12 "timezone": "Australia/Sydney",
13 "title": "Coursera Python Course"
14}

Or it can be created using receipts request body property with POST /v1/expenses, for example:

json
1{
2 "employment_id": "9d79f993-9180-4a93-8f3e-b07fa33fc8dc",
3 "amount": 212,
4 "category": "education_training",
5 "currency": "EUR",
6 "expense_date": "2024-02-27",
7 "receipts": [
8 {
9 "content": "<binary content of the file encoded in base64>",
10 "name": "expense.pdf"
11 }
12 ],
13 "tax_amount": 23,
14 "timezone": "Australia/Sydney",
15 "title": "Coursera Python Course"
16}

2024-02-27

Improvement

Adding a new field called active_contract_id to Employment.

Adding a new required amendment_contract_id to the POST v1/contract-amendment and POST v1/contract-amendment/automatable endpoints. This field corresponds to the active_contract_id of the employment that needs to be amended.

2024-02-22

Improvement

New endpoint to download expense receipt by id

A new receipt download endpoint and a new receipts property have been added to expense objects to support multiple receipts per expense.

The new receipts property is added to the response for GET v1/expenses and GET v1/expenses/{id}.

Example:

json
1{
2 "data":{
3 "expense":{
4 "id":"9d79f993-9180-4a93-8f3e-b07fa33fc8dc",
5 "reason":null,
6 "status":"pending",
7 "title":"Coursera Python Course",
8 "category":"education_training",
9 "currency":{
10 "code":"EUR",
11 "name":"European Euro",
12 "symbol":"€"
13 },
14 "amount":986,
15 "tax_amount":241,
16 "notes":null,
17 "invoice_period":null,
18 "reviewed_at":null,
19 "employment_id":"611d3ed7-23c8-4c02-9349-cc5db5fdea1b",
20 "converted_amount":212,
21 "converted_currency":{
22 "code":"EUR",
23 "name":"European Euro",
24 "symbol":"€"
25 },
26 "reviewer":null,
27 "receipts":[
28 {
29 "id":"f03d8525-eead-46ac-a0d9-ab0fc005f74e",
30 "name":"expense-1.pdf",
31 "type":"expense",
32 "inserted_at":"2024-02-22T08:42:30Z"
33 },
34 {
35 "id":"c0c7a920-8b4c-4394-ae23-be121f9e9eb6",
36 "name":"expense-2.pdf",
37 "type":"expense",
38 "inserted_at":"2024-02-22T08:56:11Z"
39 }
40 ],
41 "expense_date":"2024-02-22",
42 "converted_tax_amount":756
43 }
44 }
45}

The id from the receipts property should now be used to expense receipts.

The new endpoint for downloading expense receipts by id is GET /v1/expenses/{expense_id}/receipts/{receipt_id}.

The existing download endpoint, GET /v1/expenses/{expense_id}/receipt, has been deprecated but will continue to work.

2024-02-09

Improvement

Webhook `offboarding.submitted` now also triggered in resignation requests

The offboarding.submitted webhook event is now also triggered when an employee requests a resignation.

2024-02-08

Bug Fixes

Remove the :deleted status from the Offboarding API docs.

For more information, see the API Spec pages.

2024-02-07

Feature

Enhancements to Employment Creation Process

  • Integration of Department id and name Fields:
    • Endpoint Update: The POST v1/employments endpoint now supports the department object within the employment creation payload. This object can include either a name field for creating and associating a new department or an id field for associating an existing department with the newly created employment record.
    • Usage in Employment Creation:
      1. For Existing Departments: To associate an employment with an existing department, include the department.id field in your request payload.
      2. For New Departments: To create and associate a new department with an employment, include the department.name field in your request payload.
      • Important Note: Only one of these fields, id or name, should be included in the department object for each request to avoid processing errors.

Examples of Employment Creation Payloads

  • Associating an Existing Department:
json
1{
2 "country_code": "CAN",
3 "basic_information": {
4 "name": "John Doe",
5 "job_title": "Software Engineer",
6 "email": "john.doe@example.com",
7 "provisional_start_date": "2024-05-01",
8 "has_seniority_date": "no",
9 "department": {
10 "id": "existing-department-id"
11 },
12 "manager": {
13 "id": "manager-id"
14 }
15 },
16 "type": "employee"
17}
  • Creating and Associating a New Department:
json
1{
2 "country_code": "CAN",
3 "basic_information": {
4 "name": "Jane Smith",
5 "job_title": "Product Manager",
6 "email": "jane.smith@example.com",
7 "provisional_start_date": "2024-06-15",
8 "has_seniority_date": "no",
9 "department": {
10 "name": "Innovation Department"
11 },
12 "manager": {
13 "id": "manager-id"
14 }
15 },
16 "type": "employee"
17}

These examples illustrate how to correctly use the department feature within the employment creation process, either by associating with an existing department or by creating a new one. Please ensure that the payload for your employment creation requests adheres to these guidelines.

2024-01-31

Feature

Introducing Timeoff Approved Webhook Events

Introduced the timeoff.approved webhook event. For more information, see the API Spec pages.

2024-01-30

Improvement

Webhook timeoff.canceled is now also triggered when an automatic holiday is removed

This event is now triggered when a holiday created by the Automatic Holiday feature is removed. For more information, see the API Spec pages.

2024-01-29

Feature

Adding a new field calledobserved_day to Holiday.

Depending on the country, not all public holidays are celebrated, or observed, on the actual official date of the holiday. When this happens, it’s called an observed holiday – which ensures that employees will be able to enjoy a day off of work despite the actual holiday landing on a weekend day. For example, in the United States, when Independence Day (July 4) lands on a Saturday, it is observed on the Friday before. If it happens to land on a Sunday, it is observed on the following Monday (July 5).

2024-01-26

Feature

Introducing the GET api/v1/company-departments endpoint

API users can now request a list of the company-department records that are associated to a given Company by specifying the company_id as a (required) query parameter.

For more information, see the API Spec Page.

(An example request is included in the Postman collection for Partners, available here.)

2024-01-25

Improvement

Introducing management of the association between an employment and a department

When updating an employment, its department_id can now be specified in the request body for the Update Employment endpoint, in order to associate the employment to that department, where both must belong to the same company.

An associated department can now also be unassociated from an employment by explicitly including a null value for department_id in the request body for the Update Employment endpoint.

(To help construct such associations, List Departments and Create Department endpoints are planned for release this week.)

For more information, see the API Spec Page (partner link).

2024-01-25

Feature

Introducing the accurate termination date in the Offboarding API

Now the Offboarding API will include the accurate termination_date in its responses. For more information, see the API Spec pages.

2024-01-25

Feature

Introducing the POST api/v1/company-departments endpoint

API users can now describe an aspect of company structure in the form of company-department records which specify a Company Department’s name and its company_id association to a Company.

Department name must be non-empty with no more than 255 characters (Unicode code points).

This feature is part of a project to support association of an employment to a company-department. (Additional support is planned for release this week, including a new List Departments endpoint and an improvement to the Update Department endpoint.)

For more information, see the API Spec Page.

(An example request is included in the Postman collection for Partners, available here.)

2024-01-23

Feature

Introducing Timeoff Taken Webhook Events

Introduced the timeoff.taken webhook event. For more information, see the API Spec pages.

2024-01-22

Feature

Introducing working_hours_per_day field in Time Off Balance

Now, the Time Off Balance endpoint also include the working_hours_per_day field in its response. For more information, see the API Spec pages.

2024-01-18

Feature

Introducing contractual_leave_entitlement_type field in Time Off Balance

Now, the Time Off Balance endpoint also include the contractual_leave_entitlement_type field in its response. For more information, see the API Spec pages.

2024-01-18

Feature

Introducing Timeoff Updated Webhook Events

Introduced the timeoff.updated webhook event. For more information, see the API Spec pages.

2024-01-12

Fix

Webhook `timeoff.date_changed` is now also triggered when time off hours are updated

Previously, this event was only triggered when time off dates were updated. Now, it is also triggered when the number of hours is updated.

2024-01-11

Improvement

Introducing fields for Department ID and Name in responses to Show, Update, and List Employments

Previously, when an employment held an association to a department, only the department’s name was included in the response as the department field on the employment.

Now, the unique department_id is also included in the employment response data and both department and department_id added consistently to these endpoints where not already present before.

For more information, see the API Spec Page and its response specifications and examples for these endpoints.

2024-01-02

Feature

Introducing Offboarding Done Webhook Events

Introduced the offboarding.done webhook event. For more information, see the API Spec pages.

2023-12-27

Improvement

Changed the offboarding.in_review webhook event name to offboarding.review_started. For more information, see the API Spec pages.

2023-12-20

Feature

Introducing Offboarding In Review Webhook Events

Introduced the offboarding.in_review webhook event. For more information, see the API Spec pages.

2023-12-19

Feature

Introducing Offboarding Submitted Webhook Events

Introduced the offboarding.submitted webhook event. For more information, see the API Spec pages.

2023-12-15

New Feature

Introduced the incentive.processing_started webhook event. For more information, see the API Spec pages.

2023-12-12

New Feature

Enhancements to Employment Creation Process

  • Integration of manager > id :
    • Endpoint Update: The endpoint GET /v1/countries/:country/employment_basic_information has been enhanced to include a new fieldset: manager which returns a property called id with a list of managers that could be associated with the employment creation.
    • Usage in Employment Creation:
      • The manager field set with the id field is now available for use with the POST /v1/employments endpoint. This field allows for the association of an existing manager with the newly created employment.

2023-12-08

New Feature

Modification to the timeoff-balances endpoint

Fixes the timeoff-balancesendpoint so that the contractual_entitled field now returns an integer. This value correponds to the number of time off days for the employment, based on their contract. For more information, see the API Specs pages.

Feature

Introducing Offboarding Deleted Webhook Events

Introduced the offboarding.deleted webhook event. For more information, see the API Spec pages.

2023-12-06

Improvement

New error message showed when requesting a form that a country does not have available

When GET v1/countries/:country_code/:form is called, if the country referring to the given country_code has not available the given form then the specific error 422 message "Form not available for requested country" is returned. For more information, see the API Spec page.

2023-11-30

Improvement

Added 3 new content types for expense receipt downloads

Response content types for GET v1/expenses/{id}/receipt now include image/webp, text/csv and application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. For more information, see the API Spec page.

2023-11-29

Improvement

Introducing status filter in list employments

Introduced a new query parameter for the GET v1/employments endpoint for listing employments based on the employement's status. More information on the API Spec page.

Feature

Introducing Employment User Status Activated Webhook Events

Introduced the employment.user_status.activated webhook event. For more information, see the API Spec pages.

Feature

Introducing Employment User Status Deactivated Webhook Events

Introduced the employment.user_status.deactivated webhook event. For more information, see the API Spec pages.

2023-11-27

Feature

Introducing Employment Account Updated Webhook Events

Introduced the employment.account.updated webhook event. For more information, see the API Spec pages.

2023-11-24

Feature

Introducing Contract Amendment Done Webhook Event

Introduced the contract_amendment.done webhook event. For more information, see the API Spec pages.

2023-11-22

Feature

Introducing Incentive Paid Webhook Event

Introduced the incentive.paid webhook event. For more information, see the API Spec pages.

Feature

Introducing Incentive Updated and Created Webhook Events

Introduced the incentive.updated and incentive.created webhook event. For more information, see the API Spec pages.

2023-11-21

Feature

Introducing Incentive Deleted webhook

Introduced the incentive.deleted webhook event. For more information, see the API Spec pages.

2023-11-16

Feature

Introducing Employment Details Updated webhook

Introduced the employment.details.updated webhook event. For more information, see the API Spec pages.

Feature

Introducing department field in Show Employment

Now, theShow employment endpoint also include the department field in its response.

2023-11-06

Improvement

Added a new possible value for the type key in Employment endpoints response.

Values can now be either employee, contractor, direct_employee or global_payroll_employee.

For more information, see the API Specs page.

2023-10-27

Feature

Introducing Expense Approved Webhook Events

Introduced the expense.approved webhook event. For more information, see the API Spec pages.

Feature

Introducing Expense Declined Webhook Events

Introduced the expense.declined webhook event. For more information, see the API Spec pages.

2023-10-04

Feature

Introducing Personnal Information Updated webhook

Introduced the employment.personal_information.updated webhook events. For more information, see the API Spec pages.

2023-09-26

Improvement

Introducing new schema to create and update employments Introduced basic_information, a new body parameter for the POST v1/employments and PATCH v1/employments endpoints for creating and updating employments. Using this field instead of the root-level body parameters is highly recommended.

As with other JSON schemas used in the API, it's possible to verify the fields for the basic_information field by sending a request to the Show form schema endpoint and replacing the form path parameter with employment_basic_information.

More information on the API Spec page.

2023-09-21

Feature

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

2023-09-13

Improvement

Introducing email filter in list employments

Introduced a new query parameter for the GET v1/employments endpoint for listing employments based on the employee's personal email. This can also be useful for finding specific employment based on email. More information on the API Spec page.

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.

Introducing Expense Receipt Download Endpoint

Introduced the GET v1/expenses/:expense_id/receipt endpoint for downloading receipt files. 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!

https://www.notion.so/remotecom/Draft-Documents-4dd5831909444063b7d295dcb1984f3e