Remote Pay & Compensation API
The Pay & Compensation API from Remote — 30 operation(s) for pay & compensation.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Pay & Compensation API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Pay & Compensation
paths:
/v1/pay-items/bulk:
post:
callbacks: {}
deprecated: false
description: 'Bulk creates pay items for employments. Supports up to 500 items per request.
Integration-specific fields (shift code, currency, pay amount, etc.) go in the `provider_data` object.
Only Global Payroll employments are supported. Non-GP employments are returned as `employment_not_global_payroll`.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage payroll runs (`payroll`) | - | Manage pay items (`pay_item:write`) |
'
operationId: post_v1_pay-items_bulk
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkCreatePayItemsParams'
description: Pay Items
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkCreatePayItemsResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- pay_item:write
- payroll
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- pay_item:write
- payroll
- all:write
summary: Bulk Create Pay Items
tags:
- Pay & Compensation
/v1/currency-converter/raw:
post:
callbacks: {}
deprecated: false
description: "Convert currency using FX rates used in Remote’s estimation tools.\n These rates are not guaranteed to match final onboarding or contract rates.\n\n## Scopes\n\n| Category | Read only Scope | Write only Scope (read access implicit) |\n|---|---|---|\n| Manage company resources (`company_admin`) | Convert currencies (`convert_currency:read`) | - |\n"
operationId: post_v1_currency-converter_raw
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertCurrencyParams'
description: Convert currency parameters
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertCurrencyResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- ClientToken:
- https://gateway.remote.com/company.manage
- convert_currency:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- convert_currency:read
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- convert_currency:read
- company_admin
- all:write
- all:read
summary: Convert currency using flat rates
tags:
- Pay & Compensation
/v1/cost-calculator/estimation:
post:
callbacks: {}
deprecated: false
operationId: post_v1_cost-calculator_estimation
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CostCalculatorEstimateParams'
description: Estimate params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CostCalculatorEstimateResponse'
description: Success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- ClientToken: []
CustomerAPIToken: []
OAuth2AuthorizationCode: []
OAuth2ClientCredentials: []
summary: Creates a cost estimation of employments
tags:
- Pay & Compensation
/v1/payroll-calendars:
get:
callbacks: {}
deprecated: false
description: 'List all active payroll calendars for EOR.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage payroll runs (`payroll`) | View payroll calendars (`payroll_calendar:read`) | - |
'
operationId: get_v1_payroll-calendars
parameters:
- description: Filter payroll calendars by country code
example: BRA
in: query
name: country_code
required: false
schema:
type: string
- description: Filter payroll calendars by year
example: '2024'
in: query
name: year
required: false
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
default: 1
minimum: 1
type: integer
- description: Number of items per page
example: 20
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollCalendarsEORResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- payroll_calendar:read
- payroll
- all:write
- all:read
summary: List EOR Payroll Calendar
tags:
- Pay & Compensation
/v1/incentives/recurring:
get:
callbacks: {}
description: 'List all Recurring Incentives of a company.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | View incentives (`incentive:read`) | Manage incentives (`incentive:write`) |
'
operationId: get_v1_incentives_recurring
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: 'Filter by recurring incentive status: active or deactive.'
example: active
in: query
name: status
required: false
schema:
type: string
- description: Filter by recurring incentive type.
example: meal_allowance
in: query
name: type
required: false
schema:
type: string
- description: Filter by recurring incentives that contain the value in their notes.
example: meal
in: query
name: note
required: false
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
type: integer
- description: Change the amount of records returned per page, defaults to 20, limited to 100
example: 30
in: query
name: page_size
required: false
schema:
type: integer
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecurringIncentivesResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- incentive:read
- incentive:write
- employment_payments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- incentive:read
- incentive:write
- employment_payments
- all:write
- all:read
summary: List Recurring Incentive
tags:
- Pay & Compensation
post:
callbacks: {}
description: 'Create a Recurring Incentive, that is, a monthly paid incentive.
Incentives use the currency of the employment specified provided in the `employment_id` field.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |
'
operationId: post_v1_incentives_recurring
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRecurringIncentiveParams'
description: RecurringIncentive
required: false
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringIncentiveResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- incentive:write
- employment_payments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- incentive:write
- employment_payments
- all:write
summary: Create Recurring Incentive
tags:
- Pay & Compensation
/v1/expenses:
get:
callbacks: {}
description: 'Lists all expenses records
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | View expenses (`expense:read`) | Manage expenses (`expense:write`) |
'
operationId: get_v1_expenses
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
type: integer
- description: Change the amount of records returned per page, defaults to 20, limited to 100
example: 30
in: query
name: page_size
required: false
schema:
type: integer
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ListExpenseResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- expense:read
- expense:write
- employment_payments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- expense:read
- expense:write
- employment_payments
- all:write
- all:read
summary: List expenses
tags:
- Pay & Compensation
post:
callbacks: {}
description: 'Creates an **approved** expense
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | - | Manage expenses (`expense:write`) |
'
operationId: post_v1_expenses
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ParamsToCreateExpense'
description: Expenses
required: false
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- expense:write
- employment_payments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- expense:write
- employment_payments
- all:write
summary: Create expense
tags:
- Pay & Compensation
/v1/payroll-runs/{payroll_run_id}/gl-reports:
post:
callbacks: {}
deprecated: false
description: 'Triggers generation of a General Ledger report for the given payroll run and type.
Returns immediately with a `pending` report — poll `show` until `status` is `completed`,
then call `download`.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage payroll runs (`payroll`) | View payroll runs (`payroll_run:read`) | - |
'
operationId: post_v1_payroll-runs_payroll_run_id_gl-reports
parameters:
- description: The payroll run's ID
example: 93t3j-payroll-run-id-9suej43
in: path
name: payroll_run_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGLReportParams'
description: GL report type
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GLReportResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- payroll_run:read
- payroll
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- payroll_run:read
- payroll
- all:write
- all:read
summary: Create a GL report
tags:
- Pay & Compensation
/v1/incentives/recurring/{id}:
delete:
callbacks: {}
description: 'Delete a Recurring Incentive, that is, a monthly paid incentive.
Internally, Remote schedules upcoming incentives. As such, when you attempt to
delete a recurring incentive, Remote will **ONLY** delete scheduled incentives
with the `pending` status.
Incentives payments that are already scheduled and cannot be deleted will be
included in the response, in case you need to reference them.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |
'
operationId: delete_v1_incentives_recurring_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Recurring Incentive ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRecurringIncentiveResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- incentive:write
- employment_payments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- incentive:write
- employment_payments
- all:write
summary: Delete a Recurring Incentive
tags:
- Pay & Compensation
/v1/incentives:
get:
callbacks: {}
description: 'Lists all Incentives of a company
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | View incentives (`incentive:read`) | Manage incentives (`incentive:write`) |
'
operationId: get_v1_incentives
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Filter by Employment ID
example: 93t3j-employment-id-9suej43
in: query
name: employment_id
required: false
schema:
type: string
- description: Filter by Incentive status
example: paid
in: query
name: status
required: false
schema:
type: string
- description: Filter by Recurring Incentive id
example: 2f900aaf-4952-4ec4-ac7c-2b917a2b4da9
in: query
name: recurring_incentive_id
required: false
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
type: integer
- description: Change the amount of records returned per page, defaults to 20, limited to 100
example: 30
in: query
name: page_size
required: false
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListIncentivesResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- incentive:read
- incentive:write
- employment_payments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- incentive:read
- incentive:write
- employment_payments
- all:write
- all:read
summary: List Incentives
tags:
- Pay & Compensation
post:
callbacks: {}
description: 'Creates an Incentive.
Incentives use the currency of the employment specified provided in the `employment_id` field.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |
'
operationId: post_v1_incentives
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOneTimeIncentiveParams'
description: Incentive
required: false
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/IncentiveResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- incentive:write
- employment_payments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- incentive:write
- employment_payments
- all:write
summary: Create Incentive
tags:
- Pay & Compensation
/v1/payroll-runs/{payroll_run_id}/gl-reports/{gl_report_id}:
get:
callbacks: {}
deprecated: false
description: 'Returns the current status of a GL report. Poll until `status` is `completed`, then call `download`.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage payroll runs (`payroll`) | View payroll runs (`payroll_run:read`) | - |
'
operationId: get_v1_payroll-runs_payroll_run_id_gl-reports_gl_report_id
parameters:
- description: The payroll run's ID
example: 93t3j-payroll-run-id-9suej43
in: path
name: payroll_run_id
required: true
schema:
type: string
- description: The GL report's ID
example: 93t3j-gl-report-id-9suej43
in: path
name: gl_report_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GLReportResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
# --- truncated at 32 KB (238 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-pay-compensation-api-openapi.yml