Salary Adjustments

Manage salary changes for employees over time. Each adjustment records a new salary amount with an effective date, building a temporal history of compensation changes.

Salary adjustments are nested under employees -- you always operate on a specific employee's adjustments.

Temporal model

Each adjustment has an effectiveDate. The most recent adjustment by date is the employee's current salary. Creating a new adjustment does not update or replace the old one -- it adds a new record to the history. This means you can backdate corrections or schedule future salary changes.

Salary Adjustment Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
employeeId	string	ID of the employee this adjustment belongs to. References an Employee.
effectiveDate	date (YYYY-MM-DD)	Date this salary takes effect. The employee's salary changes from this date onwards.
salary	number	Annual base salary. Decimal with 2 decimal places.
bonus	number | null	Annual bonus amount. Decimal with 2 decimal places. null = no bonus.
currencyCode	string	ISO 4217 currency code (e.g. "GBP", "USD", "EUR").
reason	string | null	Reason for the salary change (e.g. "Annual review", "Promotion", "Market adjustment").
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.

---

Endpoints

Method	Path	Description
GET	/org/:orgId/employees/:employeeId/salary-adjustments	List salary adjustments
POST	/org/:orgId/employees/:employeeId/salary-adjustments	Create salary adjustment
PATCH	/org/:orgId/employees/:employeeId/salary-adjustments/:id	Update salary adjustment
DELETE	/org/:orgId/employees/:employeeId/salary-adjustments/:id	Delete salary adjustment

---

List Salary Adjustments

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

Returns all salary adjustments for the specified employee, ordered by effective date (most recent first).

Example Request

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

Example Response

{
  "data": [
    {
      "id": "clx5s6a7l8r9y0j1k2l3",
      "employeeId": "clx1a2b3c4d5e6f7g8h9",
      "effectiveDate": "2026-01-01",
      "salary": 95000,
      "bonus": 10000,
      "currencyCode": "GBP",
      "reason": "Annual review",
      "createdAt": "2025-12-15T10:30:00Z",
      "updatedAt": "2025-12-15T10:30:00Z"
    },
    {
      "id": "clx3r4s5t6u7v8w9x0y1",
      "employeeId": "clx1a2b3c4d5e6f7g8h9",
      "effectiveDate": "2024-03-15",
      "salary": 85000,
      "bonus": null,
      "currencyCode": "GBP",
      "reason": "Starting salary",
      "createdAt": "2024-03-15T10:30:00Z",
      "updatedAt": "2024-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "hasNextPage": false
  }
}

Reading the history

In the example above, the employee's current salary is 95,000 GBP (effective 2026-01-01). Their starting salary was 85,000 GBP. Flowstate uses the most recent effectiveDate to determine the active salary for any given point in time.

---

Create Salary Adjustment

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

Records a new salary adjustment for the employee. This is additive -- it never overwrites existing adjustments.

Create Request Body

Field	Type	Required	Description
effectiveDate	date (YYYY-MM-DD)	Yes	Date the new salary takes effect.
salary	number	Yes	Annual base salary. Must be >= 0.
currencyCode	string	Yes	ISO 4217 currency code (3 uppercase letters, e.g. "GBP").
bonus	number | null	No	Annual bonus amount. Must be >= 0. Set null for no bonus.
reason	string | null	No	Reason for the adjustment (e.g. "Promotion to Senior Engineer").

Example Request

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

Example Response

{
  "data": {
    "id": "clx9k0l1m2n3o4p5q6r7",
    "employeeId": "clx1a2b3c4d5e6f7g8h9",
    "effectiveDate": "2026-04-01",
    "salary": 105000,
    "bonus": 12000,
    "currencyCode": "GBP",
    "reason": "Promotion to Senior Engineer",
    "createdAt": "2026-04-08T09:00:00Z",
    "updatedAt": "2026-04-08T09:00:00Z"
  }
}

Status: 201 Created

---

Update Salary Adjustment

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

Updates an existing salary adjustment. All fields are optional -- only include fields you want to change.

Update Request Body

Field	Type	Required	Description
effectiveDate	date (YYYY-MM-DD)	No	Updated effective date.
salary	number	No	Updated annual salary. Must be >= 0.
currencyCode	string	No	Updated ISO 4217 currency code.
bonus	number | null	No	Updated annual bonus. Set null to remove.
reason	string | null	No	Updated reason.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/clx1a2b3c4d5e6f7g8h9/salary-adjustments/clx9k0l1m2n3o4p5q6r7" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "salary": 108000,
    "reason": "Promotion to Senior Engineer (adjusted after benchmarking)"
  }'

---

Delete Salary Adjustment

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

Permanently removes a salary adjustment record. This cannot be undone.

WARNING

Deleting the most recent salary adjustment will change the employee's current salary to the next most recent adjustment. If there are no remaining adjustments, the employee will have no salary on record.

Status: 204 No Content

---

Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      { "field": "salary", "message": "salary must be >= 0" },
      { "field": "currencyCode", "message": "Currency code must be uppercase ISO 4217" }
    ],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Salary adjustment not found.",
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

---

Related Endpoints

• Employees -- The parent resource. You can also create salary adjustments inline when creating/updating an employee via the nested salary object.
• Recipes: Record a Salary Change -- Step-by-step guide.