Your First API Call

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 to get a seeded sandbox company and a ra_test_ token, or see Obtaining access token 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.

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:

{
  "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.

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

A successful response is 200 with this shape:

{
  "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:

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

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 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 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 to get change events pushed to you.