Payroll

Create, inspect, and approve payroll runs.

A payroll run covers one pay period for one pay schedule. Runs are created in draft, recalculate on every change, and become immutable once approved. Approving a run authorizes a debit, so send an Idempotency-Key on every write.

GET /v1/payroll/runs

List all payroll runs

Returns payroll runs for a company, most recent pay period first. Filter by status to find what still needs approval.

Parameters

Name	Type	Required	Description
`company_id`	string	Yes	The company to list runs for.
`status`	string	No	draft, pending_approval, submitted, settled, or reversed.
`pay_date_after`	string	No	ISO 8601 date. Only runs paid on or after this date.
`limit`	integer	No	Between 1 and 100. Defaults to 25.

Request

curl https://api.payflo.dev/v1/payroll/runs \
  -H "Authorization: Bearer $PAYFLO_API_KEY" \
  -G -d company_id=cmp_8f2a -d status=pending_approval

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "pr_91be",
      "status": "pending_approval",
      "pay_period_start": "2025-01-01",
      "pay_period_end": "2025-01-15",
      "pay_date": "2025-01-20",
      "totals": {
        "gross_cents": 48200000,
        "employee_taxes_cents": 11568000,
        "employer_taxes_cents": 3687300,
        "debit_cents": 40319300
      }
    }
  ]
}

POST /v1/payroll/runs

Create a new payroll run

Opens a draft run for a pay period. Salaried employees are populated at their standard rate; hourly employees need hours before the run can be approved. Creating a run does not move money.

Parameters

Name	Type	Required	Description
`company_id`	string	Yes	The company to run payroll for.
`pay_period_start`	string	Yes	ISO 8601 date, inclusive.
`pay_period_end`	string	Yes	ISO 8601 date, inclusive.
`pay_date`	string	No	Defaults to the next pay date on the schedule.
`type`	string	No	regular or off_cycle. Defaults to regular.
`employee_ids`	array	No	Limits an off-cycle run to specific employees.

Request

curl -X POST https://api.payflo.dev/v1/payroll/runs \
  -H "Authorization: Bearer $PAYFLO_API_KEY" \
  -H "Idempotency-Key: run-2025-01-15-acme" \
  -d company_id=cmp_8f2a \
  -d pay_period_start=2025-01-01 \
  -d pay_period_end=2025-01-15

Response

{
  "id": "pr_91be",
  "object": "payroll_run",
  "status": "draft",
  "approval_deadline": "2025-01-16T19:00:00Z",
  "blocking_issues": [
    {
      "code": "missing_hours",
      "employee_id": "emp_77a2",
      "message": "Hourly employee has no hours for this period."
    }
  ]
}