Appearance

Contractor Rate Adjustments ​

Manage rate changes for contractors over time. Each adjustment records a new billing rate with an effective date, supporting hourly, daily, or monthly rate types.

Rate adjustments are nested under contractors -- you always operate on a specific contractor's adjustments.

Temporal model

Each adjustment has an effectiveDate. The most recent adjustment by date determines the contractor's current rate. 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 rate changes.

Rate Adjustment Object ​

FieldTypeDescription
idstringUnique identifier (CUID format). System-generated. Read-only.
contractorIdstringID of the contractor this adjustment belongs to. References a Contractor.
effectiveDatedate (YYYY-MM-DD)Date this rate takes effect. The contractor's rate changes from this date onwards.
rateTypestringBilling rate period: "hourly", "daily", or "monthly".
ratenumberRate amount in the specified currency. Decimal with 2 decimal places.
currencyCodestringISO 4217 currency code (e.g. "GBP", "USD", "EUR").
reasonstring | nullReason for the rate change (e.g. "Contract renewal", "Scope increase").
createdAtdatetime (ISO 8601)When the record was created. Read-only.
updatedAtdatetime (ISO 8601)When the record was last modified. Read-only.

Endpoints ​

MethodPathDescription
GET/org/:orgId/contractors/:contractorId/rate-adjustmentsList rate adjustments
POST/org/:orgId/contractors/:contractorId/rate-adjustmentsCreate rate adjustment
PATCH/org/:orgId/contractors/:contractorId/rate-adjustments/:idUpdate rate adjustment
DELETE/org/:orgId/contractors/:contractorId/rate-adjustments/:idDelete rate adjustment

List Rate Adjustments ​

GET /org/:orgId/contractors/:contractorId/rate-adjustments

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

Example Request ​

bash
curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/clx4c5d6e7f8g9h0i1j2/rate-adjustments" \
  -H "Authorization: Bearer private_..."

Example Response ​

json
{
  "data": [
    {
      "id": "clx7r8s9t0u1v2w3x4y5",
      "contractorId": "clx4c5d6e7f8g9h0i1j2",
      "effectiveDate": "2026-04-01",
      "rateType": "daily",
      "rate": 800,
      "currencyCode": "GBP",
      "reason": "Contract renewal",
      "createdAt": "2026-03-20T09:00:00Z",
      "updatedAt": "2026-03-20T09:00:00Z"
    },
    {
      "id": "clx3a4b5c6d7e8f9g0h1",
      "contractorId": "clx4c5d6e7f8g9h0i1j2",
      "effectiveDate": "2025-01-15",
      "rateType": "daily",
      "rate": 750,
      "currencyCode": "GBP",
      "reason": "Initial engagement rate",
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-01-10T08:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "hasNextPage": false
  }
}

Create Rate Adjustment ​

POST /org/:orgId/contractors/:contractorId/rate-adjustments

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

Create Request Body ​

FieldTypeRequiredDescription
effectiveDatedate (YYYY-MM-DD)YesDate the new rate takes effect.
rateTypestringYesBilling period: "hourly", "daily", or "monthly".
ratenumberYesRate amount. Must be >= 0.
currencyCodestringYesISO 4217 currency code (3 uppercase letters, e.g. "GBP").
reasonstring | nullNoReason for the rate change.

Example Request ​

bash
curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/clx4c5d6e7f8g9h0i1j2/rate-adjustments" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "effectiveDate": "2026-10-01",
    "rateType": "daily",
    "rate": 850,
    "currencyCode": "GBP",
    "reason": "Scope increase for Q4 deliverables"
  }'

Example Response ​

json
{
  "data": {
    "id": "clx9k0l1m2n3o4p5q6r7",
    "contractorId": "clx4c5d6e7f8g9h0i1j2",
    "effectiveDate": "2026-10-01",
    "rateType": "daily",
    "rate": 850,
    "currencyCode": "GBP",
    "reason": "Scope increase for Q4 deliverables",
    "createdAt": "2026-04-08T09:00:00Z",
    "updatedAt": "2026-04-08T09:00:00Z"
  }
}

Status: 201 Created

Update Rate Adjustment ​

PATCH /org/:orgId/contractors/:contractorId/rate-adjustments/:id

Updates an existing rate adjustment. All fields are optional.

Update Request Body ​

FieldTypeRequiredDescription
effectiveDatedate (YYYY-MM-DD)NoUpdated effective date.
rateTypestringNoUpdated billing period: "hourly", "daily", or "monthly".
ratenumberNoUpdated rate amount. Must be >= 0.
currencyCodestringNoUpdated ISO 4217 currency code.
reasonstring | nullNoUpdated reason.

Example Request ​

bash
curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/clx4c5d6e7f8g9h0i1j2/rate-adjustments/clx9k0l1m2n3o4p5q6r7" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rate": 875,
    "reason": "Scope increase for Q4 deliverables (renegotiated)"
  }'

Delete Rate Adjustment ​

DELETE /org/:orgId/contractors/:contractorId/rate-adjustments/:id

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

WARNING

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

Status: 204 No Content

Error Responses ​

Validation Error (400) ​

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      { "field": "rateType", "message": "rateType must be one of: hourly, daily, monthly" }
    ],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404) ​

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

Flowstate Documentation

Copyright 2026 Flowstate.