A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Remote API is how an app or AI agent works with a Remote company: listing and onboarding employments, requesting and approving time off, reviewing timesheets and payroll, and reading contractor invoices. Access is granted through an organization-scoped API token, or OAuth 2.0 for partners with per-area scopes, that sets which areas a call can read or write. Remote drives country-specific onboarding from dynamic JSON Schema forms, and it can push events to a registered endpoint when records change.
How an app or AI agent connects to Remote determines what it can reach. A first-party integration calls with an organization-scoped API token, a partner integration uses OAuth 2.0, and Remote can push events to a registered endpoint, with each route governed by the token behind it and the permissions that token carries.
The REST API uses JSON over standard HTTP verbs and status codes, with page-based lists, at the production gateway https://gateway.remote.com and the sandbox at https://gateway.remote-sandbox.com. A first-party call authenticates with an organization-scoped API token as a Bearer token. Resources are versioned in the path, v1 for most and v2 for some employment endpoints.
Partners connect with OAuth 2.0, using the client-credentials flow with a client id and secret and a refresh-token flow to renew access. Access tokens last one hour (3600 seconds) and carry per-area read and write scopes, like employment:read and timeoff:write, so a partner integration reaches only the areas its scopes were granted.
Remote POSTs an event to an HTTPS endpoint when a record changes, across employments, contracts, time off, expenses, incentives, payslips, and companies. Payloads are stateless and carry the resource ids, so an integration re-fetches current details, and the endpoint returns a 2XX response to confirm delivery. Webhook deliveries can be verified for authenticity.
A first-party API token is organization-scoped and broad: it can read and write across the company's data and is not split into per-area scopes. It is sent as a Bearer token in the Authorization header, and only a company admin or owner can generate or revoke it. The ra_live prefix marks a production token and ra_test a sandbox token, and the two never cross environments.
Partners authenticate with OAuth 2.0, using the client-credentials flow (client id and secret) or a refresh-token flow to renew access. Tokens are valid for one hour and carry per-area read and write scopes, so a partner reaches only the areas its scopes cover.
The Remote API is split into areas an agent can act on, like employments, contracts, time off, timesheets, payroll, invoices, and companies. Each area has its own methods, and writes in some areas change a worker's records, approve leave, or move a contract forward.
Methods for listing, onboarding, and updating employment records.
Methods for employment contracts and contract amendments.
Methods for requesting, approving, and canceling time off.
Methods for reviewing and approving submitted timesheets.
Methods for reading payroll calendars.
Methods for companies, managers, and departments.
Methods for supported countries, holidays, and country form schemas.
Methods for contractor invoices, schedules, and billing documents.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
EmploymentsMethods for listing, onboarding, and updating employment records.7 | ||||||
| GET | /v1/employments | List employments in the company, filterable by status and other fields. | read | employment:read | Current | |
Per-area scope on OAuth; a first-party API token is broad and reads this without a per-area scope. Filtering by multiple statuses was added 2025-03-06. Acts onemployment Permission (capability) employment:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/employments | Create an employment to begin onboarding a worker in a country. | write | employment:write | Current | |
The payload follows the country's JSON Schema form; fetch the schema first. Acts onemployment Permission (capability) employment:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/employments/{employment_id} | Show a single employment record. | read | employment:read | Current | |
Read-only. Acts onemployment Permission (capability) employment:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/employments/{employment_id} | Update an employment record (v1). | write | employment:write | Current | |
A v2 of this endpoint exists with newer fields. Acts onemployment Permission (capability) employment:writeVersionAvailable since the API’s base version Webhook event employment.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/employments/{employment_id} | Update an employment record (v2), with newer fields. | write | employment:write | Current | |
The v2 surface for some employment endpoints; prefer it for newer fields. Acts onemployment Permission (capability) employment:writeVersionAvailable since the API’s base version Webhook event employment.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/employments/{employment_id}/invite | Invite an employment to complete its own onboarding. | write | employment:write | Current | |
Sends the worker an invitation to self-serve their details. Acts onemployment Permission (capability) employment:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/ready | Mark onboarding complete for an employment so it is ready. | write | employment:write | Current | |
Signals that the employment's details are complete. Acts onemployment Permission (capability) employment:writeVersionAvailable since the API’s base version Webhook event employment.onboarding.completedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contracts & amendmentsMethods for employment contracts and contract amendments.3 | ||||||
| GET | /v1/employment-contracts | List employment contracts. | read | contract:read | Current | |
Read-only. Acts onemployment_contract Permission (capability) contract:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/contract-amendments | List contract amendments. | read | contract_amendment:read | Current | |
Read-only. Acts oncontract_amendment Permission (capability) contract_amendment:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/contract-amendments | Create a contract amendment for an employment. | write | contract_amendment:write | Current | |
The payload follows the amendment's JSON Schema form. Acts oncontract_amendment Permission (capability) contract_amendment:writeVersionAvailable since the API’s base version Webhook event contract_amendment.doneRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Time offMethods for requesting, approving, and canceling time off.6 | ||||||
| GET | /v1/timeoff | List time off requests, filterable by status. | read | timeoff:read | Current | |
Read-only. Acts ontimeoff Permission (capability) timeoff:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/timeoff/{id} | Show a single time off request. | read | timeoff:read | Current | |
Read-only. Acts ontimeoff Permission (capability) timeoff:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/timeoff | Create a time off request, tied to a time off type and status. | write | timeoff:write | Current | |
This API currently supports creating approved requests; an employee token omits employment_id. Acts ontimeoff Permission (capability) timeoff:writeVersionAvailable since the API’s base version Webhook event timeoff.requestedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/timeoff/{id} | Update an existing time off request. | write | timeoff:write | Current | |
Changes the request's dates or details. Acts ontimeoff Permission (capability) timeoff:writeVersionAvailable since the API’s base version Webhook event timeoff.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/timeoff/{id}/approve | Approve a pending time off request. | write | timeoff:write | Current | |
Moves the request to approved. Acts ontimeoff Permission (capability) timeoff:writeVersionAvailable since the API’s base version Webhook event timeoff.approvedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/timeoff/{id}/cancel | Cancel a time off request. | write | timeoff:write | Current | |
There are also approve_cancellation and decline_cancellation actions for canceling approved leave. Acts ontimeoff Permission (capability) timeoff:writeVersionAvailable since the API’s base version Webhook event timeoff.canceledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TimesheetsMethods for reviewing and approving submitted timesheets.3 | ||||||
| GET | /v1/timesheets | List timesheets for the company, filterable by status (open, submitted, in_calibration, processed). | read | timesheet:read | Current | |
Read-only. Acts ontimesheet Permission (capability) timesheet:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/timesheets/{id}/approve | Approve a submitted timesheet. | write | timesheet:write | Current | |
Approves the worker's submitted hours. Acts ontimesheet Permission (capability) timesheet:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/timesheets/{id}/send-back | Send a timesheet back to the employee for review or modification. | write | timesheet:write | Current | |
Returns the timesheet to the worker instead of approving it. Acts ontimesheet Permission (capability) timesheet:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PayrollMethods for reading payroll calendars.2 | ||||||
| GET | /v1/payroll-calendar | List payroll calendar periods. | read | — | Current | |
Read-only reference data; no dedicated read scope is documented for this endpoint. Acts onpayroll_calendar Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/eor-payroll-calendar | List EOR payroll calendar periods for Employer of Record workers. | read | — | Current | |
Read-only reference data. Acts onpayroll_calendar Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CompaniesMethods for companies, managers, and departments.3 | ||||||
| GET | /v1/companies | List companies, filterable by external_id. | read | company:read | Current | |
Filtering by external_id was added 2025-03-21. Acts oncompany Permission (capability) company:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/companies | Create a company (for partners onboarding new companies). | write | company:write | Current | |
The payload follows the company JSON Schema form. Acts oncompany Permission (capability) company:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/company-managers | Create and invite a company manager (an admin user). | write | company_manager:write | Current | |
Grants a person admin access to the company. Acts oncompany_manager Permission (capability) company_manager:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Countries & formsMethods for supported countries, holidays, and country form schemas.3 | ||||||
| GET | /v1/countries | List the supported countries, with ISO codes and onboarding support. | read | — | Current | |
Reference data; requires a valid token but no per-area scope. Acts oncountry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/countries/{country_code}/{form} | Get the JSON Schema form fields a country requires for a given form, like employment basics. | read | — | Current | |
Drives country-specific onboarding fields; pass an ISO 3166-1 alpha-3 country code and a form name. Acts oncountry_form Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/countries/{country_code}/holidays | List public holidays for a country and year. | read | — | Current | |
Reference data; accepts country_code, year, and an optional country_subdivision_code. Acts onholiday Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Invoices & billingMethods for contractor invoices, schedules, and billing documents.4 | ||||||
| GET | /v1/contractor-invoices | List contractor invoices. | read | invoices:read | Current | |
Read-only. Acts oncontractor_invoice Permission (capability) invoices:readVersionAvailable since the API’s base version Webhook event contractor_invoice.paid_outRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/contractor-invoices/{id} | Show a single contractor invoice. | read | invoices:read | Current | |
Read-only. Acts oncontractor_invoice Permission (capability) invoices:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/contractor-invoice-schedules | Create a recurring contractor invoice schedule. | write | invoices:write | Current | |
Sets up automatic invoicing for a contractor. Acts oncontractor_invoice_schedule Permission (capability) invoices:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/billing-documents | List billing documents for the company. | read | invoices:read | Current | |
Read-only. Acts onbilling_document Permission (capability) invoices:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Remote can notify an app when something happens in an account, like a time off request being approved or an employment being updated. It POSTs an event describing what changed, and the payload carries the resource ids so an integration re-fetches the current details rather than trusting the message body.
| Event | What it signals | Triggered by |
|---|---|---|
timeoff.requested | A time off request was submitted and is awaiting a decision. | /v1/timeoff |
timeoff.approved | A time off request was approved. | /v1/timeoff/{id}/approve |
timeoff.canceled | A time off request was canceled. | /v1/timeoff/{id}/cancel |
timeoff.updated | A time off request was changed, like its dates or details. | /v1/timeoff/{id} |
employment.updated | An employment record was updated. | /v1/employments/{employment_id}/v2/employments/{employment_id} |
employment.onboarding.completed | An employment finished onboarding. | /v1/ready |
contract_amendment.done | A contract amendment completed. | /v1/contract-amendments |
contractor_invoice.paid_out | A contractor invoice was paid out to the contractor. | /v1/contractor-invoices |
Remote limits how fast an app can call, by a request rate measured per minute and counted across a whole company rather than per token.
Remote limits authenticated requests to 300 per minute, counted per company rather than per token, so tokens that belong to the same company share one budget. The one-minute window starts at the first request and resets 60 seconds later. Every authenticated response carries x-ratelimit-count, x-ratelimit-remaining, and x-ratelimit-reset headers, and going over returns HTTP 429 with an explanatory message.
List endpoints are page-based: a page query parameter selects the page and page_size sets how many results it returns, and the response carries the current page and total counts so a client can walk through the full set.
A request and response use JSON over standard HTTP verbs and status codes. Page size is set by the page_size parameter on list endpoints. Country onboarding forms are described by a JSON Schema fetched per country and form, so a client validates and submits only the fields that country requires.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid token was provided, or the token is for the wrong environment (an ra_test token against production, or ra_live against the sandbox). | Send a valid Bearer token for the correct environment, and rotate the token if it may be compromised. |
| 403 | forbidden | The token is valid but lacks access to this action or resource, for example a partner OAuth token missing the area's scope. | Grant the needed scope on the OAuth token, or use a token with access to the company and resource. |
| 404 | not_found | The requested resource does not exist, or is not visible to this token or company. | Verify the id and confirm the resource belongs to the same company and environment as the token. |
| 422 | unprocessable_entity | The request was well-formed but failed validation, for example a payload missing a field the country's JSON Schema form requires. | Read the validation errors, fetch the country form schema, and resend with the required fields. |
| 429 | too_many_requests | The company exceeded 300 requests in the one-minute window. The limit is shared across all tokens for the company. | Back off until x-ratelimit-reset, then retry; smooth request volume so the per-company count stays under 300 per minute. |
Remote versions its API in the request path, with a stable v1 surface and a newer v2 for some employment endpoints, and ships dated changes through its developer changelog.
Remote versions in the request path. The v1 surface is stable and covers most resources, and a newer v2 exists for some employment endpoints, like updating an employment, basic information, address, contract, and bank details. Dated changes ship through the developer changelog.
The List Companies endpoint added the ability to filter by external_id, the identifier an integration assigns to a company.
The List Employments endpoint added filtering by multiple statuses at once, and exposed an employment_lifecycle_stage field.
Call v2 where it exists for newer employment fields, and stay on v1 elsewhere.
Remote API changelog ↗Bollard AI sits between a team's AI agents and Remote. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.