Locations API

Locations represent warehouses, depots, clinics, suppliers, and other physical or logical sites in your supply chain. The Locations API allows you to list, retrieve, and manage these entities.

List Locations

Retrieve all locations accessible in your OpenBoxes instance:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/locations"

Response

{
  "data": [
    {
      "id": "loc-001",
      "name": "Central Warehouse",
      "description": "Main distribution center",
      "locationNumber": "CW-001",
      "locationType": {
        "id": "lt-001",
        "name": "Depot",
        "description": "Distribution depot"
      },
      "locationGroup": {
        "id": "lg-001",
        "name": "Region 1"
      },
      "address": {
        "address": "123 Supply Chain Rd",
        "city": "Boston",
        "stateOrProvince": "MA",
        "postalCode": "02101",
        "country": "US"
      },
      "active": true
    },
    {
      "id": "loc-002",
      "name": "Regional Depot",
      "description": "East region distribution",
      "locationType": {
        "id": "lt-001",
        "name": "Depot"
      },
      "active": true
    }
  ]
}

Known Limitation: The max query parameter is ignored on the locations endpoint. All locations are returned regardless of the max value. Plan accordingly if your instance has many locations.

Get Location by ID

Retrieve a single location with full details:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/locations/loc-001"

Response

{
  "data": {
    "id": "loc-001",
    "name": "Central Warehouse",
    "description": "Main distribution center",
    "locationNumber": "CW-001",
    "locationType": {
      "id": "lt-001",
      "name": "Depot"
    },
    "locationGroup": {
      "id": "lg-001",
      "name": "Region 1"
    },
    "organization": {
      "id": "org-001",
      "name": "Acme Health"
    },
    "manager": {
      "id": "user-001",
      "name": "Jane Smith"
    },
    "address": {
      "address": "123 Supply Chain Rd",
      "city": "Boston",
      "stateOrProvince": "MA",
      "postalCode": "02101",
      "country": "US"
    },
    "active": true,
    "dateCreated": "2025-01-01T00:00:00Z",
    "lastUpdated": "2025-03-10T08:00:00Z"
  }
}

Known Limitation: Requesting a non-existent location ID returns HTTP 200 instead of 404. Always validate that the response contains meaningful data before processing.

Create Location

Create a new location in your instance:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/locations" \
  -d '{
    "name": "Field Clinic Alpha",
    "description": "Mobile clinic for southern region",
    "locationType": { "id": "lt-002" },
    "locationGroup": { "id": "lg-001" },
    "organization": { "id": "org-001" },
    "active": true
  }'

Required Fields

Field	Type	Description
name	string	Display name for the location
locationType	object	Location type reference with id

Optional Fields

Field	Type	Description
description	string	Description of the location
locationNumber	string	Custom identifier/code
locationGroup	object	Location group reference with id
organization	object	Parent organization with id
manager	object	Location manager (user) with id
address	object	Physical address (see fields below)
active	boolean	Whether the location is active (default: true)

Address Fields

Field	Type	Description
address	string	Street address
city	string	City name
stateOrProvince	string	State or province
postalCode	string	Postal/ZIP code
country	string	Country code (e.g., US, HT)

Update Location

Update an existing location:

curl -X PUT \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/locations/loc-003" \
  -d '{
    "name": "Field Clinic Alpha (Relocated)",
    "address": {
      "city": "Port-au-Prince",
      "country": "HT"
    }
  }'

Location Types

Location types classify locations (e.g., Depot, Ward, Supplier). Retrieve the available types via the generic API:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/locationType"

Common Location Types

Name	Description
Depot	Warehouse or distribution center
Ward	Hospital ward or clinic
Supplier	External supplier or vendor
Donor	Donation source
Bin Location	Sub-location within a warehouse
Virtual	Logical location for tracking purposes

Note: The dedicated /api/locationTypes endpoint returns 404. Use /api/generic/locationType instead.

Location Groups

Location groups organize locations into logical clusters (e.g., by region or program):

# List location groups
curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/locationGroup"

Session Context

When you authenticate, your session is bound to a specific location. Many API responses are filtered based on this location context. If you need data from a different location, you must authenticate again with that location's ID:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/login" \
  -d '{
    "username": "admin@acme.com",
    "password": "your-password",
    "location": "loc-002"
  }'

Important Notes

• Pagination not supported: The list endpoint returns all locations. For instances with hundreds of locations, expect a larger response payload.
• Non-existent IDs return 200: The get-by-ID endpoint does not return 404 for missing locations. Validate the response body before processing.
• Deactivation over deletion: Set active: false instead of deleting locations that have historical transaction data.