Locations

Manage geographic locations used for employee, contractor, and vacancy assignments.

Endpoints

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

---

List Locations

GET /org/:orgId/locations

Returns a paginated list of locations 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 region
sortBy	string	name	Sort field: name, countryCode, sortOrder, createdAt
sortDir	string	asc	asc or desc

Example Request

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

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2",
      "name": "London, UK",
      "countryCode": "GB",
      "region": "Europe",
      "timezone": "Europe/London",
      "defaultCurrencyCode": "GBP",
      "costMultiplier": 1.2,
      "isActive": true,
      "sortOrder": 0,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    },
    {
      "id": "clx1e2n3g4r5o0t6",
      "name": "San Francisco, US",
      "countryCode": "US",
      "region": "North America",
      "timezone": "America/Los_Angeles",
      "defaultCurrencyCode": "USD",
      "costMultiplier": 1.5,
      "isActive": true,
      "sortOrder": 1,
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 12,
    "hasNextPage": false
  }
}

---

Get Location

GET /org/:orgId/locations/:id

Returns a single location by ID.

Example Request

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

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "London, UK",
    "countryCode": "GB",
    "region": "Europe",
    "timezone": "Europe/London",
    "defaultCurrencyCode": "GBP",
    "costMultiplier": 1.2,
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2025-11-20T14:00:00Z"
  }
}

---

Create Location

POST /org/:orgId/locations

Creates a new location.

Request Body

{
  "name": "London, UK",
  "countryCode": "GB",
  "region": "Europe",
  "timezone": "Europe/London",
  "defaultCurrencyCode": "GBP",
  "costMultiplier": 1.2
}

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/locations" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "London, UK",
    "countryCode": "GB",
    "region": "Europe",
    "timezone": "Europe/London",
    "defaultCurrencyCode": "GBP",
    "costMultiplier": 1.2
  }'

Example Response

{
  "data": {
    "id": "clx3d4e5f6g7h8i9",
    "name": "London, UK",
    "countryCode": "GB",
    "region": "Europe",
    "timezone": "Europe/London",
    "defaultCurrencyCode": "GBP",
    "costMultiplier": 1.2,
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2026-03-11T09:40:00Z",
    "updatedAt": "2026-03-11T09:40:00Z"
  }
}

Status: 201 Created

---

Update Location

PATCH /org/:orgId/locations/:id

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

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/locations/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "costMultiplier": 1.25,
    "name": "London (City), UK"
  }'

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "London (City), UK",
    "countryCode": "GB",
    "region": "Europe",
    "timezone": "Europe/London",
    "defaultCurrencyCode": "GBP",
    "costMultiplier": 1.25,
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2026-03-11T09:45:00Z"
  }
}

---

Delete Location

DELETE /org/:orgId/locations/:id

Deletes a location. Locations that are actively assigned to employees, contractors, or vacancies cannot be deleted until those references are removed.

Example Request

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

Example Response

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

Status: 200 OK

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Location name (e.g., "London, UK")
countryCode	string	No	2-character ISO 3166-1 country code (e.g., "GB")
region	string	No	Geographic region (e.g., "Europe", "North America")
timezone	string	No	IANA timezone identifier (e.g., "Europe/London")
defaultCurrencyCode	string	No	3-character ISO 4217 currency code (e.g., "GBP")
costMultiplier	number	No	Location-based cost adjustment factor (default: 1.0)
isActive	boolean	No	Whether the location is active (default: true)
sortOrder	integer	No	Display sort order (default: 0)
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)