Vacancies

Manage open positions and the hiring pipeline. Vacancies represent roles that need to be filled, with target dates, salary ranges, and team assignments.

Endpoints

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

---

List Vacancies

GET /org/:orgId/vacancies

Returns a paginated list of vacancies 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 role or description
sortBy	string	role	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}/vacancies?sortBy=targetStartDate&sortDir=asc" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx5v6w7x8y9z0a1",
      "role": "Senior Backend Engineer",
      "description": "Backend engineer for the payments team, focusing on billing infrastructure.",
      "status": "open",
      "fte": 1.0,
      "targetStartDate": "2026-06-01",
      "targetFillDate": "2026-05-15",
      "jobRoleId": "clx9r8q7w6e5",
      "workTypeId": "clx2w3x4y5z6",
      "geographyId": "clx3g2h1j0k9",
      "salaryMin": "120000.00",
      "salaryMax": "160000.00",
      "currencyCode": "USD",
      "filledByLiveEmployeeId": null,
      "hiringManagerId": "clx9m4n5o6p7",
      "metadata": {},
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-01T16:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 23,
    "hasNextPage": true
  }
}

---

Get Vacancy

GET /org/:orgId/vacancies/:id

Returns a single vacancy by ID.

Example Request

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

Example Response

{
  "data": {
    "id": "clx5v6w7x8y9z0a1",
    "role": "Senior Backend Engineer",
    "description": "Backend engineer for the payments team, focusing on billing infrastructure.",
    "status": "open",
    "fte": 1.0,
    "targetStartDate": "2026-06-01",
    "targetFillDate": "2026-05-15",
    "jobRoleId": "clx9r8q7w6e5",
    "workTypeId": "clx2w3x4y5z6",
    "geographyId": "clx3g2h1j0k9",
    "salaryMin": "120000.00",
    "salaryMax": "160000.00",
    "currencyCode": "USD",
    "filledByLiveEmployeeId": null,
    "hiringManagerId": "clx9m4n5o6p7",
    "metadata": {},
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-03-01T16:45:00Z"
  }
}

---

Create Vacancy

POST /org/:orgId/vacancies

Creates a new vacancy record.

Request Body

{
  "role": "DevOps Engineer",
  "description": "Cloud infrastructure engineer to support the platform team.",
  "status": "open",
  "fte": 1.0,
  "targetStartDate": "2026-09-01",
  "targetFillDate": "2026-08-15",
  "jobRoleId": "clx9r8q7w6e5",
  "workTypeId": "clx2w3x4y5z6",
  "geographyId": "clx3g2h1j0k9",
  "salaryMin": "110000.00",
  "salaryMax": "145000.00",
  "currencyCode": "USD",
  "hiringManagerId": "clx9m4n5o6p7"
}

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/vacancies" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "role": "DevOps Engineer",
    "description": "Cloud infrastructure engineer to support the platform team.",
    "status": "open",
    "fte": 1.0,
    "targetStartDate": "2026-09-01",
    "salaryMin": "110000.00",
    "salaryMax": "145000.00",
    "currencyCode": "USD"
  }'

Example Response

{
  "data": {
    "id": "clx2b3c4d5e6f7g8",
    "role": "DevOps Engineer",
    "description": "Cloud infrastructure engineer to support the platform team.",
    "status": "open",
    "fte": 1.0,
    "targetStartDate": "2026-09-01",
    "targetFillDate": null,
    "jobRoleId": null,
    "workTypeId": null,
    "geographyId": null,
    "salaryMin": "110000.00",
    "salaryMax": "145000.00",
    "currencyCode": "USD",
    "filledByLiveEmployeeId": null,
    "hiringManagerId": null,
    "metadata": {},
    "createdAt": "2026-03-11T09:30:00Z",
    "updatedAt": "2026-03-11T09:30:00Z"
  }
}

Status: 201 Created

---

Update Vacancy

PATCH /org/:orgId/vacancies/:id

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

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/vacancies/clx5v6w7x8y9z0a1" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "filled",
    "filledByLiveEmployeeId": "clx7n8m9k0j1h2g3"
  }'

Example Response

{
  "data": {
    "id": "clx5v6w7x8y9z0a1",
    "role": "Senior Backend Engineer",
    "description": "Backend engineer for the payments team, focusing on billing infrastructure.",
    "status": "filled",
    "fte": 1.0,
    "targetStartDate": "2026-06-01",
    "targetFillDate": "2026-05-15",
    "jobRoleId": "clx9r8q7w6e5",
    "workTypeId": "clx2w3x4y5z6",
    "geographyId": "clx3g2h1j0k9",
    "salaryMin": "120000.00",
    "salaryMax": "160000.00",
    "currencyCode": "USD",
    "filledByLiveEmployeeId": "clx7n8m9k0j1h2g3",
    "hiringManagerId": "clx9m4n5o6p7",
    "metadata": {},
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-03-11T09:35:00Z"
  }
}

---

Delete Vacancy

DELETE /org/:orgId/vacancies/:id

Deletes a vacancy record.

Example Request

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

Status: 204 No Content

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
role	string	Yes	Job title or role name
description	string	No	Description of the position
status	string	Yes	Status: "open", "filled", "cancelled", "on_hold"
fte	number	No	Full-time equivalent (default: 1.0)
targetStartDate	date	No	When the hire should start (ISO 8601)
targetFillDate	date	No	When the position should be filled by
jobRoleId	string	No	ID of the job role
workTypeId	string	No	ID of the work type
geographyId	string	No	ID of the geography/location
salaryMin	decimal	No	Minimum salary for the role
salaryMax	decimal	No	Maximum salary for the role
currencyCode	string	No	ISO 4217 currency code (e.g., USD, GBP)
filledByLiveEmployeeId	string	No	ID of the employee who filled this vacancy
hiringManagerId	string	No	ID of the hiring manager (employee ID)
metadata	object	No	Arbitrary JSON metadata (default: {})
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)