How to Automate Payslip Generation with an API

Most payroll teams generate payslips the same way every month: export from the HR system, open a separate tool, input numbers, generate PDFs, download, email one by one.

It works. But it's the kind of repetitive process that only exists because two systems don't talk to each other.

An API bridges that gap. Your payroll system already knows every employee's salary, deductions, and tax details. Let it generate the payslips automatically.

---

Before and After

	Manual	With API
Time per run (50 employees)	2–4 hours	0 minutes
Human intervention	Every step	None
Consistency	Varies by person	Same every time
Error rate	Copy-paste mistakes	Validation-level errors only

---

How It Works

Three steps: authenticate, send payroll data, get back a PDF.

Authentication

API key as Bearer token:

Authorization: Bearer cs_live_your_key_here

Never put API keys in client-side code, source repositories, or plain-text configs. Environment variables only. Rotate every 90 days.

---

Create an Employee

curl -X POST https://cleverslip.com/api/v1/employees \
  -H "Authorization: Bearer $CLEVERSLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "[email protected]",
    "employeeId": "EMP-042",
    "position": "Software Engineer",
    "department": "Engineering"
  }'

You'll get back an internal ID (emp_abc123) for subsequent calls.

---

Generate a Payslip

Send earnings and deductions, get back the calculated result:

curl -X POST https://cleverslip.com/api/v1/payslips \
  -H "Authorization: Bearer $CLEVERSLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "emp_abc123",
    "payPeriod": {
      "startDate": "2026-02-01",
      "endDate": "2026-02-28"
    },
    "earnings": [
      { "label": "Base Salary", "amount": 5000 },
      { "label": "Performance Bonus", "amount": 750 }
    ],
    "deductions": [
      { "label": "Federal Income Tax", "amount": 890 },
      { "label": "Social Security", "amount": 356.50 },
      { "label": "Medicare", "amount": 83.38 },
      { "label": "401(k)", "amount": 300 },
      { "label": "Health Insurance", "amount": 200 }
    ],
    "currency": "USD",
    "country": "US"
  }'

Response:

{
  "id": "ps_xyz789",
  "grossPay": 5750.00,
  "totalDeductions": 1829.88,
  "netPay": 3920.12,
  "status": "generated",
  "pdfUrl": "/api/v1/payslips/ps_xyz789/pdf"
}

The country field determines the template — a US payslip looks different from a German Entgeltabrechnung or a French bulletin de paie.

---

Download the PDF

curl -X GET https://cleverslip.com/api/v1/payslips/ps_xyz789/pdf \
  -H "Authorization: Bearer $CLEVERSLIP_API_KEY" \
  -o payslip-jane-feb-2026.pdf

---

Error Handling

Code	What It Means	What to Do
400	Bad request data	Check the error message — missing field or invalid format
401	Auth failed	Verify your API key
404	Not found	Check employee or payslip ID
429	Rate limited	Wait, retry with exponential backoff
500	Server error	Retry after short delay

Sanity check: verify that netPay equals grossPay - totalDeductions in every response. If it doesn't, flag for review rather than sending the payslip.

---

Rate Limits

Plan	Limit
Starter	30 req/min
Pro	60 req/min
Business	120 req/min

Even at 120/min, you process 120 employees in under a minute. For larger batches, add a 500ms delay between calls and track progress to resume if something fails mid-run.

---

Integration Patterns

Cron Job

The simplest approach. A scheduled script runs on payday:

1. Pull payroll data from your HR database
2. Loop through employees, make API calls
3. Log errors, alert on failures

Works well for fixed-schedule payroll.

Webhook-Driven

HR manager clicks "Approve Payroll" → your system fires a webhook → integration server calls the payslip API for each employee.

More responsive than a cron job. Ties generation to the actual approval workflow.

ERP Integration

SAP / Oracle / Dynamics calculates salaries and taxes. A middleware layer maps ERP data to the API format. Each system does what it's best at.

---

Security Checklist

Always use HTTPS	API rejects plain HTTP
Minimise stored data	Pass data to API, store only payslip IDs
Audit API usage	Log every call — who, when, success/failure
Separate environments	Different keys for dev and production
Use test data in dev	Never real salaries in development

---

Get Started

Full API documentation — all endpoints, schemas, and error codes — is at /docs/api.

Get your API key →