> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/remote.md).

# Remote

Connect to Remote to work with your global workforce: list the people your company employs, read one person's record, add a new hire for a given country, review time off, and pull billing documents.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector          | Authentication |
| ------------------ | -------------- |
| Remote (API Token) | API Token      |

### Remote (API Token)

Connect to Remote with an API token to read employments, time off, and billing documents, and to create new hires. A company admin or owner mints the token in the Remote dashboard and picks its scopes there. Sandbox and production are separate environments with separate tokens.

#### Set up in Remote

1. Prepare the Remote account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Token:** A Remote API token, minted by a company admin or owner under Company > Company Settings > Integrations & APIs > Integrations > the Remote API card > Generate API token. Scopes are chosen at mint time (Read only, Full access, or Custom endpoints), so a token that is too narrow fails specific actions rather than the connection itself.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **Remote (API Token)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required                 | What to enter                                                                                                                                                                                                                                                                                                                                  |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Token     | Yes                      | A Remote API token, minted by a company admin or owner under Company > Company Settings > Integrations & APIs > Integrations > the Remote API card > Generate API token. Scopes are chosen at mint time (Read only, Full access, or Custom endpoints), so a token that is too narrow fails specific actions rather than the connection itself. |
| Environment   | Optional / as applicable | Which Remote environment this token belongs to: 'production' for a token starting 'ra\_live\_', or 'sandbox' for one starting 'ra\_test\_'. Sandbox and production are separate, and a token only works against its own.                                                                                                                       |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **Remote** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### List Employments

List the people your company employs through Remote, filtered by status, employment model, or type.

#### Inputs

| Field                 | Type                      | Required | Description                                                                                                                                                                                                                                                                                                                  |
| --------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status                | multiple\_select (string) | No       | Only show people in these statuses. Leave empty for everyone. Available values: Active, Created, Pre-hire, Created, awaiting reserve, Created, reserve paid, Initiated, Invited, Pending, In review, Job title review, Pending post self-enrollment actions, Offboarding, Archived, Deleted, Incomplete (not onboarded yet). |
| Employment model      | select (string)           | No       | Only show people hired under this Remote model. Available values: EOR (Remote is the employer of record), PEO, Global payroll (your own legal entity).                                                                                                                                                                       |
| Employment type       | select (string)           | No       | Only show people of this type, for example only contractors. Available values: Employee, Contractor, Direct employee, Global payroll employee.                                                                                                                                                                               |
| Login email           | string                    | No       | Find one person by the email they log in to Remote with.                                                                                                                                                                                                                                                                     |
| Maximum results       | integer                   | No       | How many people to return at most. Minimum: 1. Maximum: 500. Default: 25.                                                                                                                                                                                                                                                    |
| Show advanced options | boolean                   | No       | Show ID lookups, company scoping and the page to resume from. Default: false.                                                                                                                                                                                                                                                |
| Short ID              | string                    | No       | Find one person by the short ID shown in the Remote dashboard.                                                                                                                                                                                                                                                               |
| Partner external ID   | string                    | No       | Find people by the ID your own system stored on them in Remote.                                                                                                                                                                                                                                                              |
| Company ID            | string                    | No       | Only needed if your token can see more than one Remote company.                                                                                                                                                                                                                                                              |
| Start from page       | integer                   | No       | Continue a previous run by passing the page number it returned. Keep Maximum results the same as in that run, or records are skipped or repeated. Minimum: 1.                                                                                                                                                                |

#### Outputs

| Field          | Type          | Description                                                                                                                                                                                                    |
| -------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employments    | object\_array | One row per person: id, short\_id, full\_name, status, type, employment\_model, employment\_lifecycle\_stage, job\_title, department, country, login\_email, work\_email, external\_id, partner\_external\_id. |
| Returned count | integer       | How many people this call returned.                                                                                                                                                                            |
| Total count    | integer       | How many people match the filters in total across all pages.                                                                                                                                                   |
| Next page      | integer       | Pass this back as Start from page to fetch the next batch.                                                                                                                                                     |

### Get Employment

