Getting Started

Introduction

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

REST API

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 to write code
  • Your software developer will need admin access to your Remote.com account so they can generate an API token

Getting started

  1. Establish your goals

    Determine what you want to accomplish using the API. For inspiration, check Use Cases and Examples. To discover what endpoints and data fields are available through the API, check the API Reference.

  2. Access the sandbox

    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:

    1. Log in to your remote.com account.
    2. Navigate to Integrations > Remote API > Access API. Here you will find a link to the sandbox environment.

      Note: You need to have the “company admin” role in Remote to access this page.

  3. Create a test company

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

  4. Get an API access token

    Next, sign in to your new test company account and generate an access token. See Auth & Authorization 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.

    shell
    1curl --location --request POST \
    2 --header "Authorization: Bearer <your token>" \
    3 --header "Content-Type: application/json" \
    4 https://gateway.remote-sandbox.com/v1/employments \
    5 --data '{
    6 "company_id": "the Remote ID for your test company",
    7 "country_code": "the country where your employee will be employed",
    8 "full_name": "the full name of your employee",
    9 "job_title": "the job title of your employee",
    10 "personal_email": "the personal email address of your employee",
    11 "type": "employee",
    12 "provisional_start_date": "a start date in the future"
    13 }'
    • 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).