Remote Payslips API
The Payslips API from Remote — 4 operation(s) for payslips.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Payslips API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Payslips
paths:
/v1/employee/payslips:
get:
callbacks: {}
deprecated: false
description: 'Returns a paginated list of payslip files belonging to the current employee.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View payslips (`payslip:read`) | - |
'
operationId: get_v1_employee_payslips
parameters:
- 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/ListEmployeePayslipsResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- OAuth2Assertion:
- https://gateway.remote.com/employment.manage
- payslip:read
- employment_documents
- all:write
- all:read
summary: List approved payslip files for the authenticated employee
tags:
- Payslips
/v1/employee/payslip-files:
get:
callbacks: {}
deprecated: false
description: 'Returns a paginated list of payslip files belonging to the current employee.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View payslips (`payslip:read`) | - |
'
operationId: get_v1_employee_payslip-files
parameters:
- 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/ListPayslipFilesResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- OAuth2Assertion:
- https://gateway.remote.com/employment.manage
- payslip:read
- employment_documents
- all:write
- all:read
summary: List payslip files for the authenticated employee
tags:
- Payslips
/v1/payslips/{payslip_id}/pdf:
get:
callbacks: {}
description: 'Given a Payslip ID, downloads a payslip.
It is important to note that each country has a different payslip format and they are not authored by Remote.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View payslips (`payslip:read`) | - |
'
operationId: get_v1_payslips_payslip_id_pdf
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: Payslip ID
example: 93t3j-payslip-id-9suej43
in: path
name: payslip_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PayslipDownloadResponse'
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
- payslip:read
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- payslip:read
- employment_documents
- all:write
- all:read
summary: Download payslip in the PDF format
tags:
- Payslips
/v1/payslips:
get:
callbacks: {}
description: 'Lists all payslips belonging to a company. Can also filter for a single employment belonging
to that company.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View payslips (`payslip:read`) | - |
'
operationId: get_v1_payslips
parameters:
- description: Employment ID
example: 93t3j-employment-id-9suej43
in: query
name: employment_id
required: false
schema:
type: string
- description: Filters by payslips `issued_at` field, after or on the same day than the given date
example: '"2022-12-15"'
in: query
name: start_date
required: false
schema:
type: string
- description: Filters by payslips `issued_at` field, before or or the same day than the given date
example: '"2023-12-15"'
in: query
name: end_date
required: false
schema:
type: string
- description: Filters by payslips `expected_payout_date` field, after or on the same day than the given date
example: '"2022-12-15"'
in: query
name: expected_payout_start_date
required: false
schema:
type: string
- description: Filters by payslips `expected_payout_date` field, before or or the same day than the given date
example: '"2023-12-15"'
in: query
name: expected_payout_end_date
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/ListPayslipsResponse'
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
- payslip:read
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- payslip:read
- employment_documents
- all:write
- all:read
summary: List payslips
tags:
- Payslips
components:
schemas:
PayslipDownloadResponse:
description: The binary content of the payslip file.
example: UGVyaW9kIEVuZCBEYXRlLFBheSBEYXRlLEVtcG...5jZSBPZiBSZXNpZGVuYdXJyZW50LEFsbG93
format: binary
title: PayslipDownloadResponse
type: string
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
Decimal:
description: A decimal number represented as a string to preserve precision. Supports negative values and fractional digits.
example: '-123.456'
pattern: ^-?\d+(\.\d+)?$
title: Decimal
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
PayslipItem:
description: A payslip with file, payslip, payroll run, and payroll output metadata.
example:
file:
inserted_at: '2026-04-01T00:00:00Z'
name: payslip.pdf
slug: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
has_employee_payroll_overviews: false
payroll_output: null
payroll_run:
expected_payout_date: '2026-05-01'
period_end: '2026-04-30'
period_start: '2026-04-01'
type: regular
payslip:
active_compensation: null
has_content_layout: false
net_salary: null
slug: 7f4bc535-3d7a-43f5-ab44-360ca91acc7a
properties:
file:
description: File metadata
properties:
inserted_at:
format: date-time
type: string
name:
type: string
slug:
$ref: '#/components/schemas/UuidSlug'
type: object
has_employee_payroll_overviews:
type: boolean
payroll_output:
description: Payroll output breakdown
nullable: true
type: object
payroll_run:
description: Payroll run metadata
nullable: true
properties:
expected_payout_date:
format: date
nullable: true
type: string
period_end:
format: date
type: string
period_start:
format: date
type: string
type:
type: string
type: object
payslip:
description: Payslip data
properties:
active_compensation:
description: Active compensation at the time of the payslip
nullable: true
type: object
has_content_layout:
type: boolean
net_salary:
description: Net salary amount
nullable: true
type: object
slug:
$ref: '#/components/schemas/UuidSlug'
type: object
required:
- file
- payslip
- has_employee_payroll_overviews
title: PayslipItem
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
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
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
BadRequestResponse:
description: Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.
example:
message: invalid {resource}
oneOf:
- properties:
message:
description: A human-readable error message describing what was wrong with the request.
type: string
required:
- message
type: object
- properties:
message:
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
type: object
title: BadRequestResponse
type: object
ListPayslipsResponse:
description: Response schema listing many payslips
example:
current_page: 1
payslips:
- employment_id: 98d3f-employment-id-1oi45n
expected_payout_date: '2021-07-01'
id: 93t3j-employment-id-9suej43
issued_at: '2021-07-01'
net_pay_converted_amount: 1500000
net_pay_source_amount: 1000000
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
payslips:
items:
$ref: '#/components/schemas/Payslip'
type: array
total_count:
description: The total number of records in the result
type: integer
total_pages:
description: The total number of pages the user can go through
type: integer
type: object
title: ListPayslipsResponse
type: object
PayslipFile:
description: A single payslip file with its associated payroll run metadata.
example:
currency:
code: USD
symbol: $
id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
name: payslip.pdf
net_salary:
converted_amount: 460000
converter: Transferwise
fee: '0.00'
rate: '0.92'
source_amount: 500000
period_end: '2026-04-30'
period_start: '2026-04-01'
properties:
currency:
$ref: '#/components/schemas/PayslipFileCurrency'
id:
$ref: '#/components/schemas/UuidSlug'
name:
description: Original filename of the payslip
example: payslip.pdf
type: string
net_salary:
$ref: '#/components/schemas/PayslipFileNetSalary'
period_end:
format: date
nullable: true
type: string
period_start:
format: date
nullable: true
type: string
required:
- id
- name
title: PayslipFile
type: object
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
ForbiddenResponse:
description: Returned when the authenticated user or token does not have permission to perform the requested action. Check that the token has the required OAuth2 scopes and that the user has the necessary role.
example:
message: Forbidden
properties:
message:
pattern: Forbidden
type: string
required:
- message
title: ForbiddenResponse
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
ListPayslipFilesResponse:
description: Response schema listing many payslip_files
example:
current_page: 1
payslip_files:
- currency:
code: USD
symbol: $
id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
name: payslip.pdf
net_salary:
converted_amount: 460000
converter: Transferwise
fee: '0.00'
rate: '0.92'
source_amount: 500000
period_end: '2026-04-30'
period_start: '2026-04-01'
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
payslip_files:
items:
$ref: '#/components/schemas/PayslipFile'
type: array
total_count:
description: The total number of records in the result
type: integer
total_pages:
description: The total number of pages the user can go through
type: integer
type: object
title: ListPayslipFilesResponse
type: object
UuidSlug:
description: Identifier of the employment being terminated.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
title: UuidSlug
type: string
PayslipFileCurrency:
example:
code: USD
symbol: $
nullable: true
properties:
code:
$ref: '#/components/schemas/CurrencyCode'
symbol:
description: The currency symbol
example: $
type: string
required:
- code
- symbol
title: PayslipFileCurrency
type: object
Payslip:
description: A payslip issued to an employee for a specific payroll period.
example:
employment_id: 98d3f-employment-id-1oi45n
expected_payout_date: '2021-07-01'
id: 93t3j-employment-id-9suej43
issued_at: '2021-07-01'
net_pay_converted_amount: 1500000
net_pay_source_amount: 1000000
properties:
employment_id:
description: The unique identifier (UUID) of the employment this payslip belongs to.
type: string
expected_payout_date:
$ref: '#/components/schemas/Date'
id:
description: The unique identifier (UUID) of the payslip.
type: string
issued_at:
description: The date the payslip was issued.
format: date
type: string
net_pay_converted_amount:
description: The net pay amount converted to the company's billing currency, in cents. Only shown if available.
type: integer
net_pay_source_amount:
description: The net pay amount in the source (local) currency, in cents. Only shown if available.
type: integer
required:
- id
- issued_at
- employment_id
title: Payslip
type: object
TooManyRequestsResponse:
description: Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.
example:
message: Too many requests
properties:
message:
pattern: Too many requests
type: string
title: TooManyRequestsResponse
type: object
PayslipFileNetSalary:
additionalProperties: true
description: Net salary amount including source/converted amounts, currencies and conversion rate. Shape produced by `Tiger.Billing.Value.Amount.build/1`.
example:
converted_amount: 460000
converter: Transferwise
fee: '0.00'
rate: '0.92'
source_amount: 500000
nullable: true
properties:
converted_amount:
nullable: true
type: integer
converter:
nullable: true
type: string
fee:
$ref: '#/components/schemas/Decimal'
rate:
$ref: '#/components/schemas/Decimal'
source_amount:
nullable: true
type: integer
title: PayslipFileNetSalary
type: object
ListEmployeePayslipsResponse:
description: Response schema listing many payslips
example:
current_page: 1
payslips:
- file:
inserted_at: '2026-04-01T00:00:00Z'
name: payslip.pdf
slug: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
has_employee_payroll_overviews: false
payroll_output: null
payroll_run:
expected_payout_date: '2026-05-01'
period_end: '2026-04-30'
period_start: '2026-04-01'
type: regular
payslip:
active_compensation: null
has_content_layout: false
net_salary: null
slug: 7f4bc535-3d7a-43f5-ab44-360ca91acc7a
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
payslips:
items:
$ref: '#/components/schemas/PayslipItem'
type: array
total_count:
description: The total number of records in the result
type: integer
total_pages:
description: The total number of pages the user can go through
type: integer
type: object
title: ListEmployeePayslipsResponse
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.
'
flows:
clientCredentials:
scopes:
address:read: address:read
address:write: address:write
bank_account:read: bank_account:read
bank_account:write: bank_account:write
document:read: document:read
document:write: document:write
emergency_contact:read: emergency_contact:read
emergency_contact:write: emergency_contact:write
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
expense:read: expense:read
incentive:read: incentive:read
payroll: payroll
payslip:read: payslip:read
personal_detail:read: personal_detail:read
personal_detail:write: personal_detail:write
time_and_attendance: time_and_attendance
timeoff:read: timeoff:read
timeoff:write: timeoff:write
timesheet:read: timesheet:read
tokenUrl: /auth/oauth2/token
x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
type: oauth2
OAuth2AuthorizationCode:
description: 'Authenticate as the token authorizer using `authorization_code` / `ref
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-payslips-api-openapi.yml