Puzzle Payroll API
The Payroll API from Puzzle — 6 operation(s) for payroll.
OpenAPI Specification
openapi: 3.0.3
info:
title: Puzzle Api Accounts Payroll API
description: Puzzle Api
version: '0'
servers:
- url: https://staging.southparkdata.com/rest/v0
tags:
- name: Payroll
paths:
/company/{id}/workers:
get:
operationId: workersList
summary: Get Workers
description: 'Retrieves a list of all of the company''s workers, both employees and contractors.
Required scope: read:worker'
tags:
- Payroll
parameters:
- name: id
in: path
required: true
description: The company ID
schema:
type: string
minLength: 1
description: Partner-facing external identifier
- name: subset
in: query
required: false
schema:
type: string
enum:
- Active
- Terminated
- Contractor
- name: search
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
workers:
type: array
items:
anyOf:
- type: object
properties:
annualCosts:
type: object
properties:
salaryCost:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
burdenCost:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
fullyLoadedCost:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
required:
- salaryCost
- burdenCost
- fullyLoadedCost
nullable: true
id:
type: string
minLength: 1
description: Partner-facing external identifier
firstName:
type: string
nullable: true
lastName:
type: string
nullable: true
employmentType:
type: string
enum:
- FullTime
- PartTime
- Contractor
jobTitle:
type: string
department:
type: string
nullable: true
startDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
employeeTerminations:
type: array
items:
type: object
properties:
terminationDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
required:
- terminationDate
flsaStatus:
type: string
enum:
- Exempt
- SalariedNonexempt
- Nonexempt
- Owner
nullable: true
officeLocation:
type: object
properties:
id:
type: string
minLength: 1
description: Partner-facing external identifier
city:
type: string
state:
type: string
zipCode:
type: string
required:
- id
- city
- state
- zipCode
payFrequency:
type: string
enum:
- Hour
- Day
- Week
- Month
- Year
- Paycheck
payRate:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
terminated:
type: boolean
required:
- annualCosts
- id
- firstName
- lastName
- employmentType
- jobTitle
- department
- startDate
- employeeTerminations
- flsaStatus
- officeLocation
- payFrequency
- payRate
- terminated
- type: object
properties:
id:
type: string
minLength: 1
description: Partner-facing external identifier
firstName:
type: string
nullable: true
lastName:
type: string
nullable: true
businessName:
type: string
nullable: true
startDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
department:
type: string
nullable: true
hourlyRate:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
nullable: true
isActive:
type: boolean
type:
type: string
enum:
- Individual
- Business
nullable: true
wageType:
type: string
enum:
- Fixed
- Hourly
- Daily
- Weekly
- Monthly
- Biweekly
- Semimonthly
- Annually
- Custom
payRate:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
required:
- id
- firstName
- lastName
- businessName
- startDate
- department
- hourlyRate
- isActive
- type
- wageType
- payRate
required:
- workers
/company/{id}/contractors:
post:
operationId: createContractor
summary: Create Contractor
description: 'Create a contractor for the given company.
Requires scope: write:worker'
tags:
- Payroll
parameters:
- name: id
in: path
required: true
description: The company ID
schema:
type: string
minLength: 1
description: Partner-facing external identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
firstName:
type: string
lastName:
type: string
businessName:
type: string
nullable: true
startDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
type:
type: string
enum:
- Individual
- Business
payRate:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
wageType:
type: string
enum:
- Fixed
- Hourly
- Daily
- Weekly
- Monthly
- Biweekly
- Semimonthly
- Annually
- Custom
isActive:
type: boolean
departmentId:
type: string
minLength: 1
description: Partner-facing external identifier
nativeId:
type: string
required:
- firstName
- lastName
- startDate
- type
- payRate
- wageType
- isActive
- nativeId
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
type: string
minLength: 1
description: Partner-facing external identifier
firstName:
type: string
nullable: true
lastName:
type: string
nullable: true
businessName:
type: string
nullable: true
startDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
department:
type: string
nullable: true
hourlyRate:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
nullable: true
isActive:
type: boolean
type:
type: string
enum:
- Individual
- Business
nullable: true
wageType:
type: string
enum:
- Fixed
- Hourly
- Daily
- Weekly
- Monthly
- Biweekly
- Semimonthly
- Annually
- Custom
payRate:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
required:
- id
- firstName
- lastName
- businessName
- startDate
- department
- hourlyRate
- isActive
- type
- wageType
- payRate
/company/{id}/employees:
post:
operationId: createEmployee
summary: Create Employee
description: 'Create an employee for the given company.
Required scope: write:worker'
tags:
- Payroll
parameters:
- name: id
in: path
required: true
description: The company ID
schema:
type: string
minLength: 1
description: Partner-facing external identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
firstName:
type: string
lastName:
type: string
employmentType:
type: string
enum:
- FullTime
- PartTime
- Contractor
jobTitle:
type: string
startDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
officeLocationId:
type: string
minLength: 1
description: Partner-facing external identifier
payRate:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
payFrequency:
type: string
enum:
- Hour
- Day
- Week
- Month
- Year
- Paycheck
nativeId:
type: string
terminationDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
flsaStatus:
type: string
enum:
- Exempt
- SalariedNonexempt
- Nonexempt
- Owner
departmentId:
type: string
minLength: 1
description: Partner-facing external identifier
required:
- firstName
- lastName
- employmentType
- jobTitle
- startDate
- officeLocationId
- payRate
- payFrequency
- nativeId
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
annualCosts:
type: object
properties:
salaryCost:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
burdenCost:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
fullyLoadedCost:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
required:
- salaryCost
- burdenCost
- fullyLoadedCost
nullable: true
id:
type: string
minLength: 1
description: Partner-facing external identifier
firstName:
type: string
nullable: true
lastName:
type: string
nullable: true
employmentType:
type: string
enum:
- FullTime
- PartTime
- Contractor
jobTitle:
type: string
department:
type: string
nullable: true
startDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
employeeTerminations:
type: array
items:
type: object
properties:
terminationDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
required:
- terminationDate
flsaStatus:
type: string
enum:
- Exempt
- SalariedNonexempt
- Nonexempt
- Owner
nullable: true
officeLocation:
type: object
properties:
id:
type: string
minLength: 1
description: Partner-facing external identifier
city:
type: string
state:
type: string
zipCode:
type: string
required:
- id
- city
- state
- zipCode
payFrequency:
type: string
enum:
- Hour
- Day
- Week
- Month
- Year
- Paycheck
payRate:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
terminated:
type: boolean
required:
- annualCosts
- id
- firstName
- lastName
- employmentType
- jobTitle
- department
- startDate
- employeeTerminations
- flsaStatus
- officeLocation
- payFrequency
- payRate
- terminated
/company/{id}/benefits:
get:
operationId: benefits
summary: Get Benefits
description: 'Retrieves a list of all benefits for the given company. These benefits represent company-level benefits that can have both an employee contribution and a company contribution.
Payrolls will reference these benefits and provide details on the employee and company contribution amounts.
Requires scope: read:company'
tags:
- Payroll
parameters:
- name: id
in: path
required: true
description: The company ID
schema:
type: string
minLength: 1
description: Partner-facing external identifier
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
benefits:
type: array
items:
type: object
properties:
id:
type: string
minLength: 1
description: Partner-facing external identifier
nativeId:
type: string
nullable: true
name:
type: string
description:
type: string
type:
type: string
enum:
- medical
- dental
- vision
- retirement
- commuter
- disability
- life_insurance
- other_non_taxable
- other_taxable
- unknown_benefit
- student_loan
isPreTax:
type: boolean
dataSource:
type: string
required:
- id
- nativeId
- name
- description
- type
- isPreTax
- dataSource
required:
- benefits
post:
operationId: createBenefit
summary: Create Benefit
description: 'Create a benefit for the given company.
Requires scope: write:benefit'
tags:
- Payroll
parameters:
- name: id
in: path
required: true
description: The company ID
schema:
type: string
minLength: 1
description: Partner-facing external identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
nativeId:
type: string
name:
type: string
description:
type: string
type:
type: string
enum:
- medical
- dental
- vision
- retirement
- commuter
- disability
- life_insurance
- other_non_taxable
- other_taxable
- unknown_benefit
- student_loan
description: The value is normalized before matching, so any casing that maps onto a listed value is accepted.
isPreTax:
type: boolean
required:
- nativeId
- name
- description
- type
- isPreTax
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
type: string
minLength: 1
description: Partner-facing external identifier
nativeId:
type: string
nullable: true
name:
type: string
description:
type: string
type:
type: string
enum:
- medical
- dental
- vision
- retirement
- commuter
- disability
- life_insurance
- other_non_taxable
- other_taxable
- unknown_benefit
- student_loan
isPreTax:
type: boolean
dataSource:
type: string
required:
- id
- nativeId
- name
- description
- type
- isPreTax
- dataSource
/company/{id}/payrolls:
post:
operationId: createDetailedPayroll
summary: Create Payroll
description: 'Create a single payroll.
Payrolls can only be added to accounts with the Payroll type.
All the amounts on the top-level payroll object are the totals for all the associated compensations
Payrolls must have at least one employeeCompensation OR contractorCompensation
The transactionAmounts field should contain a list of all the amounts for all the non-reimbursement transactions that were used to fund this payroll.
If no transactionAmounts are provided, the companyDebit amount will be used instead
Puzzle uses this information to link this payroll with all the transactions that funded it to ensure everything gets represented in the general ledger correctly.
Puzzle currently only supports USD currencies
Required scope: write:payroll'
tags:
- Payroll
parameters:
- name: id
in: path
required: true
description: The company ID
schema:
type: string
minLength: 1
description: Partner-facing external identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
accountId:
type: string
minLength: 1
description: Partner-facing external identifier
nativeId:
type: string
withdrawalDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
checkDate:
type: string
minLength: 1
description: Calendar date, YYYY-MM-DD
companyDebit:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
transactionAmounts:
type: array
items:
type: object
properties:
amount:
type: string
minLength: 1
description: Arbitrary-precision decimal, serialized as a string
currency:
type: string
minLength: 3
maxLength: 3
description: ISO 4217 currency code
required:
- amount
- currency
description: A monetary amount with its currency
netPay:
type: object
properties:
amount:
type: string
minLeng
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/puzzle/refs/heads/main/openapi/puzzle-payroll-api-openapi.yml