Remote Pay Items API
The Pay Items API from Remote — 2 operation(s) for pay items.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Pay Items API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Pay Items
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 Items
/v1/pay-items:
get:
callbacks: {}
deprecated: false
description: 'Lists pay items for a company with optional filtering by employment, date range, and pagination.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage payroll runs (`payroll`) | View pay items (`pay_item:read`) | Manage pay items (`pay_item:write`) |
'
operationId: get_v1_pay-items
parameters:
- description: Filter by employment slug
in: query
name: employment_slug
required: false
schema:
$ref: '#/components/schemas/UuidSlug'
- description: Filter pay items with effective_date >= given date (YYYY-MM-DD)
in: query
name: effective_from
required: false
schema:
$ref: '#/components/schemas/Date'
- description: Filter pay items with effective_date <= given date (YYYY-MM-DD)
in: query
name: effective_to
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/ListPayItemsResponse'
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
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- pay_item:read
- pay_item:write
- payroll
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- pay_item:read
- pay_item:write
- payroll
- all:write
- all:read
summary: List Pay Items
tags:
- Pay Items
components:
schemas:
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
BulkCreatePayItemsResponse:
additionalProperties: false
example:
data:
failures:
- error: not_found
row_number: 0
successes:
- pay_item:
amount: 7200
code: overtime
effective_date: '2026-03-11'
employment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider_data:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
row_number: 0
properties:
data:
properties:
failures:
items:
$ref: '#/components/schemas/PayItemBulkCreateFailures'
type: array
successes:
items:
$ref: '#/components/schemas/PayItemBulkCreateSuccesses'
type: array
required:
- successes
- failures
type: object
required:
- data
title: BulkCreatePayItemsResponse
type: object
PayItemBulkCreateFailures:
additionalProperties: false
example:
error: not_found
row_number: 0
properties:
error:
description: Failure reason. Includes `employment_not_global_payroll` when the provided employment is not Global Payroll.
oneOf:
- type: string
- $ref: '#/components/schemas/UnprocessableEntityResponse'
row_number:
type: integer
title: PayItemBulkCreateFailures
type: object
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
ConflictResponse:
description: Returned when the request conflicts with the current state of a resource (HTTP 409). For example, trying to create a resource that already exists or performing an action that requires the resource to be in a different state.
example:
message: Company needs to be in status active to manage employments
properties:
message:
description: A human-readable message describing the conflict and the expected state.
type: string
title: ConflictResponse
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
PayItem:
additionalProperties: false
example:
amount: 7200
code: overtime
effective_date: '2026-03-11'
employment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider_data:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
properties:
amount:
description: Value of the pay item (e.g. duration in seconds, amount in cents)
type: integer
code:
description: Pay item type code
type: string
effective_date:
description: Working day date (YYYY-MM-DD)
format: date
type: string
employment_id:
allOf:
- $ref: '#/components/schemas/UuidSlug'
description: Employment UUID.
provider_data:
$ref: '#/components/schemas/PayItemProviderData'
required:
- employment_id
- effective_date
- code
- amount
- provider_data
title: PayItem
type: object
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
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
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
ListPayItemsResponse:
additionalProperties: false
example:
data:
current_page: 1
data:
- amount: 7200
code: overtime
effective_date: '2026-03-11'
employment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider_data:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: Current page number
minimum: 1
type: integer
data:
description: List of pay items
items:
$ref: '#/components/schemas/PayItem'
type: array
total_count:
description: Total number of pay items
minimum: 0
type: integer
total_pages:
description: Total number of pages
minimum: 0
type: integer
required:
- data
- current_page
- total_pages
- total_count
type: object
required:
- data
title: ListPayItemsResponse
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
UuidSlug:
description: Identifier of the employment being terminated.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
title: UuidSlug
type: string
PayItemProviderData:
additionalProperties: false
example:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
properties:
adjustment_effective_date:
description: Correction date for a previously submitted day (YYYY-MM-DD)
format: date
type: string
hourly_rate:
description: Hourly rate in cents
type: integer
hourly_rate_currency_code:
$ref: '#/components/schemas/CurrencyCode'
is_deduction:
description: Whether payout_amount should be considered a deduction
type: boolean
pay_rate:
description: Overtime rate multiplier (e.g. 1.5)
type: number
payout_amount:
description: Associated payout or deduction in cents
type: integer
payout_currency_code:
$ref: '#/components/schemas/CurrencyCode'
shift_code:
description: Shift identifier from partner system
type: string
work_day_duration:
description: Expected work day duration in seconds
type: integer
title: PayItemProviderData
type: object
BulkCreatePayItemsParams:
additionalProperties: false
example:
pay_items:
- amount: 7200
code: overtime
effective_date: '2026-03-11'
employment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider_data:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
properties:
pay_items:
items:
$ref: '#/components/schemas/PayItemParams'
maxItems: 500
minItems: 1
type: array
required:
- pay_items
title: BulkCreatePayItemsParams
type: object
PayItemParams:
additionalProperties: false
example:
amount: 7200
code: overtime
effective_date: '2026-03-11'
employment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider_data:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
properties:
amount:
description: Duration in seconds
minimum: 1
type: integer
code:
description: Pay item type code
type: string
effective_date:
description: Working day date (YYYY-MM-DD)
format: date
type: string
employment_id:
allOf:
- $ref: '#/components/schemas/UuidSlug'
description: Employment UUID. Only Global Payroll employments are supported.
provider_data:
$ref: '#/components/schemas/PayItemProviderData'
required:
- employment_id
- effective_date
- code
- amount
title: PayItemParams
type: object
PayItemBulkCreateSuccesses:
additionalProperties: false
example:
pay_item:
amount: 7200
code: overtime
effective_date: '2026-03-11'
employment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider_data:
adjustment_effective_date: '2026-03-15'
hourly_rate: 2550
hourly_rate_currency_code: SGD
is_deduction: false
pay_rate: 1.5
payout_amount: 1500000
payout_currency_code: SGD
shift_code: DAY
work_day_duration: 28800
row_number: 0
properties:
pay_item:
$ref: '#/components/schemas/PayItem'
row_number:
type: integer
required:
- row_number
- pay_item
title: PayItemBulkCreateSuccesses
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
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` / `refresh_token` grants in the OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
refreshUrl: /auth/oauth2/token
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
type: oauth2
OAuth2ClientCredentials:
description: 'Authenticate using `client_credentials` grant in the OAuth 2.0 protocol.
'
flows:
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