Run payroll

Create, calculate, approve, and complete a payroll run through the Payroll API.

Run payroll

Use this guide to process pay for a period via API. Employees must exist in HR (and be mirrored in Payroll) before you start a run.

Prerequisites

• API credentials — Authorization
• Employees in HR — Add an employee
• Payroll settings and chart of accounts configured for the company
• Permissions: payroll:runs:read, payroll:runs:write; approval may require payroll:runs:approve

Steps

1. List existing runs

   curl -sS "$FLUIDE_BASE_URL/api/v1/payroll/payroll" \
     -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
     -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
     -H "X-Fluide-Client-Id: fluide-developer" \
     -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
     -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID"
   
2. Create a payroll run

   Create a run for your target pay period. Open Create payroll run in Payroll API reference for the exact request body — fields depend on your organization’s payroll configuration.

   curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/payroll/payroll" \
     -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
     -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
     -H "X-Fluide-Client-Id: fluide-developer" \
     -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
     -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "periodStart": "2026-06-01",
       "periodEnd": "2026-06-30"
     }'
   

   Save the run id from the response.

3. Calculate and review

   Trigger calculation on the run, then fetch line items and totals. Resolve exceptions (missing payment rails, expired contracts) before approving.

   Poll the run status until calculation completes. Exact status values are documented on the run resource in the API reference.

4. Approve and complete

   If your process requires approval, call the approve endpoint with a principal holding payroll:runs:approve. Then complete or disburse per your configuration.

5. Fetch payslips

   curl -sS "$FLUIDE_BASE_URL/api/v1/payroll/payslips?payrollRunId=$RUN_ID" \
     -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
     -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
     -H "X-Fluide-Client-Id: fluide-developer" \
     -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
     -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID"
   

   Generate PDF artifacts via Utils when your integration needs downloadable payslips.

Tips

• Configure payroll GL mappings before your first production run if Books integration is enabled.
• Variable pay (bonuses, adjustments) is added on the run before calculation — see run line-item endpoints in the API reference.
• After completion, Payroll publishes events consumed by Books for journal posting.

Troubleshooting

Problem	Resolution
Employee missing from run	Confirm HR → Payroll mirror. Employee needs active contract and payment rail.
Calculation exceptions	Fetch run exception list; fix HR data and recalculate.
GL not posted after run	Check Books mappings — Payroll → Books.

Related

HR → Payroll sync

Employee mirror mechanics.

Payroll → Books

GL posting after run completion.

Payroll API reference

Full run lifecycle endpoints.