Create single and bulk employee checks (paychecks), attach and edit shifts, preview payroll, download paystub PDFs, and run pay runs that calculate gross-to-net and taxes.
openapi: 3.0.3
info:
title: Zeal API
description: >-
Zeal is an embedded payroll-as-a-service platform. This representative
OpenAPI describes the core surfaces of the Zeal API used to build payroll
products: onboarding companies, employees, and contractors; running pay
runs (employee checks) and contractor payments; managing pay schedules,
tax parameters, reports, funding, and webhooks. All requests are
authenticated with a Bearer API key and scoped by a companyID. Use a test
API key against Test Mode (no money moves) before switching to a live key.
termsOfService: https://www.zeal.com/terms
contact:
name: Zeal Support
url: https://docs.zeal.com
email: support@zeal.com
version: '1.0'
servers:
- url: https://api.zeal.com
description: Zeal API (test or live selected by API key)
security:
- bearerAuth: []
tags:
- name: Companies
- name: Employees
- name: Contractors
- name: Employee Check
- name: Contractor Payments
- name: Pay Schedules
- name: Onboarding
- name: Tax
- name: Reports
- name: Funding
paths:
/companies:
post:
operationId: createCompany
tags: [Companies]
summary: Create a company
description: Create a new employer company on the platform.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCompanyRequest'
responses:
'200':
description: The created company.
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
get:
operationId: getCompanyInformation
tags: [Companies]
summary: Get company information
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: The company record.
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
put:
operationId: updateCompanyInformation
tags: [Companies]
summary: Update company information
description: >-
Update company profile fields such as payroll_firstCheckDate,
payroll_schedule, and payroll_firstPayPeriodID.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCompanyRequest'
responses:
'200':
description: The updated company.
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
/companies/onboard:
get:
operationId: getCompanyOnboardingLink
tags: [Companies, Onboarding]
summary: Get a company onboarding link
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: A hosted onboarding link for the company.
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardLink'
/bankAccount:
post:
operationId: createCompanyBankAccount
tags: [Companies]
summary: Create a company bank account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountRequest'
responses:
'200':
description: The created bank account.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
/employees:
post:
operationId: createEmployee
tags: [Employees]
summary: Create an employee
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmployeeRequest'
responses:
'200':
description: The created employee.
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
get:
operationId: getEmployees
tags: [Employees]
summary: Get employees
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: A list of employees.
content:
application/json:
schema:
type: object
properties:
employees:
type: array
items:
$ref: '#/components/schemas/Employee'
put:
operationId: updateEmployeeInformation
tags: [Employees]
summary: Update employee information
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
responses:
'200':
description: The updated employee.
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
/employees/onboarding:
get:
operationId: generateEmployeeOnboardingLink
tags: [Employees, Onboarding]
summary: Generate an employee onboarding link
parameters:
- $ref: '#/components/parameters/companyID'
- name: employeeID
in: query
required: true
schema:
type: string
responses:
'200':
description: A hosted onboarding link for the employee.
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardLink'
/taxes/employee/setup:
post:
operationId: setEmployeeTaxParameters
tags: [Employees, Tax]
summary: Set employee tax parameters
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeTaxParameters'
responses:
'200':
description: The saved tax parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeTaxParameters'
/taxes/employee/definitions:
get:
operationId: getEmployeeTaxParameterDefinitions
tags: [Employees, Tax]
summary: Get employee tax parameter definitions
parameters:
- $ref: '#/components/parameters/companyID'
- name: employeeID
in: query
required: true
schema:
type: string
responses:
'200':
description: The tax parameter definitions required for the employee.
content:
application/json:
schema:
type: object
/contractors:
post:
operationId: createContractor
tags: [Contractors]
summary: Create a contractor
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContractorRequest'
responses:
'200':
description: The created contractor.
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor'
get:
operationId: getContractors
tags: [Contractors]
summary: Get contractors
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: A list of contractors.
content:
application/json:
schema:
type: object
properties:
contractors:
type: array
items:
$ref: '#/components/schemas/Contractor'
put:
operationId: updateContractorInformation
tags: [Contractors]
summary: Update contractor information
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor'
responses:
'200':
description: The updated contractor.
content:
application/json:
schema:
$ref: '#/components/schemas/Contractor'
/contractors/onboard:
get:
operationId: getContractorOnboardingLink
tags: [Contractors, Onboarding]
summary: Generate a contractor onboarding link
parameters:
- $ref: '#/components/parameters/companyID'
- name: contractorID
in: query
required: true
schema:
type: string
responses:
'200':
description: A hosted onboarding link for the contractor.
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardLink'
/employeeCheck:
post:
operationId: createEmployeeCheck
tags: [Employee Check]
summary: Create an employee check
description: >-
Create a paycheck (employee check) for a reporting period. Zeal
calculates gross-to-net, employee and employer taxes, and deductions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmployeeCheckRequest'
responses:
'200':
description: The created employee check(s).
content:
application/json:
schema:
type: object
properties:
checks:
type: array
items:
$ref: '#/components/schemas/EmployeeCheck'
get:
operationId: getEmployeeChecksByEmployee
tags: [Employee Check]
summary: Get employee checks by employee
parameters:
- $ref: '#/components/parameters/companyID'
- name: employeeID
in: query
required: true
schema:
type: string
responses:
'200':
description: A list of employee checks.
content:
application/json:
schema:
type: object
properties:
checks:
type: array
items:
$ref: '#/components/schemas/EmployeeCheck'
put:
operationId: updateEmployeeCheck
tags: [Employee Check]
summary: Update an employee check
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeCheck'
responses:
'200':
description: The updated employee check.
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeCheck'
delete:
operationId: deleteEmployeeCheck
tags: [Employee Check]
summary: Delete an employee check
parameters:
- $ref: '#/components/parameters/companyID'
- name: employeeCheckID
in: query
required: true
schema:
type: string
responses:
'200':
description: Deletion result.
content:
application/json:
schema:
type: object
/employeeCheck/bulk:
post:
operationId: createBulkEmployeeChecks
tags: [Employee Check]
summary: Create bulk employee checks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
companyID:
type: string
checks:
type: array
items:
$ref: '#/components/schemas/CreateEmployeeCheckRequest'
responses:
'200':
description: The created employee checks.
content:
application/json:
schema:
type: object
/paystub:
get:
operationId: downloadPaystubPdf
tags: [Employee Check]
summary: Download a paystub PDF
parameters:
- $ref: '#/components/parameters/companyID'
- name: employeeCheckID
in: query
required: true
schema:
type: string
responses:
'200':
description: The paystub PDF.
content:
application/pdf:
schema:
type: string
format: binary
/contractorPayments:
post:
operationId: createContractorPayment
tags: [Contractor Payments]
summary: Create a contractor payment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContractorPaymentRequest'
responses:
'200':
description: The created contractor payment.
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorPayment'
get:
operationId: getContractorPayments
tags: [Contractor Payments]
summary: Get contractor payments
parameters:
- $ref: '#/components/parameters/companyID'
- name: contractorID
in: query
required: false
schema:
type: string
responses:
'200':
description: A list of contractor payments.
content:
application/json:
schema:
type: object
properties:
payments:
type: array
items:
$ref: '#/components/schemas/ContractorPayment'
put:
operationId: updateContractorPayment
tags: [Contractor Payments]
summary: Update a contractor payment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorPayment'
responses:
'200':
description: The updated contractor payment.
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorPayment'
delete:
operationId: deleteContractorPayment
tags: [Contractor Payments]
summary: Delete a contractor payment
parameters:
- $ref: '#/components/parameters/companyID'
- name: paymentID
in: query
required: true
schema:
type: string
responses:
'200':
description: Deletion result.
content:
application/json:
schema:
type: object
/contractorPayments/disburse:
post:
operationId: triggerContractorDisbursement
tags: [Contractor Payments]
summary: Trigger a contractor payment disbursement
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
companyID:
type: string
paymentIDs:
type: array
items:
type: string
responses:
'200':
description: Disbursement result.
content:
application/json:
schema:
type: object
/reportingPeriods:
get:
operationId: getAllReportingPeriods
tags: [Pay Schedules]
summary: Get all reporting periods
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: The reporting periods for the company's pay schedule.
content:
application/json:
schema:
type: object
properties:
reportingPeriods:
type: array
items:
$ref: '#/components/schemas/ReportingPeriod'
/reportingPeriods/upcoming:
get:
operationId: getUpcomingRegularPayroll
tags: [Pay Schedules]
summary: Get upcoming regular payroll
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: The next upcoming regular payroll period.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportingPeriod'
/checkDate:
get:
operationId: getNextAvailableCheckDate
tags: [Pay Schedules]
summary: Get the next available check / pay date
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: The next available check date.
content:
application/json:
schema:
type: object
properties:
checkDate:
type: string
format: date
/taxes/location:
post:
operationId: resolveTaxableLocation
tags: [Tax]
summary: Resolve a taxable location
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
companyID:
type: string
address:
type: string
responses:
'200':
description: The resolved taxable location.
content:
application/json:
schema:
$ref: '#/components/schemas/TaxableLocation'
/minimumWage:
get:
operationId: getMinimumWageRules
tags: [Tax]
summary: Get minimum wage rules
parameters:
- name: jurisdiction
in: query
required: false
schema:
type: string
responses:
'200':
description: The applicable minimum wage rules.
content:
application/json:
schema:
type: object
/reports/payrollJournal:
post:
operationId: createPayrollJournalReport
tags: [Reports]
summary: Create a payroll journal report
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReportRequest'
responses:
'200':
description: A report job reference.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportJob'
/reports/cashRequirements:
post:
operationId: createCashRequirementsReport
tags: [Reports]
summary: Create a cash requirements report
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReportRequest'
responses:
'200':
description: A report job reference.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportJob'
/reports/status:
get:
operationId: getReportJobStatus
tags: [Reports]
summary: Get report job status
parameters:
- name: jobID
in: query
required: true
schema:
type: string
responses:
'200':
description: The report job status.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportJob'
/reports/download:
get:
operationId: retrieveReportDownload
tags: [Reports]
summary: Retrieve a finished report download
parameters:
- name: jobID
in: query
required: true
schema:
type: string
responses:
'200':
description: The finished report.
content:
application/json:
schema:
type: object
/reserve/balance:
get:
operationId: getReserveBalance
tags: [Funding]
summary: Get the reserve / provider balance
parameters:
- $ref: '#/components/parameters/companyID'
responses:
'200':
description: The reserve balance funding payroll.
content:
application/json:
schema:
type: object
properties:
balance:
type: number
currency:
type: string
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Provide your Zeal API key as a Bearer token:
`Authorization: Bearer <YOUR_API_KEY>`. Use a test key for Test Mode
and a live key for production. Requests are additionally scoped by a
companyID passed in the body or query.
parameters:
companyID:
name: companyID
in: query
required: true
description: The Zeal companyID identifying the employer account.
schema:
type: string
schemas:
CreateCompanyRequest:
type: object
required: [business_name, ein]
properties:
business_name:
type: string
ein:
type: string
email:
type: string
UpdateCompanyRequest:
type: object
properties:
companyID:
type: string
payroll_firstCheckDate:
type: string
format: date
payroll_schedule:
type: string
enum: [weekly, biweekly, semimonthly, monthly]
payroll_firstPayPeriodID:
type: string
Company:
type: object
properties:
companyID:
type: string
business_name:
type: string
ein:
type: string
status:
type: string
enum: [needs_onboarding, onboarding, onboarded]
OnboardLink:
type: object
properties:
url:
type: string
format: uri
expiration:
type: string
format: date-time
BankAccountRequest:
type: object
properties:
companyID:
type: string
institution_name:
type: string
account_number:
type: string
routing_number:
type: string
account_type:
type: string
enum: [checking, savings]
BankAccount:
type: object
properties:
id:
type: string
institution_name:
type: string
account_type:
type: string
status:
type: string
CreateEmployeeRequest:
type: object
required: [companyID, first_name, last_name]
properties:
companyID:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
default_pay_rate:
type: number
Employee:
type: object
properties:
id:
type: string
companyID:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
onboarded:
type: boolean
EmployeeTaxParameters:
type: object
properties:
companyID:
type: string
employeeID:
type: string
parameters:
type: object
CreateContractorRequest:
type: object
required: [companyID, type]
properties:
companyID:
type: string
type:
type: string
enum: [individual, business]
first_name:
type: string
last_name:
type: string
business_name:
type: string
email:
type: string
Contractor:
type: object
properties:
id:
type: string
companyID:
type: string
type:
type: string
first_name:
type: string
last_name:
type: string
business_name:
type: string
onboarded:
type: boolean
CreateEmployeeCheckRequest:
type: object
required: [companyID, employeeID, reportingPeriodID]
properties:
companyID:
type: string
employeeID:
type: string
reportingPeriodID:
type: string
check_date:
type: string
format: date
shifts:
type: array
items:
$ref: '#/components/schemas/Shift'
Shift:
type: object
properties:
time:
type: string
format: date-time
hourly_wage:
type: number
hours:
type: number
wage_type:
type: string
EmployeeCheck:
type: object
properties:
employeeCheckID:
type: string
employeeID:
type: string
reportingPeriodID:
type: string
check_date:
type: string
format: date
gross_pay:
type: number
net_pay:
type: number
status:
type: string
enum: [pending, pre-processed, processed, failed]
CreateContractorPaymentRequest:
type: object
required: [companyID, contractorID, amount]
properties:
companyID:
type: string
contractorID:
type: string
amount:
type: number
disbursement_method:
type: string
enum: [direct_deposit, prepaid, off_platform]
ContractorPayment:
type: object
properties:
paymentID:
type: string
contractorID:
type: string
amount:
type: number
status:
type: string
enum: [pending, pre-processed, processed, failed]
ReportingPeriod:
type: object
properties:
id:
type: string
start:
type: string
format: date
end:
type: string
format: date
check_date:
type: string
format: date
TaxableLocation:
type: object
properties:
id:
type: string
jurisdiction:
type: string
state:
type: string
ReportRequest:
type: object
required: [companyID]
properties:
companyID:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
ReportJob:
type: object
properties:
jobID:
type: string
status:
type: string
enum: [queued, processing, complete, failed]
download_url:
type: string
format: uri