openapi: 3.1.0
info:
title: Deel Global Payroll API
description: |
Global Payroll APIs for direct employees on the client's own legal entities across
120+ countries. Covers payroll events/cycles, gross-to-net adjustments (bonuses,
deductions, one-time payments, expense reimbursements), time-tracking shifts,
payslips/paystubs, and Global Payroll hiring.
version: '2026-05-25'
contact:
name: Deel Developer Support
url: https://developer.deel.com/api/global-payroll/introduction
servers:
- url: https://api.letsdeel.com/rest/v2
description: Production
- url: https://api-sandbox.demo.deel.com/rest/v2
description: Sandbox
security:
- BearerAuth: []
tags:
- name: Global Payroll
description: Payroll cycles and events for Global Payroll legal entities
- name: Adjustments
description: Gross-to-net payroll adjustments — bonuses, deductions, one-time payments
- name: Time Tracking
description: Time tracking shifts for Global Payroll employees
- name: Payslips
description: Employee payslips
- name: Paystubs
description: US paystubs
- name: GP Hiring
description: Global Payroll employee hiring
paths:
/gp/payroll-events:
get:
operationId: getPayrollEvents
summary: List Payroll Events
description: Returns the open and historical payroll cycles for the organization's Global Payroll entities.
tags: [Global Payroll]
parameters:
- { name: legal_entity_id, in: query, schema: { type: string } }
- { name: status, in: query, schema: { type: string, enum: [draft, open, locked, processed, paid, closed] } }
- { name: from, in: query, schema: { type: string, format: date } }
- { name: to, in: query, schema: { type: string, format: date } }
responses:
'200':
description: Payroll events
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/PayrollEvent' } }
/gp/payroll-events/{event_id}:
get:
operationId: getPayrollEvent
summary: Retrieve A Payroll Event
tags: [Global Payroll]
parameters:
- { name: event_id, in: path, required: true, schema: { type: string } }
responses:
'200':
description: Payroll event
content:
application/json:
schema: { $ref: '#/components/schemas/PayrollEvent' }
/gp/adjustments:
get:
operationId: getAdjustments
summary: List Payroll Adjustments
tags: [Adjustments]
parameters:
- { name: payroll_event_id, in: query, schema: { type: string } }
- { name: worker_id, in: query, schema: { type: string } }
responses:
'200':
description: Adjustments
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/PayrollAdjustment' } }
post:
operationId: createAdjustment
summary: Create Payroll Adjustment
description: Add a gross-to-net adjustment to a worker's pay for the current cycle.
tags: [Adjustments]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/PayrollAdjustmentCreate' }
responses:
'201':
description: Adjustment created
content:
application/json:
schema: { $ref: '#/components/schemas/PayrollAdjustment' }
/gp/time-tracking/shifts:
get:
operationId: getShifts
summary: List Time Tracking Shifts
tags: [Time Tracking]
parameters:
- { name: worker_id, in: query, schema: { type: string } }
- { name: from, in: query, schema: { type: string, format: date } }
- { name: to, in: query, schema: { type: string, format: date } }
responses:
'200':
description: Shifts
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Shift' } }
post:
operationId: createShift
summary: Create Shift
tags: [Time Tracking]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ShiftCreate' }
responses:
'201':
description: Shift created
content:
application/json:
schema: { $ref: '#/components/schemas/Shift' }
/payslips:
get:
operationId: getPayslips
summary: List Payslips
tags: [Payslips]
parameters:
- { name: worker_id, in: query, schema: { type: string } }
- { name: year, in: query, schema: { type: integer } }
responses:
'200':
description: Payslips
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Payslip' } }
/paystubs:
get:
operationId: getPaystubs
summary: List Paystubs
description: US-specific paystubs with state and federal tax breakdowns.
tags: [Paystubs]
parameters:
- { name: worker_id, in: query, schema: { type: string } }
- { name: year, in: query, schema: { type: integer } }
responses:
'200':
description: Paystubs
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Paystub' } }
/gp/contracts:
post:
operationId: createGpContract
summary: Create Global Payroll Contract
description: Hire a direct employee onto a Global Payroll legal entity.
tags: [GP Hiring]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/GpContractCreate' }
responses:
'201':
description: GP contract created
content:
application/json:
schema:
type: object
properties:
id: { type: string }
status: { type: string }
components:
securitySchemes:
BearerAuth: { type: http, scheme: bearer, bearerFormat: opaque }
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
schema: { type: string, format: uuid }
schemas:
PayrollEvent:
type: object
properties:
id: { type: string }
legal_entity_id: { type: string }
country: { type: string }
currency: { type: string }
cycle_start: { type: string, format: date }
cycle_end: { type: string, format: date }
cutoff_date: { type: string, format: date }
pay_date: { type: string, format: date }
status: { type: string, enum: [draft, open, locked, processed, paid, closed] }
total_gross: { type: number }
total_net: { type: number }
worker_count: { type: integer }
PayrollAdjustment:
type: object
properties:
id: { type: string }
worker_id: { type: string }
payroll_event_id: { type: string }
type: { type: string, enum: [bonus, deduction, commission, reimbursement, allowance, garnishment, one_time, recurring] }
amount: { type: number }
currency: { type: string }
taxable: { type: boolean }
description: { type: string }
status: { type: string, enum: [pending, approved, applied, declined] }
PayrollAdjustmentCreate:
type: object
required: [worker_id, type, amount, currency]
properties:
worker_id: { type: string }
payroll_event_id: { type: string }
type: { type: string, enum: [bonus, deduction, commission, reimbursement, allowance, garnishment, one_time, recurring] }
amount: { type: number }
currency: { type: string }
taxable: { type: boolean, default: true }
description: { type: string }
Shift:
type: object
properties:
id: { type: string }
worker_id: { type: string }
start_at: { type: string, format: date-time }
end_at: { type: string, format: date-time }
break_minutes: { type: integer }
notes: { type: string }
status: { type: string, enum: [draft, submitted, approved, declined] }
ShiftCreate:
type: object
required: [worker_id, start_at, end_at]
properties:
worker_id: { type: string }
start_at: { type: string, format: date-time }
end_at: { type: string, format: date-time }
break_minutes: { type: integer }
notes: { type: string }
Payslip:
type: object
properties:
id: { type: string }
worker_id: { type: string }
period_start: { type: string, format: date }
period_end: { type: string, format: date }
gross: { type: number }
net: { type: number }
currency: { type: string }
download_url: { type: string, format: uri }
Paystub:
type: object
properties:
id: { type: string }
worker_id: { type: string }
period_start: { type: string, format: date }
period_end: { type: string, format: date }
gross: { type: number }
net: { type: number }
federal_tax: { type: number }
state_tax: { type: number }
fica: { type: number }
currency: { type: string, default: USD }
GpContractCreate:
type: object
required: [legal_entity_id, employee, country, salary, currency, start_date]
properties:
legal_entity_id: { type: string }
employee:
type: object
properties:
first_name: { type: string }
last_name: { type: string }
email: { type: string, format: email }
country: { type: string }
salary: { type: number }
currency: { type: string }
salary_frequency: { type: string, enum: [yearly, monthly] }
start_date: { type: string, format: date }
job_title: { type: string }