---
updatedAt: 2026-07-20T20:22:08.000Z
agentTools:
  projectIndex: https://developer.remote.com/llms.txt
---

# Your First API Call

Make your first authenticated request to the Remote API and get real data back.

Make your first authenticated request to the Remote API and get real data back.

## Who this is for

You have a Remote API token and want to confirm it works, see the shape of a response, and make your first real call. No SDK required, just curl and your token.

## Before you start

* **A Remote API token.** If you don't have one yet, follow the [Sandbox Quickstart](https://developer.remote.com/docs/sandbox-quickstart) to get a seeded sandbox company and a `ra_test_` token, or see [Obtaining access token](https://developer.remote.com/docs/authorization-for-customers) to generate one in the platform. Set it as an environment variable so the examples below run as-is:

  ```bash
  export REMOTE_API_TOKEN="your_token_here"
  ```

* **The base URL for your environment.** Sandbox and production are separate hosts, and tokens are bound to the environment that issued them.

  | Environment | Base URL                             | Token prefix |
  | :---------- | :----------------------------------- | :----------- |
  | Sandbox     | `https://gateway.remote-sandbox.com` | `ra_test_`   |
  | Production  | `https://gateway.remote.com`         | `ra_live_`   |

  The examples below use the sandbox host. A `ra_test_` token only works against the sandbox host, and a `ra_live_` token only works against production. Mixing them returns a `401`.

## Step 1: Confirm your token

The simplest call is `GET /v1/identity/current`. It returns the entities your token controls, so it is a quick way to confirm the token is valid and see what it can reach.

```bash
curl https://gateway.remote-sandbox.com/v1/identity/current \
  -H "Authorization: Bearer $REMOTE_API_TOKEN"
```

A `200` means your token works. For a Customer API token, the response body identifies the company and the user this token can act on behalf of:

```json
{
  "data": {
    "company": { "...": "the company this token can access" },
    "user": { "...": "the user who generated the token" }
  }
}
```

If you get a `401`, re-check the token value, the `Authorization` header, and that the token matches the host you are calling.

## Step 2: List employments (your first real call)

`GET /v1/employments` is the call most integrations start with. It returns the employments your token can see.

```bash
curl https://gateway.remote-sandbox.com/v1/employments \
  -H "Authorization: Bearer $REMOTE_API_TOKEN"
```

A successful response is `200` with this shape:

```json
{
  "data": {
    "employments": [
      { "...": "one employment record" }
    ],
    "current_page": 1,
    "total_count": 42,
    "total_pages": 3
  }
}
```

* `data.employments` is the array of records for this page.
* `data.current_page`, `data.total_count`, and `data.total_pages` describe where you are in the result set.

## Step 3: Filter and page the results

`GET /v1/employments` accepts these query params:

| Param              | What it does                                                           |
| :----------------- | :--------------------------------------------------------------------- |
| `company_id`       | Filter to one company                                                  |
| `email`            | Filter by employee email                                               |
| `status`           | Filter by employment status (see accepted values in the API reference) |
| `employment_type`  | Filter by employment type (see accepted values in the API reference)   |
| `employment_model` | Filter by employment model (see accepted values in the API reference)  |
| `short_id`         | Filter by an employment's short ID                                     |
| `page`             | Which page to fetch (default `1`)                                      |
| `page_size`        | How many records per page (default `20`, max `100`)                    |

Example: fetch the second page, 20 records at a time.

```bash
curl "https://gateway.remote-sandbox.com/v1/employments?page=2&page_size=20" \
  -H "Authorization: Bearer $REMOTE_API_TOKEN"
```

Walk pages by incrementing `page` until it reaches `data.total_pages`.

## Good to know

* Filter values for `status`, `employment_type`, and `employment_model` are fixed sets. Check the [List employments](/reference/get_v1_employments) reference for the accepted values before you hard-code them.
* Every response carries rate limit headers (`x-ratelimit-count`, `x-ratelimit-remaining`, `x-ratelimit-reset`). See the [Rate Limit Policy](https://developer.remote.com/docs/rate-limit) for the limits and how to back off.
* The same data is available across surfaces (API, MCP, SDK, CLI). The difference is only how you fetch it. This page uses raw curl so you can see exactly what is on the wire.

## Next

Polling `/v1/employments` on a loop works, but if you want to know the moment something changes, subscribe to a webhook instead of polling. See [Introduction to Webhooks](https://developer.remote.com/docs/introduction-to-webhooks) to get change events pushed to you.