Get the full Remote record for one person, with sensitive personal and document sections off by default. Bank account details are never returned.

#### Inputs

| Field                                 | Type            | Required | Description                                                                                                                                            |
| ------------------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Person                                | select (string) | Yes      | The person whose record you want. Options load from the selected connection.                                                                           |
| Show advanced options                 | boolean         | No       | Show the switches for sensitive personal data and documents. Default: false.                                                                           |
| Include personal and contract details | boolean         | No       | Also return home address, personal details, tax details, emergency contact, and contract terms. These contain sensitive personal data. Default: false. |
| Include attached documents            | boolean         | No       | Also list the documents attached to this person, such as contracts and identity checks. Default: false.                                                |

#### Outputs

| Field      | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employment | object | The person's record: id, short\_id, full\_name, status, user\_status, type, employment\_model, employment\_lifecycle\_stage, job\_title, department, department\_id, country, company\_id, login\_email, personal\_email, work\_email, manager, manager\_email, manager\_employment\_id, provisional\_start\_date, seniority\_date, probation\_period\_end\_date, expiration\_date, termination\_date, external\_id, partner\_external\_id, engaged\_by\_legal\_entity\_id, bill\_to\_legal\_entity\_id, active\_contract\_id, created\_at, updated\_at. The sensitive sections appear only when their switch is turned on. |

### Create Employment

Add a new hire to Remote for a given country. Remote's required fields differ by country, so the action fetches that country's form first and tells you exactly what is missing.

#### Inputs

| Field                          | Type            | Required | Description                                                                                                                                                                                                                                 |
| ------------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Country                        | select (string) | Yes      | Where the person will be employed. Remote's required fields depend on this. Options load from the selected connection.                                                                                                                      |
| Employment type                | select (string) | No       | What kind of engagement this is. Defaults to employee. Available values: Employee (Remote is the employer of record), Contractor, Global payroll employee (your own legal entity), HRIS (direct employee, records only). Default: employee. |
| Full name                      | string          | Yes      | The person's full legal name.                                                                                                                                                                                                               |
| Email                          | string          | Yes      | The email Remote will use to invite this person.                                                                                                                                                                                            |
| Job title                      | string          | Yes      | The role this person is hired into.                                                                                                                                                                                                         |
| Start date                     | date            | Yes      | The intended first day, at least 2 working days from today. Some countries need more notice in production.                                                                                                                                  |
| Country-specific fields (JSON) | textarea        | No       | Extra fields this country requires, as a JSON object. The action tells you exactly which keys are missing if you leave one out.                                                                                                             |
| Show advanced options          | boolean         | No       | Show the engaging legal entity, your own record ID, and the duplicate check. Default: false.                                                                                                                                                |
| Engaging legal entity ID       | string          | No       | Required for Global Payroll only. Copy it from your legal entity in the Remote dashboard.                                                                                                                                                   |
| Your system's ID               | string          | No       | An ID from your own HR system, stored on the Remote record.                                                                                                                                                                                 |
| Skip the duplicate check       | boolean         | No       | Create the record even if someone with this email already exists in Remote. Leave off unless you are deliberately rehiring. Default: false.                                                                                                 |

#### Outputs

| Field      | Type    | Description                                                                                                                                                                                                                                               |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employment | object  | The created (or pre-existing) record: id, type, country\_code, company\_id, full\_name, job\_title, login\_email, personal\_email, provisional\_start\_date, employment\_lifecycle\_stage, external\_id, partner\_external\_id, created\_at, updated\_at. |
| Created    | boolean | True if a new record was created, false if an existing person with this email was returned instead.                                                                                                                                                       |
| Next step  | string  | What Remote needs next, for example inviting the person to complete onboarding.                                                                                                                                                                           |

### List Time Off

List time off across the company, or for one person, filtered by type, status, or date range.

#### Inputs

