Employees

Create, read, and update the people you pay.

An employee belongs to exactly one company and carries the compensation and withholding elections used when a payroll run is calculated. Employees are never deleted — terminate them instead, so prior runs and year-end documents stay intact.

GET /v1/employees

List all employees

Returns employees for a company, newest first. Results are paginated with a cursor; terminated employees are excluded unless you ask for them.

Parameters

Name Type Required Description
company_id string Yes The company to list employees for.
status string No One of active, terminated, or all. Defaults to active.
limit integer No Between 1 and 100. Defaults to 25.
starting_after string No Cursor from a previous page's last object id.

Request

curl https://api.payflo.dev/v1/employees \
  -H "Authorization: Bearer $PAYFLO_API_KEY" \
  -G -d company_id=cmp_8f2a -d limit=2

Response

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "emp_4c19",
      "first_name": "Dana",
      "last_name": "Reyes",
      "status": "active",
      "compensation": { "type": "salary", "annual_cents": 12000000 },
      "work_location": { "state": "CA" }
    }
  ]
}
POST /v1/employees

Create a new employee

Creates an employee in onboarding state. They are not included in a payroll run until required tax and payment details are complete — either supplied here or collected through self-service onboarding.

Parameters

Name Type Required Description
company_id string Yes The company this employee belongs to.
first_name string Yes Legal first name, as it appears on their Social Security card.
last_name string Yes Legal last name.
email string Yes Used for the onboarding invitation and portal access.
compensation object Yes Either { type: 'salary', annual_cents } or { type: 'hourly', rate_cents }.
work_location object Yes Where the work happens. Determines tax jurisdiction.
start_date string No ISO 8601 date. Defaults to today.

Request

curl -X POST https://api.payflo.dev/v1/employees \
  -H "Authorization: Bearer $PAYFLO_API_KEY" \
  -H "Idempotency-Key: emp-dana-reyes-001" \
  -d company_id=cmp_8f2a \
  -d first_name=Dana \
  -d last_name=Reyes \
  -d email=dana@acme.com \
  -d 'compensation[type]=salary' \
  -d 'compensation[annual_cents]=12000000' \
  -d 'work_location[state]=CA'

Response

{
  "id": "emp_4c19",
  "object": "employee",
  "status": "onboarding",
  "onboarding": {
    "w4_complete": false,
    "payment_method_complete": false,
    "i9_complete": false
  },
  "created_at": "2025-01-08T17:04:22Z"
}