Locations

Manage physical locations (stores, branches, points of sale) for your tenant. Devices and employees are assigned to locations for reporting and access control.

GET/api/v1/locations

List all locations for your tenant. Supports filtering, sorting, and pagination.

Headers

Name	Type	Required	Description
Authorization	string	Required	Bearer <access_token> — requires locations:read scope

AuthorizationstringRequired

Bearer <access_token> — requires locations:read scope

Query Parameters

Name	Type	Required	Description
name	string	Optional	Filter by location name (substring match)
externalId	string	Optional	Filter by your own external identifier
sortBy	string	Optional	"name" \| "createdAt" \| "updatedAt"
sortOrder	string	Optional	"asc" \| "desc"
limit	number	Optional	Page size. When provided, the response includes nextCursor and hasMore
cursor	string	Optional	Pagination cursor from a previous response

namestringOptional

Filter by location name (substring match)

externalIdstringOptional

Filter by your own external identifier

sortBystringOptional

"name" | "createdAt" | "updatedAt"

sortOrderstringOptional

"asc" | "desc"

limitnumberOptional

Page size. When provided, the response includes nextCursor and hasMore

cursorstringOptional

Pagination cursor from a previous response

Response

{
  "data": [
    {
      "id": "loc_abc123",
      "name": "Flagship Store",
      "address": "Laugavegur 1",
      "address2": null,
      "city": "Reykjavík",
      "postcode": "101",
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ]
}

GET/api/v1/locations/:id

Retrieve a single location by ID.

Headers

Name	Type	Required	Description
Authorization	string	Required	Bearer <access_token> — requires locations:read scope

AuthorizationstringRequired

Bearer <access_token> — requires locations:read scope

Response

{
  "data": {
    "id": "loc_abc123",
    "name": "Flagship Store",
    "address": "Laugavegur 1",
    "address2": null,
    "city": "Reykjavík",
    "postcode": "101",
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

POST/api/v1/locations

Create a new location. Returns the created location.

Headers

Name	Type	Required	Description
Authorization	string	Required	Bearer <access_token> — requires locations:write scope
Content-Type	string	Required	application/json

AuthorizationstringRequired

Bearer <access_token> — requires locations:write scope

Content-TypestringRequired

application/json

Request Body

Name	Type	Required	Description
name	string	Required	Display name for the location
address	string	Required	Street address
address2	string	Optional	Second address line (floor, unit, etc.)
city	string	Required	City
postcode	string	Required	Postal code

namestringRequired

Display name for the location

addressstringRequired

Street address

address2stringOptional

Second address line (floor, unit, etc.)

citystringRequired

City

postcodestringRequired

Postal code

Response

// 201 Created
{
  "data": {
    "id": "loc_abc123",
    "name": "Flagship Store",
    "address": "Laugavegur 1",
    "city": "Reykjavík",
    "postcode": "101",
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

DELETE/api/v1/locations/:id

Delete a location. Also unassigns all devices associated with that location.

Headers

Name	Type	Required	Description
Authorization	string	Required	Bearer <access_token> — requires locations:write scope

AuthorizationstringRequired

Bearer <access_token> — requires locations:write scope

Response

{ "deleted": true }