Locations

The locations resource is used to manage tenant locations.

Location object

{
  "id": "0198cf97-47e0-7930-bfa8-f480a0614068",
  "tenant": "01988bb8-1cfb-7c87-9326-93op0349288e",
  "name": "Downtown campus",
  "meta": {
    "brand_color_background": "#0e6b99",
    "brand_color_foreground": "#ffffff",
    "brand_logo": "logo-downtown-campus.svg"
  },
  "created_at": "2025-08-21 22:24:14",
  "updated_at": "2025-08-21 22:25:04"
}

Fields

id
required readonly string
Unique ID of the record.
tenant
required readonly string
Unique ID of the tenant.
name
required string
Name of the location.
meta
nullable object
Additional metadata about the location. The following keys are used by Bloom's web app:
- brand_color_background (required): Hexadecimal color code for the location's background color.
- brand_color_foreground (required): Hexadecimal color code for the location's foreground color.
- brand_logo: File name of the location's logo.
created_at
required readonly string
UTC timestamp of when the record was created.
updated_at
nullable readonly string
UTC timestamp of when the record was last updated.

Create a location

POST /tenants/{tenantId}/locations

The request body must include a location object.

The number of allowed locations is defined by the tenant's subscription

Required permissions

locations:create

Response

HTTP status	Title	Description	Schema
201	Created	Successfully created	Location object
400	Bad Request	Invalid or missing field(s)	Error object
403	Forbidden	Maximum number of allowed locations already exist	Error object
404	Not Found	Tenant not found	Error object
409	Conflict	Location name already exists for tenant	Error object

List locations

GET /tenants/{tenantId}/locations

Required permissions

locations:read

Response

HTTP status	Title	Description	Schema
200	OK		An associative array of location objects
400	Bad Request	Invalid parameters in the request query	Error object
404	Not Found	Tenant not found	Error object

Read a location

GET /tenants/{tenantId}/locations/{id}

Required permissions

locations:read

Response

HTTP status	Title	Description	Schema
200	OK		Location object
400	Bad Request	Invalid parameters in the request query	Error object
404	Not Found	Tenant or location ID not found	Error object

Update a location

PATCH /tenants/{tenantId}/locations/{id}

The request body must include parts of a location object.

Required permissions

locations:update

Response

HTTP status	Title	Description	Schema
200	OK	Updated location record	Location object
400	Bad Request	Invalid or missing field(s)	Error object
404	Not Found	Tenant or location ID not found	Error object
409	Conflict	Location name already exists for tenant	Error object

Delete a location

DELETE /tenants/{tenantId}/locations/{id}

Required permissions

locations:delete

Response

HTTP status	Title	Description	Schema
204	No content	Successfully deleted
404	Not Found	Tenant ID not found	Error object

Was this page helpful?