Quick Start Guide

Introduction

Welcome to the Remote API documentation. In here you will find everything you need to easily consolidate and share global employee data across your HR Tech stack.

The Remote API is composed of a set of RESTful resources protected by OAuth2 Authentication. They follow the REST pattern using JSON messages as the only accepted format, and respect standard HTTP verbs and status codes.

What will you need?

• A Remote.com account
• A software developer with admin access to your Remote.com account

Getting started

1. Define Your Objectives

   Determine your goals for using the API. For inspiration, see our Use Case and Examples.

2. Access the Sandbox Environment

   There is a sandbox environment available if you want to experiment with the API and validate results before making changes to your production company. To access the sandbox environment:

   • Log in to your remote.com account.
   • Navigate to Integrations > Remote API > Access API
   • On the right hand panel Here you will find a link to the sandbox environment.
   
   

   📘

   Note: You must have "company admin" role to access the integrations page

   
   

3. Create a Test Company in Sandbox

   • In the sandbox environment, create a company that you can use for testing.
   • To create a company, click Sign Up and go through the company sign up flow.
   • You can also add a hire. Don’t worry, you won’t be charged for any test employments you create for this company.

4. Get an API access token in Sandbox

   Next, sign in to your new test company account and generate an access token. See Obtaining access token for instructions on how to generate a token.

   This token will only work for API requests made to the sandbox environment (https://gateway.remote-sandbox.com).

5. Send your first request to the API

   Now that you have an access token, use it to try out some requests to the sandbox environment.

   Below is an example of creating your first employment in your test company. In this example, we provide the minimum set of data required to add an employee to the Onboarding page in Remote.

   Bash

   curl --location --request POST \
     --header "Authorization: Bearer <*your token*>" \
     --header "Content-Type: application/json" \
     https://gateway.remote-sandbox.com/v1/employments \
     --data '{
     "company_id": "*the Remote ID for your test company*",
     "country_code": "*the country where your employee will be employed*",
     "full_name": "*the full name of your employee*",
     "job_title": "*the job title of your employee*",
     "personal_email": "the personal email address of your employee",
     "type": "employee",
     "provisional_start_date": "a start date in the future"
     }'
   

   • company_id - you can find your company ID by logging in to your test company and going to Company settings > Company information > General information.
   • country_code - This needs to be an ISO 3166-1 3-digit alphabetic code for the country where your employee is being employed.

   Next, log in to your test company and confirm that your new employee appears in the Onboarding page. From here you can send an invitation through the Remote UI asking the new employee to finish onboarding tasks in Remote.

6. Deploy to Production

   Once you’re confident that your API requests are working as expected, you can take the following steps to start sending requests to your production company.

   1. Sign in to your production company and generate a production token following the same steps in “4. Get an API access token”.
   2. Change the path for your requests from the sandbox environment (https://gateway.remote-sandbox.com) to the production environment (https://gateway.remote.com).