Salary adjustments

A salary adjustment is an employee’s annual salary and bonus from a given date. It applies from its effectiveDate until the next adjustment’s. Adding one never changes earlier adjustments, so the list is the employee’s pay history, including future-dated changes.

• IDs. :employeeId takes the employee’s Flowstate ID or externalId. :id takes the adjustment’s Flowstate ID.
• Dates. Send YYYY-MM-DD, which is read as 00:00 UTC, or a full ISO 8601 date-time. Dates come back as ISO 8601 date-times.
• Money. salary and bonus come back as decimal strings, e.g. "95000". Send them as numbers.
• Scenarios. Live data only. See Scenarios.

The salary adjustment object

Endpoints

The employee endpoints can return the same records: include=currentSalary,salaryHistory on List employees. You can also create one inline with the nested salary object on Create an employee.

List salary adjustments

GET /api/v1/org/:orgId/employees/:employeeId/salary-adjustments

Permission: View Employees (team_employees_view) and View Detailed Financials (financials_view_detailed).

Returns every adjustment for the employee, latest effectiveDate first. Not paginated: there is no meta.

Example request

curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/EMP-1042/salary-adjustments" \
  -H "Authorization: Bearer private_..."

Example response

{
  "data": [
    {
      "id": "cmf2k8x1q0040ab2cd3ef4gh5",
      "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
      "liveEmployeeId": "cmf2k8x1q0001ab2cd3ef4gh5",
      "effectiveDate": "2026-01-01T00:00:00.000Z",
      "salary": "95000",
      "bonus": "10000",
      "currencyCode": "GBP",
      "reason": "Annual review",
      "sourceSystem": "api",
      "sourceSystemId": null,
      "lastSyncedAt": "2025-12-15T10:30:00.000Z",
      "metadata": {},
      "createdAt": "2025-12-15T10:30:00.000Z",
      "updatedAt": "2025-12-15T10:30:00.000Z"
    },
    {
      "id": "cmf2k8x1q0042ab2cd3ef4gh5",
      "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
      "liveEmployeeId": "cmf2k8x1q0001ab2cd3ef4gh5",
      "effectiveDate": "2024-03-15T00:00:00.000Z",
      "salary": "85000",
      "bonus": null,
      "currencyCode": "GBP",
      "reason": "Starting salary",
      "sourceSystem": "api",
      "sourceSystemId": null,
      "lastSyncedAt": "2024-03-15T10:30:00.000Z",
      "metadata": {},
      "createdAt": "2024-03-15T10:30:00.000Z",
      "updatedAt": "2024-03-15T10:30:00.000Z"
    }
  ]
}

Errors

Create a salary adjustment

POST /api/v1/org/:orgId/employees/:employeeId/salary-adjustments

Permission: Create Employees (team_employees_create).

Body parameters

Example request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/EMP-1042/salary-adjustments" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "effectiveDate": "2026-10-01",
    "salary": 105000,
    "bonus": 12000,
    "currencyCode": "GBP",
    "reason": "Promotion to Staff Engineer"
  }'

Example response

201 Created.

{
  "data": {
    "id": "cmf2k8x1q0043ab2cd3ef4gh5",
    "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
    "liveEmployeeId": "cmf2k8x1q0001ab2cd3ef4gh5",
    "effectiveDate": "2026-10-01T00:00:00.000Z",
    "salary": "105000",
    "bonus": "12000",
    "currencyCode": "GBP",
    "reason": "Promotion to Staff Engineer",
    "sourceSystem": "api",
    "sourceSystemId": null,
    "lastSyncedAt": "2026-09-14T09:00:00.000Z",
    "metadata": {},
    "createdAt": "2026-09-14T09:00:00.000Z",
    "updatedAt": "2026-09-14T09:00:00.000Z"
  }
}

Errors

Update a salary adjustment

PATCH /api/v1/org/:orgId/employees/:employeeId/salary-adjustments/:id

Permission: Update Employees (team_employees_update).

Takes the create body with every field optional. null clears bonus or reason. The response is the updated adjustment, 200 OK.

Example request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/EMP-1042/salary-adjustments/cmf2k8x1q0043ab2cd3ef4gh5" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "salary": 108000 }'

Errors

Delete a salary adjustment

DELETE /api/v1/org/:orgId/employees/:employeeId/salary-adjustments/:id

Permission: Delete Employees (team_employees_delete).

Permanent. If you delete the latest adjustment, the one before it becomes the latest.

Example response

{ "data": { "id": "cmf2k8x1q0043ab2cd3ef4gh5", "deleted": true } }

Errors

Tasks

Give a pay rise from a date

POST a new adjustment with the rise’s effectiveDate, as in Create a salary adjustment. Don’t PATCH the current one: that rewrites history back to its original effectiveDate.

Correct a mistake

PATCH the wrong adjustment by :id. Take the id from List salary adjustments.

Related

• Employees · Errors
• Recipe: Record a salary change
• Webhooks: writes send salary_adjustment events. See Webhooks.