Remote Payroll Runs API
The Payroll Runs API from Remote — 3 operation(s) for payroll runs.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Payroll Runs API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Payroll Runs
paths:
/v1/payroll-runs/{payroll_run_id}:
get:
callbacks: {}
deprecated: false
description: 'Given an ID, shows a payroll run.
`employee_details` field is deprecated in favour of the `employee_details` endpoint and will be removed in the future.
## 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
parameters:
- description: Payroll run ID
example: 93t3j-payroll_run_id-9suej43
in: path
name: payroll_run_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollRunResponse'
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: Show Company Payroll Runs
tags:
- Payroll Runs
/v1/payroll-runs/{payroll_run_id}/employee-details:
get:
callbacks: {}
deprecated: false
description: 'Gets the employee details for a payroll run
## 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_employee-details
parameters:
- description: Payroll run ID
example: 93t3j-payroll_run_id-9suej43
in: path
name: payroll_run_id
required: true
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/EmployeeDetailsResponse'
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: Get Employee Details for a Payroll Run
tags:
- Payroll Runs
/v1/payroll-runs:
get:
callbacks: {}
deprecated: false
description: 'Lists all payroll runs for a company
## 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
parameters:
- description: Filters payroll runs where period_start or period_end match the given date
example: '2021-07-01'
in: query
name: payroll_period
required: false
schema:
$ref: '#/components/schemas/Date'
- 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/ListPayrollRunResponse'
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: List Company Payroll Runs
tags:
- Payroll Runs
components:
schemas:
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
required:
- code
- message
- action
title: ActionError
type: object
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
NullableDate:
description: Optional UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
example: '2021-07-01'
format: date
nullable: true
title: NullableDate
type: string
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
Country:
description: A supported country on Remote
example:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
properties:
alpha_2_code:
description: The ISO 3166-1 alpha-2 country code (e.g., "PT").
type: string
code:
description: The ISO 3166-1 alpha-3 country code (e.g., "PRT"). This is the primary code used across the Remote API.
type: string
contractor_products_available:
description: Contractor product names available for this country
items:
enum:
- standard
- plus
- cor
type: string
type: array
country_subdivisions:
description: Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.
items:
$ref: '#/components/schemas/CountrySubdivision'
nullable: true
type: array
employment_agreement_preview_available:
description: Whether an Employment Agreement preview is available for this country.
type: boolean
eor_onboarding:
description: Whether EOR (Employer of Record) onboarding is available in this country.
type: boolean
locked_benefits:
description: When benefit plan selections become locked for this country (e.g., "after_first_hire" means benefits cannot be changed after the first employee is hired).
type: string
name:
description: The country's full English name.
type: string
region:
description: The geographic region the country belongs to (e.g., "Europe", "Asia", "Americas").
type: string
subregion:
description: The geographic subregion (e.g., "Southern Europe", "Southeast Asia"). Null for some countries.
nullable: true
type: string
supported_json_schemas:
description: The list of JSON schema form names available for this country (e.g., "address_details", "contract_details"). Use these with the Show form schema endpoint to get country-specific field requirements.
items:
type: string
type: array
required:
- alpha_2_code
- code
- name
title: Country
type: object
CurrencyCode:
description: Currency code of the SWIFT fee. Only present when processing_fee is set.
example: BRL
maxLength: 3
minLength: 3
nullable: true
title: CurrencyCode
type: string
Date:
description: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
example: '2021-07-01'
format: date
title: Date
type: string
ListPayrollRunResponse:
description: Response containing a list of payroll runs for the company. Each payroll run includes summary information but not per-employee breakdowns.
example:
payroll_runs:
- approval_date: '2021-01-15'
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
currency_code: USD
cutoff_date: '2021-01-20'
expected_payout_date: '2021-01-25'
id: 123e4567-e89b-12d3-a456-426614174000
period_end: '2021-01-31'
period_start: '2021-01-01'
status: preparing
total_payroll_cost: 1000
type: main
properties:
payroll_runs:
description: List of payroll runs matching the query filters.
items:
$ref: '#/components/schemas/MinimalPayrollRun'
type: array
title: ListPayrollRunResponse
type: object
EmployeeDetails:
description: Payroll cost breakdown for a single employee within a payroll run. All monetary amounts are represented as an object with `amount` (integer, in cents) and `currency` (ISO 4217 code).
example:
base_salary:
amount: 1000
currency: USD
benefits:
amount: 100
currency: USD
deductions:
amount: 200
currency: USD
employer_costs:
amount: 100
currency: USD
expenses:
amount: 100
currency: USD
full_name: John Doe
gross_pay:
amount: 1000
currency: USD
incentives:
amount: 100
currency: USD
net_pay:
amount: 800
currency: USD
other:
amount: 100
currency: USD
payslip_id: 123e4567-e89b-12d3-a456-426614174000
total_cost:
amount: 1000
currency: USD
properties:
base_salary:
description: The employee's base salary component for this payroll period. When the payroll run is in `preparing` or `processing` status, this is an estimate that may change after final payroll calculations. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
benefits:
description: Total cost of employee benefits (health insurance, pension, etc.) for this payroll run. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
deductions:
description: Total deductions from the employee's gross pay, including taxes and social contributions. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
employer_costs:
description: Total employer-side contributions and costs (employer social contributions, taxes, etc.) beyond the employee's gross pay. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
employment_id:
description: The unique identifier of the employment record for this employee.
format: uuid
type: string
expenses:
description: Total approved expenses reimbursed to the employee in this payroll run. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
full_name:
description: The full name of the employee. May be null if the employee's profile is incomplete.
nullable: true
type: string
gross_pay:
description: The employee's gross pay before any deductions. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
incentives:
description: Total incentives (bonuses, commissions, etc.) paid to the employee in this payroll run. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
net_pay:
description: The net amount paid to the employee after all deductions (taxes, social contributions, etc.). Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
other:
description: Any other payroll components not categorized as salary, benefits, expenses, or incentives. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
payslip_id:
description: The unique identifier of the employee's payslip for this payroll run. Null when the payroll run is still in `preparing` or `processing` status and payslips have not yet been generated.
format: uuid
nullable: true
type: string
total_cost:
description: The total cost to the employer for this employee in this payroll run, including salary, benefits, employer contributions, expenses, and incentives. Amount in cents.
properties:
amount:
description: Amount in cents.
type: integer
currency:
description: ISO 4217 currency code.
type: string
type: object
required:
- full_name
- payslip_id
- total_cost
- net_pay
- gross_pay
- deductions
- base_salary
- expenses
- incentives
- other
- benefits
- employer_costs
title: EmployeeDetails
type: object
PayrollRun:
additionalProperties: false
description: A payroll run represents a single payroll processing cycle for a company in a specific country and period. It progresses through statuses from preparation to finalization, and contains cost totals aggregated across all employees included in the run.
example:
approval_date: '2021-01-15'
benefits_total: 1000
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
currency_code: USD
employee_details:
- base_salary:
amount: 1000
currency: USD
benefits:
amount: 100
currency: USD
deductions:
amount: 200
currency: USD
employer_costs:
amount: 100
currency: USD
expenses:
amount: 100
currency: USD
full_name: John Doe
gross_pay:
amount: 1000
currency: USD
incentives:
amount: 100
currency: USD
net_pay:
amount: 800
currency: USD
other:
amount: 100
currency: USD
payslip_id: 123e4567-e89b-12d3-a456-426614174000
total_cost:
amount: 1000
currency: USD
employer_contributions_total: 1000
expected_payout_date: '2021-01-25'
expenses_total: 1000
id: 123e4567-e89b-12d3-a456-426614174000
incentives_total: 1000
other_total: 1000
period_end: '2021-01-31'
period_start: '2021-01-01'
salary_total: 1000
status: preparing
total_payroll_cost: 1000
properties:
approval_date:
$ref: '#/components/schemas/NullableDate'
benefits_total:
description: The total benefits cost across all employees in this payroll run. Amount in cents.
type: integer
country:
$ref: '#/components/schemas/Country'
currency_code:
$ref: '#/components/schemas/CurrencyCode'
cutoff_date:
$ref: '#/components/schemas/NullableDate'
employee_details:
deprecated: true
description: Per-employee cost breakdown for this payroll run. Deprecated — use the dedicated `GET /v1/payroll-runs/{payroll_run_id}/employee-details` endpoint instead, which supports pagination.
items:
$ref: '#/components/schemas/EmployeeDetails'
type: array
employer_contributions_total:
description: The total employer-side contributions (social contributions, employer taxes, etc.) across all employees. Amount in cents.
type: integer
expected_payout_date:
$ref: '#/components/schemas/Date'
expenses_total:
description: The total reimbursed expenses across all employees in this payroll run. Amount in cents.
type: integer
id:
description: The unique identifier of the payroll run.
format: uuid
type: string
incentives_total:
description: The total incentives (bonuses, commissions, etc.) across all employees in this payroll run. Amount in cents.
type: integer
other_total:
description: The total of other payroll components not categorized elsewhere. Amount in cents.
type: integer
period_end:
$ref: '#/components/schemas/Date'
period_start:
$ref: '#/components/schemas/Date'
salary_total:
description: The total base salary amount across all employees in this payroll run. Amount in cents.
type: integer
status:
description: 'The current status of the payroll run.
- `preparing`: The payroll run is being assembled. Employee details and costs are estimates and may change.
- `processing`: The payroll run has been submitted for processing by the local payroll provider. Costs are still estimates.
- `completed`: Payroll processing is complete. Costs are final and payslips are available.
- `finalized`: The payroll run has been finalized and payments have been or will be disbursed.
- `waiting_for_customer_approval`: The payroll run requires approval from the company before it can proceed.
- `rejected`: The payroll run was rejected during the approval process and needs to be revised.
'
enum:
- preparing
- processing
- completed
- finalized
- waiting_for_customer_approval
- rejected
type: string
total_payroll_cost:
description: The total cost of this payroll run across all employees, including salaries, benefits, employer contributions, expenses, and incentives. Amount in cents.
type: integer
type:
description: 'The type of payroll run.
- `main`: The regular recurring payroll for the period.
- `one_off`: An ad-hoc payroll run outside the regular cycle, typically for off-cycle payments.
- `pro_forma`: A simulated payroll run used for cost estimation purposes. Not actually processed.
- `tax_documents`: A payroll run for generating tax-related documents only.
- `expenses`: A payroll run dedicated to reimbursing approved expenses.
- `parallel`: A supplementary payroll run that runs alongside the main payroll for the same period.
'
enum:
- main
- one_off
- pro_forma
- tax_documents
- expenses
- parallel
type: string
required:
- id
- status
- period_start
- period_end
- approval_date
- expected_payout_date
- currency_code
- country
- total_payroll_cost
- salary_total
- benefits_total
- incentives_total
- expenses_total
- other_total
- employer_contributions_total
- employee_details
title: PayrollRun
type: object
CountrySubdivision:
description: A subdivision of a supported country on Remote
example:
code: PT-11
name: Lisboa
subdivision_type: District
properties:
code:
description: The ISO 3166-2 subdivision code (e.g., "PT-11" for Lisboa).
type: string
name:
description: The subdivision's name (e.g., "Lisboa", "California").
type: string
subdivision_type:
description: The type of subdivision (e.g., "District", "State", "Province").
type: string
required:
- name
title: CountrySubdivision
type: object
EmployeeDetailsResponse:
description: Paginated response containing per-employee payroll cost breakdowns for a specific payroll run.
example:
data:
employee_details:
- base_salary:
amount: 1000
currency: USD
benefits:
amount: 100
currency: USD
deductions:
amount: 200
currency: USD
employer_costs:
amount: 100
currency: USD
expenses:
amount: 100
currency: USD
full_name: John Doe
gross_pay:
amount: 1000
currency: USD
incentives:
amount: 100
currency: USD
net_pay:
amount: 800
currency: USD
other:
amount: 100
currency: USD
payslip_id: 123e4567-e89b-12d3-a456-426614174000
total_cost:
amount: 1000
currency: USD
properties:
data:
properties:
employee_details:
description: List of per-employee cost breakdowns for the payroll run.
items:
$ref: '#/components/schemas/EmployeeDetails'
type: array
required:
- employee_details
type: object
required:
- data
title: EmployeeDetailsResponse
type: object
MinimalPayrollRun:
description: A lightweight representation of a payroll run used in list responses. Contains summary information and the total cost, but not the per-employee breakdown or cost category totals.
example:
approval_date: '2021-01-15'
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
currency_code: USD
cutoff_date: '2021-01-20'
expected_payout_date: '2021-01-25'
id: 123e4567-e89b-12d3-a456-426614174000
period_end: '2021-01-31'
period_start: '2021-01-01'
status: preparing
total_payroll_cost: 1000
type: main
properties:
approval_date:
$ref: '#/components/schemas/NullableDate'
country:
$ref: '#/components/schemas/Country'
currency_code:
$ref: '#/components/schemas/CurrencyCode'
cutoff_date:
$ref: '#/components/schemas/NullableDate'
expected_payout_date:
$ref: '#/components/schemas/Date'
id:
description: The unique identifier of the payroll run.
format: uuid
type: string
period_end:
$ref: '#/components/schemas/Date'
period_start:
$ref: '#/components/schemas/Date'
status:
description: 'The current status of the payroll run.
- `preparing`: The payroll run is being assembled. Costs are estimates.
- `processing`: Submitted for processing. Costs are still estimates.
- `completed`: Processing is complete. Costs are final.
- `finalized`: Payments have been or will be disbursed.
- `waiting_for_customer_approval`
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-payroll-runs-api-openapi.yml