Contractors

Manage contractor records in your organization. Contractors represent external individuals or firms engaged on a contract basis, with rate information and team/project assignments.

Endpoints

Method	Path	Description
GET	/org/:orgId/contractors	List contractors
GET	/org/:orgId/contractors/:id	Get contractor
POST	/org/:orgId/contractors	Create contractor
PATCH	/org/:orgId/contractors/:id	Update contractor
DELETE	/org/:orgId/contractors/:id	Delete contractor

---

List Contractors

GET /org/:orgId/contractors

Returns a paginated list of contractors in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Records per page (max 200)
search	string	—	Search by name or email
sortBy	string	name	Sort field
sortDir	string	asc	asc or desc
scenarioId	string	—	Scenario ID for what-if queries

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors?limit=10&sortBy=name" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx4c5d6e7f8g9h0",
      "name": "Priya Sharma",
      "email": "priya@consultingfirm.com",
      "contractorType": "individual",
      "companyId": null,
      "geographyId": "clx3g2h1j0k9",
      "rateType": "hourly",
      "rate": "150.00",
      "currencyCode": "USD",
      "startDate": "2025-01-15",
      "endDate": "2025-12-31",
      "managerId": "clx9m4n5o6p7",
      "metadata": {},
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-06-15T11:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 38,
    "hasNextPage": true
  }
}

---

Get Contractor

GET /org/:orgId/contractors/:id

Returns a single contractor by ID.

Example Request

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

Example Response

{
  "data": {
    "id": "clx4c5d6e7f8g9h0",
    "name": "Priya Sharma",
    "email": "priya@consultingfirm.com",
    "contractorType": "individual",
    "companyId": null,
    "geographyId": "clx3g2h1j0k9",
    "rateType": "hourly",
    "rate": "150.00",
    "currencyCode": "USD",
    "startDate": "2025-01-15",
    "endDate": "2025-12-31",
    "managerId": "clx9m4n5o6p7",
    "metadata": {},
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-06-15T11:30:00Z"
  }
}

---

Create Contractor

POST /org/:orgId/contractors

Creates a new contractor record.

Request Body

{
  "name": "Marcus Johnson",
  "email": "marcus@devshop.io",
  "contractorType": "individual",
  "rateType": "daily",
  "rate": "1200.00",
  "currencyCode": "GBP",
  "startDate": "2026-04-01",
  "endDate": "2026-09-30",
  "geographyId": "clx3g2h1j0k9",
  "managerId": "clx9m4n5o6p7"
}

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marcus Johnson",
    "email": "marcus@devshop.io",
    "contractorType": "individual",
    "rateType": "daily",
    "rate": "1200.00",
    "currencyCode": "GBP",
    "startDate": "2026-04-01",
    "endDate": "2026-09-30"
  }'

Example Response

{
  "data": {
    "id": "clx8p9q0r1s2t3u4",
    "name": "Marcus Johnson",
    "email": "marcus@devshop.io",
    "contractorType": "individual",
    "companyId": null,
    "geographyId": null,
    "rateType": "daily",
    "rate": "1200.00",
    "currencyCode": "GBP",
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "managerId": null,
    "metadata": {},
    "createdAt": "2026-03-11T09:00:00Z",
    "updatedAt": "2026-03-11T09:00:00Z"
  }
}

Status: 201 Created

---

Update Contractor

PATCH /org/:orgId/contractors/:id

Updates one or more fields on an existing contractor. Only include the fields you want to change.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/clx4c5d6e7f8g9h0" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rate": "175.00",
    "endDate": "2026-06-30"
  }'

Example Response

{
  "data": {
    "id": "clx4c5d6e7f8g9h0",
    "name": "Priya Sharma",
    "email": "priya@consultingfirm.com",
    "contractorType": "individual",
    "companyId": null,
    "geographyId": "clx3g2h1j0k9",
    "rateType": "hourly",
    "rate": "175.00",
    "currencyCode": "USD",
    "startDate": "2025-01-15",
    "endDate": "2026-06-30",
    "managerId": "clx9m4n5o6p7",
    "metadata": {},
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2026-03-11T09:25:00Z"
  }
}

---

Delete Contractor

DELETE /org/:orgId/contractors/:id

Deletes a contractor record. This operation is permanent for live data. In scenario mode, it creates a soft-delete tombstone.

Example Request

curl -X DELETE "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/contractors/clx4c5d6e7f8g9h0" \
  -H "Authorization: Bearer private_..."

Status: 204 No Content

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Contractor or company name
email	string	No	Contact email address
contractorType	string	Yes	Type: "individual" or "company"
companyId	string	No	Parent company contractor ID (for nested companies)
geographyId	string	No	ID of the geography/location
rateType	string	No	Rate period: "hourly", "daily", or "monthly"
rate	decimal	No	Contracted rate amount
currencyCode	string	No	ISO 4217 currency code (e.g., USD, GBP)
startDate	date	No	Contract start date (ISO 8601: YYYY-MM-DD)
endDate	date	No	Contract end date (null = ongoing)
managerId	string	No	ID of the supervising employee
metadata	object	No	Arbitrary JSON metadata (default: {})
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)