Configure how and when workers are paid via worker pay groups, work weeks, and pay types that define pay frequency and cadence for an employer's payroll.
openapi: 3.0.1
info:
title: Salsa Payroll API
description: >-
Representative OpenAPI description of the Salsa embedded payroll REST API.
Salsa is partner-gated payroll infrastructure - approved platform partners
receive separate sandbox and production Bearer API keys and use these
endpoints to provision employers and workers, run payroll, disburse worker
payments, configure tax, and manage webhooks for US and Canada. This is a
faithful, representative subset of the surface documented at
https://docs.salsa.dev/reference and is not the vendor's official machine
specification.
termsOfService: https://www.salsa.dev/legal
contact:
name: Salsa Support
url: https://docs.salsa.dev/
version: rest-v1
servers:
- url: https://api.salsa.dev/api/rest/v1
description: Production (partner production API key)
- url: https://api.sandbox.salsa.dev/api/rest/v1
description: Sandbox (partner sandbox API key)
security:
- bearerAuth: []
tags:
- name: Companies
description: Employer (company) entities and configuration.
- name: Workers
description: Employees and contractors.
- name: Pay Schedules
description: Worker pay groups and work weeks.
- name: Payrolls
description: Payroll runs and reports.
- name: Payments
description: Individual worker payments and disbursements.
- name: Onboarding & Sessions
description: User tokens, hosted onboarding, and mock onboarding.
- name: Tax
description: Employer and worker tax setup.
- name: Webhooks
description: Webhook endpoint management.
paths:
/employers:
post:
operationId: createEmployer
tags: [Companies]
summary: Create an employer (company).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmployerCreate'
responses:
'201':
description: Employer created.
content:
application/json:
schema:
$ref: '#/components/schemas/Employer'
get:
operationId: listEmployers
tags: [Companies]
summary: Retrieve employers.
responses:
'200':
description: A list of employers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Employer'
/employers/{employerId}:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: getEmployer
tags: [Companies]
summary: Retrieve an employer.
responses:
'200':
description: The employer.
content:
application/json:
schema:
$ref: '#/components/schemas/Employer'
patch:
operationId: updateEmployer
tags: [Companies]
summary: Update an employer.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmployerCreate'
responses:
'200':
description: The updated employer.
content:
application/json:
schema:
$ref: '#/components/schemas/Employer'
delete:
operationId: deleteEmployer
tags: [Companies]
summary: Delete an employer.
responses:
'204':
description: Deleted.
/employers/{employerId}/pay-types:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: listPayTypes
tags: [Companies]
summary: List an employer's pay types.
responses:
'200':
description: A list of pay types.
post:
operationId: createPayType
tags: [Companies]
summary: Create a pay type for an employer.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Pay type created.
/employers/{employerId}/bank-accounts:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: listEmployerBankAccounts
tags: [Companies]
summary: List an employer's bank accounts.
responses:
'200':
description: A list of bank accounts.
post:
operationId: createEmployerBankAccount
tags: [Companies]
summary: Create a bank account for an employer.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Bank account created.
/employers/{employerId}/workers:
parameters:
- $ref: '#/components/parameters/EmployerId'
post:
operationId: createWorker
tags: [Workers]
summary: Create a worker.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkerCreate'
responses:
'201':
description: Worker created.
content:
application/json:
schema:
$ref: '#/components/schemas/Worker'
get:
operationId: listWorkers
tags: [Workers]
summary: Retrieve an employer's workers.
responses:
'200':
description: A list of workers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Worker'
/employers/{employerId}/workers/{workerId}:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/WorkerId'
get:
operationId: getWorker
tags: [Workers]
summary: Retrieve a worker.
responses:
'200':
description: The worker.
content:
application/json:
schema:
$ref: '#/components/schemas/Worker'
patch:
operationId: updateWorker
tags: [Workers]
summary: Update a worker.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkerCreate'
responses:
'200':
description: The updated worker.
delete:
operationId: deleteWorker
tags: [Workers]
summary: Delete a worker.
responses:
'204':
description: Deleted.
/employers/{employerId}/workers/{workerId}/contracts:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/WorkerId'
get:
operationId: listWorkerContracts
tags: [Workers]
summary: List a worker's contracts.
responses:
'200':
description: A list of contracts.
post:
operationId: createWorkerContract
tags: [Workers]
summary: Create a worker contract (W-2 employee or 1099 contractor terms).
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Contract created.
/employers/{employerId}/workers/{workerId}/bank-accounts:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/WorkerId'
get:
operationId: listWorkerBankAccounts
tags: [Workers]
summary: List a worker's bank accounts.
responses:
'200':
description: A list of bank accounts.
post:
operationId: createWorkerBankAccount
tags: [Workers]
summary: Create a bank account for a worker.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Bank account created.
/employers/{employerId}/worker-pay-groups:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: listWorkerPayGroups
tags: [Pay Schedules]
summary: List an employer's worker pay groups (pay schedules).
responses:
'200':
description: A list of pay groups.
post:
operationId: createWorkerPayGroup
tags: [Pay Schedules]
summary: Create a worker pay group defining pay frequency and cadence.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Pay group created.
/employers/{employerId}/work-weeks:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: listWorkWeeks
tags: [Pay Schedules]
summary: List an employer's work weeks.
responses:
'200':
description: A list of work weeks.
post:
operationId: createWorkWeek
tags: [Pay Schedules]
summary: Create a work week for an employer.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Work week created.
/employers/{employerId}/payroll-runs:
parameters:
- $ref: '#/components/parameters/EmployerId'
post:
operationId: createPayrollRun
tags: [Payrolls]
summary: Create a payroll run.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollRunCreate'
responses:
'201':
description: Payroll run created.
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollRun'
get:
operationId: listPayrollRuns
tags: [Payrolls]
summary: Retrieve payroll runs.
responses:
'200':
description: A list of payroll runs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PayrollRun'
/employers/{employerId}/payroll-runs/{payrollRunId}:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/PayrollRunId'
get:
operationId: getPayrollRun
tags: [Payrolls]
summary: Retrieve a payroll run.
responses:
'200':
description: The payroll run.
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollRun'
delete:
operationId: deletePayrollRun
tags: [Payrolls]
summary: Delete a payroll run.
responses:
'204':
description: Deleted.
/employers/{employerId}/payroll-runs/{payrollRunId}/preview:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/PayrollRunId'
post:
operationId: previewPayrollRun
tags: [Payrolls]
summary: Preview a payroll run (calculated gross-to-net before confirmation).
responses:
'200':
description: Payroll run preview.
/employers/{employerId}/payroll-runs/{payrollRunId}/confirm:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/PayrollRunId'
post:
operationId: confirmPayrollRun
tags: [Payrolls]
summary: Confirm a payroll run and initiate funding and disbursement.
responses:
'200':
description: Payroll run confirmed.
/employers/{employerId}/reports/payroll-journal:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: getPayrollJournalReport
tags: [Payrolls]
summary: Retrieve the payroll journal report.
responses:
'200':
description: The payroll journal report.
/employers/{employerId}/workers/{workerId}/payments:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/WorkerId'
post:
operationId: createWorkerPayment
tags: [Payments]
summary: Create a worker payment.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Worker payment created.
get:
operationId: listWorkerPayments
tags: [Payments]
summary: Retrieve a worker's payments.
responses:
'200':
description: A list of worker payments.
/employers/{employerId}/workers/{workerId}/payments/{paymentId}/confirm:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/WorkerId'
- name: paymentId
in: path
required: true
schema:
type: string
post:
operationId: confirmWorkerPayment
tags: [Payments]
summary: Confirm a worker payment for disbursement.
responses:
'200':
description: Payment confirmed.
/employers/{employerId}/workers/{workerId}/payments/{paymentId}/deductions:
parameters:
- $ref: '#/components/parameters/EmployerId'
- $ref: '#/components/parameters/WorkerId'
- name: paymentId
in: path
required: true
schema:
type: string
post:
operationId: createPaymentDeduction
tags: [Payments]
summary: Add a deduction to a worker payment.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: Deduction created.
/user-tokens:
post:
operationId: createUserToken
tags: [Onboarding & Sessions]
summary: Create a scoped user API token (e.g. EMPLOYER_ADMIN) for the embeddable UI.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserTokenCreate'
responses:
'201':
description: A user token.
content:
application/json:
schema:
$ref: '#/components/schemas/UserToken'
/employers/{employerId}/hosted-onboardings:
parameters:
- $ref: '#/components/parameters/EmployerId'
post:
operationId: createHostedEmployerOnboarding
tags: [Onboarding & Sessions]
summary: Create a hosted onboarding flow for an employer.
responses:
'201':
description: Hosted onboarding created.
/employers/{employerId}/mock-onboard:
parameters:
- $ref: '#/components/parameters/EmployerId'
post:
operationId: mockOnboardEmployer
tags: [Onboarding & Sessions]
summary: Simulate employer onboarding (sandbox only).
responses:
'200':
description: Employer mock-onboarded.
/employers/{employerId}/workers/mock-onboard:
parameters:
- $ref: '#/components/parameters/EmployerId'
post:
operationId: mockOnboardWorker
tags: [Onboarding & Sessions]
summary: Simulate worker onboarding (sandbox only).
responses:
'200':
description: Worker mock-onboarded.
/employers/{employerId}/taxes-setup:
parameters:
- $ref: '#/components/parameters/EmployerId'
get:
operationId: getEmployerTaxSetup
tags: [Tax]
summary: Retrieve an employer's tax setup and withholding configuration.
responses:
'200':
description: Employer tax setup.
/webhook-endpoints:
post:
operationId: createWebhookEndpoint
tags: [Webhooks]
summary: Register a webhook endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointCreate'
responses:
'201':
description: Webhook endpoint created.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
get:
operationId: listWebhookEndpoints
tags: [Webhooks]
summary: Retrieve all webhook endpoints.
responses:
'200':
description: A list of webhook endpoints.
/webhook-endpoints/{webhookEndpointId}:
parameters:
- name: webhookEndpointId
in: path
required: true
schema:
type: string
get:
operationId: getWebhookEndpoint
tags: [Webhooks]
summary: Retrieve a webhook endpoint.
responses:
'200':
description: The webhook endpoint.
patch:
operationId: updateWebhookEndpoint
tags: [Webhooks]
summary: Update a webhook endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointCreate'
responses:
'200':
description: The updated webhook endpoint.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Partner Bearer API key. Approved Salsa platform partners receive
separate sandbox and production keys. Send as
`Authorization: Bearer ${YOUR_API_TOKEN}`.
parameters:
EmployerId:
name: employerId
in: path
required: true
description: The employer (company) identifier.
schema:
type: string
WorkerId:
name: workerId
in: path
required: true
description: The worker identifier.
schema:
type: string
PayrollRunId:
name: payrollRunId
in: path
required: true
description: The payroll run identifier.
schema:
type: string
schemas:
Employer:
type: object
properties:
id:
type: string
businessName:
type: string
country:
type: string
enum: [US, CA]
onboardingStatus:
type: string
createdAt:
type: string
format: date-time
EmployerCreate:
type: object
required: [businessName, country]
properties:
businessName:
type: string
country:
type: string
enum: [US, CA]
address:
type: object
ein:
type: string
description: US Employer Identification Number (or CA business number).
Worker:
type: object
properties:
id:
type: string
employerId:
type: string
firstName:
type: string
lastName:
type: string
workerType:
type: string
enum: [EMPLOYEE, CONTRACTOR]
onboardingStatus:
type: string
WorkerCreate:
type: object
required: [firstName, lastName, workerType]
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
format: email
workerType:
type: string
enum: [EMPLOYEE, CONTRACTOR]
PayrollRun:
type: object
properties:
id:
type: string
employerId:
type: string
workerPayGroupId:
type: string
payPeriodStart:
type: string
format: date
payPeriodEnd:
type: string
format: date
payDate:
type: string
format: date
status:
type: string
PayrollRunCreate:
type: object
required: [workerPayGroupId, payPeriodStart, payPeriodEnd, payDate]
properties:
workerPayGroupId:
type: string
payPeriodStart:
type: string
format: date
payPeriodEnd:
type: string
format: date
payDate:
type: string
format: date
UserTokenCreate:
type: object
required: [employerId, role]
properties:
employerId:
type: string
role:
type: string
enum: [EMPLOYER_ADMIN, WORKER]
UserToken:
type: object
properties:
token:
type: string
role:
type: string
expiresAt:
type: string
format: date-time
WebhookEndpointCreate:
type: object
required: [url]
properties:
url:
type: string
format: uri
eventTypes:
type: array
items:
type: string
example:
- Employer.created
- Worker.created
- PayrollRun.statusChanged
- Transmission.completed
WebhookEndpoint:
type: object
properties:
id:
type: string
url:
type: string
format: uri
eventTypes:
type: array
items:
type: string
secret:
type: string
description: Signing secret used to verify webhook payloads.