openapi: 3.1.0
info:
title: Remote Payroll and Billing API
description: |
Inspect payroll calendars, billing documents, incentives, expenses,
payslips, and timesheets across Remote's EOR, Global Payroll, PEO,
and Contractor offerings. All financial events are exposed both
via REST and via webhooks.
version: '2026-05-22'
contact:
name: Remote API Support
url: https://support.remote.com/
x-logo:
url: https://remote.com/favicon.ico
servers:
- url: https://gateway.remote.com/v1
description: Production
- url: https://gateway.remote-sandbox.com/v1
description: Sandbox
security:
- BearerAuth: []
tags:
- name: Payroll Calendars
description: Inspect payroll calendars for company, EOR, and Global Payroll
- name: Billing Documents
description: Customer-facing invoices and statements
- name: Incentives
description: One-time bonuses and recurring incentives
- name: Expenses
description: Employee expense reimbursements
- name: Payslips
description: Released payslips for employees
- name: Company Currencies
description: List currencies a company can be billed in
paths:
/payroll/calendars:
get:
summary: List Payroll Calendar
operationId: listPayrollCalendar
tags: [Payroll Calendars]
parameters:
- { name: starts_after, in: query, schema: { type: string, format: date } }
- { name: ends_before, in: query, schema: { type: string, format: date } }
responses:
'200':
description: Calendar entries.
content:
application/json:
schema: { $ref: '#/components/schemas/PayrollCalendarList' }
/payroll/calendars/company:
get:
summary: List Company Payroll Calendar
operationId: listCompanyPayrollCalendar
tags: [Payroll Calendars]
responses:
'200':
description: Calendar entries.
content:
application/json:
schema: { $ref: '#/components/schemas/PayrollCalendarList' }
/payroll/calendars/eor:
get:
summary: List EOR Payroll Calendar
operationId: listEorPayrollCalendar
tags: [Payroll Calendars]
responses:
'200':
description: Calendar entries.
content:
application/json:
schema: { $ref: '#/components/schemas/PayrollCalendarList' }
/billing_documents:
get:
summary: List Billing Documents
operationId: listBillingDocuments
tags: [Billing Documents]
parameters:
- { name: status, in: query, schema: { type: string, enum: [issued, paid, overdue, void] } }
- { name: period, in: query, schema: { type: string, description: "YYYY-MM" } }
responses:
'200':
description: Billing documents.
content:
application/json:
schema: { $ref: '#/components/schemas/BillingDocumentList' }
/billing_documents/{billing_document_id}:
parameters:
- { name: billing_document_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show A Billing Document
operationId: showBillingDocument
tags: [Billing Documents]
responses:
'200':
description: Billing document.
content:
application/json:
schema: { $ref: '#/components/schemas/BillingDocumentEnvelope' }
/billing_documents/{billing_document_id}/breakdown:
parameters:
- { name: billing_document_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Get Billing Document Breakdown
operationId: getBillingDocumentBreakdown
tags: [Billing Documents]
responses:
'200':
description: Line-item breakdown.
content:
application/json:
schema:
type: object
additionalProperties: true
/billing_documents/{billing_document_id}/pdf:
parameters:
- { name: billing_document_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Download Billing Document PDF
operationId: downloadBillingDocumentPdf
tags: [Billing Documents]
responses:
'200':
description: PDF binary.
content:
application/pdf:
schema: { type: string, format: binary }
/incentives:
get:
summary: List Incentives
operationId: listIncentives
tags: [Incentives]
parameters:
- { name: employment_id, in: query, schema: { type: string, format: uuid } }
- { name: type, in: query, schema: { type: string, enum: [bonus, commission, signing_bonus, recurring_incentive] } }
responses:
'200':
description: Incentives.
content:
application/json:
schema: { $ref: '#/components/schemas/IncentiveList' }
post:
summary: Create An Incentive
operationId: createIncentive
tags: [Incentives]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/IncentiveCreateRequest' }
responses:
'201':
description: Created.
content:
application/json:
schema: { $ref: '#/components/schemas/IncentiveEnvelope' }
/incentives/{incentive_id}:
parameters:
- { name: incentive_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show An Incentive
operationId: showIncentive
tags: [Incentives]
responses:
'200':
description: Incentive.
content:
application/json:
schema: { $ref: '#/components/schemas/IncentiveEnvelope' }
patch:
summary: Update An Incentive
operationId: updateIncentive
tags: [Incentives]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/IncentiveCreateRequest' }
responses:
'200':
description: Updated.
content:
application/json:
schema: { $ref: '#/components/schemas/IncentiveEnvelope' }
delete:
summary: Delete An Incentive
operationId: deleteIncentive
tags: [Incentives]
responses:
'204': { description: Deleted. }
/expenses:
get:
summary: List Expenses
operationId: listExpenses
tags: [Expenses]
parameters:
- { name: employment_id, in: query, schema: { type: string, format: uuid } }
- { name: status, in: query, schema: { $ref: '#/components/schemas/ExpenseStatus' } }
responses:
'200':
description: Expenses.
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseList' }
post:
summary: Create An Expense
operationId: createExpense
tags: [Expenses]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseCreateRequest' }
responses:
'201':
description: Created.
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseEnvelope' }
/expenses/{expense_id}:
parameters:
- { name: expense_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show An Expense
operationId: showExpense
tags: [Expenses]
responses:
'200':
description: Expense.
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseEnvelope' }
patch:
summary: Update An Expense
operationId: updateExpense
tags: [Expenses]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseCreateRequest' }
responses:
'200':
description: Updated.
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseEnvelope' }
delete:
summary: Delete An Expense
operationId: deleteExpense
tags: [Expenses]
responses:
'204': { description: Deleted. }
/expenses/{expense_id}/approve:
parameters:
- { name: expense_id, in: path, required: true, schema: { type: string, format: uuid } }
post:
summary: Approve An Expense
operationId: approveExpense
tags: [Expenses]
responses:
'200':
description: Approved.
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseEnvelope' }
/expenses/{expense_id}/decline:
parameters:
- { name: expense_id, in: path, required: true, schema: { type: string, format: uuid } }
post:
summary: Decline An Expense
operationId: declineExpense
tags: [Expenses]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [reason]
properties:
reason: { type: string }
responses:
'200':
description: Declined.
content:
application/json:
schema: { $ref: '#/components/schemas/ExpenseEnvelope' }
/payslips:
get:
summary: List Payslips
operationId: listPayslips
tags: [Payslips]
parameters:
- { name: employment_id, in: query, schema: { type: string, format: uuid } }
- { name: period, in: query, schema: { type: string } }
responses:
'200':
description: Payslips.
content:
application/json:
schema: { $ref: '#/components/schemas/PayslipList' }
/payslips/{payslip_id}:
parameters:
- { name: payslip_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show A Payslip
operationId: showPayslip
tags: [Payslips]
responses:
'200':
description: Payslip.
content:
application/json:
schema: { $ref: '#/components/schemas/PayslipEnvelope' }
/company_currencies:
get:
summary: List Company Currencies
operationId: listCompanyCurrencies
tags: [Company Currencies]
responses:
'200':
description: Currencies.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
currencies:
type: array
items:
type: object
properties:
code: { type: string }
name: { type: string }
symbol: { type: string }
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
PayrollCalendarEntry:
type: object
properties:
id: { type: string, format: uuid }
scope:
type: string
enum: [company, eor, global_payroll]
country_code: { type: string }
period_start: { type: string, format: date }
period_end: { type: string, format: date }
cutoff_date: { type: string, format: date }
payday: { type: string, format: date }
currency: { type: string }
PayrollCalendarList:
type: object
properties:
data:
type: object
properties:
payroll_calendars:
type: array
items: { $ref: '#/components/schemas/PayrollCalendarEntry' }
BillingDocument:
type: object
properties:
id: { type: string, format: uuid }
number: { type: string }
status:
type: string
enum: [issued, paid, overdue, void]
amount: { type: integer, description: Amount in smallest currency unit. }
currency: { type: string }
issued_at: { type: string, format: date-time }
due_at: { type: string, format: date-time }
period_start: { type: string, format: date }
period_end: { type: string, format: date }
type:
type: string
enum: [eor_invoice, payroll_fee_invoice, contractor_invoice, reserve_invoice]
BillingDocumentList:
type: object
properties:
data:
type: object
properties:
billing_documents:
type: array
items: { $ref: '#/components/schemas/BillingDocument' }
BillingDocumentEnvelope:
type: object
properties:
data:
type: object
properties:
billing_document: { $ref: '#/components/schemas/BillingDocument' }
Incentive:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
type:
type: string
enum: [bonus, commission, signing_bonus, recurring_incentive]
amount: { type: integer }
currency: { type: string }
recurrence:
type: string
enum: [one_time, monthly, quarterly, yearly]
effective_date: { type: string, format: date }
status:
type: string
enum: [created, processing_started, paid, canceled]
note: { type: string }
IncentiveList:
type: object
properties:
data:
type: object
properties:
incentives:
type: array
items: { $ref: '#/components/schemas/Incentive' }
IncentiveEnvelope:
type: object
properties:
data:
type: object
properties:
incentive: { $ref: '#/components/schemas/Incentive' }
IncentiveCreateRequest:
type: object
required: [employment_id, type, amount, currency, effective_date]
properties:
employment_id: { type: string, format: uuid }
type:
type: string
enum: [bonus, commission, signing_bonus, recurring_incentive]
amount: { type: integer }
currency: { type: string }
effective_date: { type: string, format: date }
recurrence:
type: string
enum: [one_time, monthly, quarterly, yearly]
note: { type: string }
ExpenseStatus:
type: string
enum: [submitted, approved, declined, reimbursed, deleted]
Expense:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
category: { type: string }
amount: { type: integer }
currency: { type: string }
status: { $ref: '#/components/schemas/ExpenseStatus' }
expense_date: { type: string, format: date }
description: { type: string }
receipt_url: { type: string, format: uri, nullable: true }
ExpenseList:
type: object
properties:
data:
type: object
properties:
expenses:
type: array
items: { $ref: '#/components/schemas/Expense' }
ExpenseEnvelope:
type: object
properties:
data:
type: object
properties:
expense: { $ref: '#/components/schemas/Expense' }
ExpenseCreateRequest:
type: object
required: [employment_id, category, amount, currency, expense_date]
properties:
employment_id: { type: string, format: uuid }
category: { type: string }
amount: { type: integer }
currency: { type: string }
expense_date: { type: string, format: date }
description: { type: string }
receipt_url: { type: string, format: uri }
Payslip:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
period_start: { type: string, format: date }
period_end: { type: string, format: date }
gross_amount: { type: integer }
net_amount: { type: integer }
currency: { type: string }
released_at: { type: string, format: date-time }
document_url: { type: string, format: uri }
PayslipList:
type: object
properties:
data:
type: object
properties:
payslips:
type: array
items: { $ref: '#/components/schemas/Payslip' }
PayslipEnvelope:
type: object
properties:
data:
type: object
properties:
payslip: { $ref: '#/components/schemas/Payslip' }