| Field                                | Type            | Required | Description                                                                                                                                                                                                                                                                                       |
| ------------------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Person                               | select (string) | No       | Only show time off for one person. Leave empty for the whole company. Options load from the selected connection.                                                                                                                                                                                  |
| Status                               | select (string) | No       | Only show requests in this state, for example only those awaiting approval. Available values: Requested, Approved, Cancelled, Declined, Taken, Cancellation requested.                                                                                                                            |
| Leave type                           | select (string) | No       | Only show one kind of leave. Available values: Time off, Paid time off, Unpaid leave, Public holiday, Sick leave, Extended leave, Time in lieu, Maternity leave, Paternity leave, Parental leave, Bereavement, Military leave, Custom company leave, Casual leave, RTT, ROL, Ex festivita, Other. |
| From date                            | date            | No       | Start of the window you care about.                                                                                                                                                                                                                                                               |
| To date                              | date            | No       | End of the window you care about.                                                                                                                                                                                                                                                                 |
| Maximum results                      | integer         | No       | How many records to return at most. Minimum: 1. Maximum: 500. Default: 25.                                                                                                                                                                                                                        |
| Show advanced options                | boolean         | No       | Show sensitive-detail, sorting and paging controls. Default: false.                                                                                                                                                                                                                               |
| Include notes and attached documents | boolean         | No       | Also return the free-text notes, cancellation reasons, and any attached document. These often contain medical or bereavement detail. Default: false.                                                                                                                                              |
| Sort by                              | select (string) | No       | Order the results by leave type or status. Available values: Leave type, Status.                                                                                                                                                                                                                  |
| Direction                            | select (string) | No       | Ascending or descending. Available values: Ascending, Descending.                                                                                                                                                                                                                                 |
| Start from page                      | integer         | No       | Continue a previous run by passing the page number it returned. Keep Maximum results the same as in that run, or records are skipped or repeated. Minimum: 1.                                                                                                                                     |

#### Outputs

| Field            | Type          | Description                                                                                                                                                                                                                            |
| ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time off records | object\_array | One row per record: id, employment\_id, status, timeoff\_type, start\_date, end\_date, total\_minutes, timezone, automatic, approver\_id, approved\_at, cancelled\_at, leave\_policy\_name, leave\_policy\_variant\_id, timeoff\_days. |
| Returned count   | integer       | How many records this call returned.                                                                                                                                                                                                   |
| Total count      | integer       | How many records match the filters in total across all pages.                                                                                                                                                                          |
| Next page        | integer       | Pass this back as Start from page to fetch the next batch.                                                                                                                                                                             |

### List Invoices

List the billing documents Remote issues to your company (invoices, prefunding invoices and credit notes), with their totals.

#### Inputs

| Field                 | Type    | Required | Description                                                                                                                                                                                                                                                                    |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Month                 | string  | No       | Only show documents for one month, as YYYY-MM. Leave empty for the most recent.                                                                                                                                                                                                |
| Maximum results       | integer | No       | How many documents to return at most. Minimum: 1. Maximum: 100. Default: 20.                                                                                                                                                                                                   |
| Show advanced options | boolean | No       | Show the amount toggle and the page to resume from. Default: false.                                                                                                                                                                                                            |
| Include amounts       | boolean | No       | Fetch each document's total and currency. On by default, because Remote's list itself has no amounts. Remote gates that detail endpoint separately from the listing, so if your company has not requested access the amounts come back empty and the Totals note explains why. |
| Start from page       | integer | No       | Continue a previous run by passing the page number it returned. Keep Maximum results the same as in that run, or records are skipped or repeated. Minimum: 1.                                                                                                                  |

#### Outputs

| Field             | Type          | Description                                                                                                                                                                   |
| ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Billing documents | object\_array | One row per document: id, billing\_document\_period, billing\_document\_type, bill\_from, and (when amounts are included) document\_number, total, currency and issued\_date. |
| Totals note       | string        | Set only when amounts could not be read for some or all documents, with the reason. Empty otherwise.                                                                          |
| Returned count    | integer       | How many documents this call returned.                                                                                                                                        |
| Total count       | integer       | How many documents match in total across all pages.                                                                                                                           |
| Next page         | integer       | Pass this back as Start from page to fetch the next batch.                                                                                                                    |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/remote.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
