Payslips

Overview

Toku supports two payslip workflows: automatic generation after a payroll run completes, and manual upload of PDF payslips. Both produce hrisPayslip records that employees can download via presigned URLs.

Payslip Generation

When a payroll run finishes, Toku automatically generates payslips and fires a payslip.generated webhook event. Subscribe to this event to know when payslips are ready. For webhook setup, see Webhooks.

{
  "event": "payslip.generated",
  "data": {
    "hrisPayslipID": "payslip-uuid",
    "roleInOrgID": "role-uuid",
    "payslipDate": "2025-03"
  }
}

File Upload Flow

To upload an external PDF payslip, follow this three-step process. The PDF must be under 20 MB (fileSizeInBytes ≤ 20971520).

Request a presigned upload URL

Call POST /createHrisPayslipFileUpload with the file metadata. The response contains a fileID and a presigned uploadUrl for S3.

curl -X POST https://app.toku.com/api/tokuApi/v1/createHrisPayslipFileUpload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "roleInOrgID": "role-uuid",
    "fileName": "payslip-march-2025.pdf",
    "fileMimeType": "application/pdf",
    "fileSizeInBytes": 102400
  }'

Response:

{
  "fileID": "file-uuid",
  "fileName": "payslip-march-2025.pdf",
  "fileMimeType": "application/pdf",
  "fileSizeInBytes": 102400,
  "uploadUrl": "https://storage.example.com/...?X-Amz-Signature=..."
}

Save both fileID and uploadUrl — you need them in the next steps.

Upload the PDF directly to S3

PUT the raw PDF binary to the presigned uploadUrl. No Toku authorization header is needed — the presigned URL includes all required credentials.

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/pdf" \
  --data-binary @payslip-march-2025.pdf

A 200 OK response confirms the upload succeeded. If S3 returns an error, the presigned URL may have expired — request a new one from Step 1.

Call POST /createHrisPayslip with the fileID from Step 1 and the payslip financial details.

curl -X POST https://app.toku.com/api/tokuApi/v1/createHrisPayslip \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "roleInOrgID": "role-uuid",
    "fileID": "file-uuid",
    "currencyID": "SGD",
    "payslipDate": "2025-03",
    "grossAmount": 5000.00,
    "netAmount": 4200.00
  }'

Response:

{
  "hrisPayslipID": "payslip-uuid"
}

The returned hrisPayslipID is the stable identifier for this payslip record.

Retrieving Payslips

Organization-level listing

Use POST /getHrisPayslipsForOrg to list all payslips across an organization with optional filters:

Parameter	Type	Description
`search`	string?	Search by employee name or file name
`periodKey`	string?	Filter by period in `YYYY-MM` format
`department`	string?	Filter by department
`limit`	integer?	Results per page (1–200, default 10)
`offset`	integer?	Pagination offset

The response includes totalCount, a payslips[] array, and a dashboardSummary.

Employee-level listing

Use POST /getHrisPayslipsForEmployee with a roleInOrgID to retrieve all payslips for a specific employee.

Downloading Payslips

Call POST /getHrisPayslipDownloadUrl with an hrisPayslipID to get a short-lived presigned download URL:

curl -X POST https://app.toku.com/api/tokuApi/v1/getHrisPayslipDownloadUrl \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{ "hrisPayslipID": "payslip-uuid" }'

Response:

{
  "hrisPayslipID": "payslip-uuid",
  "fileID": "file-uuid",
  "fileName": "payslip-march-2025.pdf",
  "mimeType": "application/pdf",
  "downloadUrl": "https://storage.example.com/...?X-Amz-Signature=..."
}

Redirect the employee’s browser to downloadUrl or proxy it from your backend. The URL is short-lived — do not cache it.

Overview

Payslip Generation

File Upload Flow

Retrieving Payslips

Organization-level listing

Employee-level listing

Downloading Payslips

Endpoints

Create Payslip File Upload

Create Payslip

Get Payslips for Org

Get Payslips for Employee

Get Payslip Download URL

​Overview

​Payslip Generation

​File Upload Flow

​Retrieving Payslips

​Organization-level listing

​Employee-level listing

​Downloading Payslips

​Endpoints

Create Payslip File Upload

Create Payslip

Get Payslips for Org

Get Payslips for Employee

Get Payslip Download URL

Overview

Payslip Generation

File Upload Flow

Retrieving Payslips

Organization-level listing

Employee-level listing

Downloading Payslips

Endpoints