Locations

Manage geographic locations used for employee, contractor, and vacancy assignments. Locations define where people work and carry defaults for currency and cost calculations.

Location Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
name	string	Location name (e.g. "London, UK", "San Francisco, US").
countryCode	string | null	2-character ISO 3166-1 country code (e.g. "GB", "US").
region	string | null	Geographic region (e.g. "Europe", "North America").
timezone	string | null	IANA timezone identifier (e.g. "Europe/London", "America/Los_Angeles").
defaultCurrencyCode	string | null	ISO 4217 currency code (e.g. "GBP"). Employees assigned to this location inherit this currency unless overridden.
costMultiplier	number | null	Location-based cost adjustment factor (e.g. 1.2 = 20% above baseline). Used in cost forecasting.
isActive	boolean	Whether this location is active.
sortOrder	integer	Display ordering weight. Lower values appear first.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.

---

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

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based).
limit	integer	20	Records per page. Min 1, max 100.
search	string	--	Free-text search by name or region.
sortBy	string	name	Field to sort by: 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" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2z3a4",
      "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": "clx1e2n3g4r5o0t6u7v8",
      "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": 20,
    "total": 12,
    "hasNextPage": false
  }
}

---

Create Location

POST /org/:orgId/locations

Create Request Body

Field	Type	Required	Description
name	string	Yes	Location name.
countryCode	string | null	No	2-character ISO 3166-1 country code.
region	string | null	No	Geographic region.
timezone	string | null	No	IANA timezone identifier.
defaultCurrencyCode	string | null	No	ISO 4217 currency code (3 characters).
costMultiplier	number	No	Cost adjustment factor. Must be positive.
isActive	boolean	No	Default: true.
sortOrder	integer	No	Display ordering. Default: 0.

Update Request Body

All fields from Create are accepted, all optional.

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": "Berlin, DE",
    "countryCode": "DE",
    "region": "Europe",
    "timezone": "Europe/Berlin",
    "defaultCurrencyCode": "EUR",
    "costMultiplier": 1.1
  }'

Status: 201 Created

---

Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [{ "field": "name", "message": "name is required" }],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Location not found.",
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

---

Related Endpoints

• Employees -- Employees reference locations via geographyId.
• Contractors -- Contractors reference locations via geographyId.
• Vacancies -- Vacancies reference locations via geographyId.
• Exchange Rates -- Convert between location currencies.