API Reference

Business plan

Integrate CleverSlip into your workflow. Manage employees, generate payslips, and download PDFs programmatically.

Authentication

All API requests require a Bearer token. Create an API key from your dashboard, then include it in the Authorization header.

curl -X GET https://cleverslip.com/api/v1/employees \
  -H "Authorization: Bearer pslp_your_api_key"

Employees

GET/api/v1/employees

List all active employees. Supports pagination and search.

Response

{
  "data": [
    {
      "id": "clx...",
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Smith",
      "employeeId": "EMP-001",
      "department": "Engineering",
      "position": "Software Engineer",
      "salary": 85000,
      "startDate": "2024-01-15",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POST/api/v1/employees

Create a new employee. Subject to your plan's employee limit.

Request body

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "employeeId": "EMP-001",
  "department": "Engineering",
  "position": "Software Engineer",
  "salary": 85000,
  "startDate": "2024-01-15"
}

Response

{
  "data": {
    "id": "clx...",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "employeeId": "EMP-001",
    "department": "Engineering",
    "position": "Software Engineer",
    "salary": 85000,
    "startDate": "2024-01-15",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}

GET/api/v1/employees/:id

Get a single employee by ID.

Response

{
  "data": {
    "id": "clx...",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "employeeId": "EMP-001",
    "department": "Engineering",
    "position": "Software Engineer",
    "salary": 85000,
    "startDate": "2024-01-15",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}

PUT/api/v1/employees/:id

Update an employee. All fields except startDate can be modified.

Request body

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "employeeId": "EMP-001",
  "department": "Engineering",
  "position": "Senior Engineer",
  "salary": 95000
}

Response

{
  "data": {
    "id": "clx...",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "employeeId": "EMP-001",
    "department": "Engineering",
    "position": "Senior Engineer",
    "salary": 95000,
    "startDate": "2024-01-15",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}

DELETE/api/v1/employees/:id

Soft-delete an employee. Sets isActive to false and records an end date.

Response

204 No Content

Payslips

GET/api/v1/payslips

List payslips. Supports pagination, search, and filtering by employeeId.

Response

{
  "data": [
    {
      "id": "clx...",
      "employeeId": "clx...",
      "country": "US",
      "payPeriodStart": "2024-06-01",
      "payPeriodEnd": "2024-06-30",
      "grossSalary": 7083.33,
      "totalDeductions": 2125.00,
      "netSalary": 4958.33,
      "createdAt": "2024-07-01T00:00:00.000Z",
      "employee": {
        "firstName": "Jane",
        "lastName": "Smith",
        "employeeId": "EMP-001"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POST/api/v1/payslips

Create a payslip and automatically generate the PDF. Subject to plan limits.

Request body

{
  "country": "US",
  "employeeId": "clx...",
  "payPeriodStart": "2024-06-01",
  "payPeriodEnd": "2024-06-30",
  "payDate": "2024-07-05",
  "paymentMethod": "Bank Transfer",
  "earnings": {
    "baseSalary": 7083.33,
    "bonus": 500
  },
  "deductions": {
    "federalTax": 1200,
    "stateTax": 450,
    "socialSecurity": 475
  },
  "notes": "June 2024 payslip",
  "sendEmail": false
}

Response

{
  "data": {
    "id": "clx..."
  }
}

GET/api/v1/payslips/:id

Get full payslip details including all earnings, deductions, and employee info.

Response

{
  "data": {
    "id": "clx...",
    "employeeId": "clx...",
    "country": "US",
    "payPeriodStart": "2024-06-01",
    "payPeriodEnd": "2024-06-30",
    "payDate": "2024-07-05",
    "paymentMethod": "Bank Transfer",
    "earnings": [
      { "key": "baseSalary", "label": "Base Salary", "amount": 7083.33 },
      { "key": "bonus", "label": "Bonus", "amount": 500 }
    ],
    "deductions": [
      { "key": "federalTax", "label": "Federal Tax", "amount": 1200 },
      { "key": "stateTax", "label": "State Tax", "amount": 450 },
      { "key": "socialSecurity", "label": "Social Security", "amount": 475 }
    ],
    "grossSalary": 7583.33,
    "totalDeductions": 2125.00,
    "netSalary": 5458.33,
    "notes": "June 2024 payslip",
    "createdAt": "2024-07-01T00:00:00.000Z",
    "employee": {
      "firstName": "Jane",
      "lastName": "Smith",
      "employeeId": "EMP-001"
    }
  }
}

DELETE/api/v1/payslips/:id

Permanently delete a payslip and its generated PDF.

Response

204 No Content

GET/api/v1/payslips/:id/pdf

Download the payslip as a PDF file. Returns binary PDF with Content-Disposition header.

Response

Content-Type: application/pdf
Content-Disposition: attachment; filename="payslip-Jane-Smith-2024-06-01-2024-06-30.pdf"

<binary PDF data>

Pagination

List endpoints accept the following query parameters:

Parameter	Default	Description
page	1	Page number (min: 1)
limit	20	Items per page (1–100)
search	—	Filter by name, email, or employee ID (max 255 chars)
employeeId	—	Filter payslips by employee (payslips only)

GET /api/v1/employees?page=2&limit=10&search=jane

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with an error field.

Status	Description
400	Bad Request — invalid parameters or missing required fields
401	Unauthorized — invalid or missing API key
403	Forbidden — plan limit reached (employees, payslips, or feature)
404	Not Found — resource does not exist or is not accessible
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — unexpected failure, try again later

{
  "error": "Missing required field: firstName"
}

Rate Limits

API requests are rate-limited to 120 requests per minute per API key.

When the limit is exceeded, requests return 429 Too Many Requests. Wait before retrying.