Contractor rate adjustments

A rate adjustment is a contractor’s rate 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 contractor’s rate history, including future-dated changes.

• IDs. :contractorId takes the contractor’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. rate comes back as a decimal string, e.g. "800". Send it as a number.
• Scenarios. Live data only. See Scenarios.

The rate adjustment object

Endpoints

The contractor endpoints can return the same records: include=currentRate,rateHistory on List contractors. You can also create one inline with the nested rateAdjustment object on Create a contractor.

List rate adjustments

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

Permission: View Contractors (team_contractors_view) and View Detailed Financials (financials_view_detailed).

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

Example request

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

Example response

{
  "data": [
    {
      "id": "cmf2k8x1q0062ab2cd3ef4gh5",
      "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
      "liveContractorId": "cmf2k8x1q0060ab2cd3ef4gh5",
      "effectiveDate": "2026-04-01T00:00:00.000Z",
      "rateType": "daily",
      "rate": "800",
      "currencyCode": "GBP",
      "reason": "Contract renewal",
      "sourceSystem": "api",
      "sourceSystemId": null,
      "lastSyncedAt": "2026-03-20T09:00:00.000Z",
      "metadata": {},
      "createdAt": "2026-03-20T09:00:00.000Z",
      "updatedAt": "2026-03-20T09:00:00.000Z"
    },
    {
      "id": "cmf2k8x1q0063ab2cd3ef4gh5",
      "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
      "liveContractorId": "cmf2k8x1q0060ab2cd3ef4gh5",
      "effectiveDate": "2025-01-15T00:00:00.000Z",
      "rateType": "daily",
      "rate": "750",
      "currencyCode": "GBP",
      "reason": "Initial rate",
      "sourceSystem": "api",
      "sourceSystemId": null,
      "lastSyncedAt": "2025-01-10T08:00:00.000Z",
      "metadata": {},
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-01-10T08:00:00.000Z"
    }
  ]
}

Errors

Create a rate adjustment

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

Permission: Create Contractors (team_contractors_create).

Body parameters

Example request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/CTR-311/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"
  }'

Example response

201 Created.

{
  "data": {
    "id": "cmf2k8x1q0064ab2cd3ef4gh5",
    "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
    "liveContractorId": "cmf2k8x1q0060ab2cd3ef4gh5",
    "effectiveDate": "2026-10-01T00:00:00.000Z",
    "rateType": "daily",
    "rate": "850",
    "currencyCode": "GBP",
    "reason": "Scope increase",
    "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 rate adjustment

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

Permission: Update Contractors (team_contractors_update).

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

Example request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/CTR-311/rate-adjustments/cmf2k8x1q0064ab2cd3ef4gh5" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "rate": 875 }'

Errors

Delete a rate adjustment

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

Permission: Delete Contractors (team_contractors_delete).

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

Example response

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

Errors

Tasks

Change a rate from a date

POST a new adjustment with the new effectiveDate, as in Create a rate adjustment. Keep PATCH for correcting a wrong adjustment: it rewrites that period of the history.

Related

• Contractors · Errors
• Webhooks: writes send contractor_rate events. See Webhooks.