Locations API

Locations represent warehouses, depots, clinics, suppliers, and other physical or logical sites in your supply chain. The Locations API is for reading them: list every location, and read one by id. Locations are created and edited in the OpenBoxes web application.

List Locations#

Retrieve all locations accessible in your OpenBoxes instance:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/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 -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/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.

Creating and editing locations#

The API documentation does not cover creating or updating a location, and you should not build an integration around either. Locations (warehouses, depots, wards, suppliers, bin locations) are created and edited in the OpenBoxes web application, under Configuration ▸ Locations. The Locations API is for reading them: list every location and read one by id, as shown above.

If an integration genuinely needs to create or update locations, raise it with support before you build. We have not verified either call on a hosted instance, so we would test it with you rather than have you discover the answer in production. It is not something a plan upgrade turns on.

Location Types#

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

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/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/v1/locationTypes endpoint returns 404. Use /api/v1/generic/locationType instead.

Location Groups#

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

# List location groups
curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/generic/locationGroup"

Location Context#

OpenBoxes filters many API responses by a "current location". When you authenticate with an API key, the connection is opened in a location chosen for the key creator's OpenBoxes user, in this order:

1. The Default location set on that user's record in OpenBoxes (Configuration ▸ Users ▸ edit the user ▸ Default location; an administrator can set it). Choosing a location after signing in does not set this: it only applies to that browser session.
2. If no Default location is set: the single depot the user holds a location role at, if there is exactly one.
3. Otherwise: the organization's only depot, if there is exactly one.

If none of those apply, for example a key creator with no Default location on an organization with several depots, the connection has no current location, and location-scoped calls such as availableItems without location.id or creating a stock movement fail. Pass an explicit location.id (or the documented location parameter) on requests that support it to scope results to a different warehouse:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products/IBU200/availableItems?location.id=loc-002"

To set or change the location for key-authenticated requests, open Configuration ▸ Users in OpenBoxes, edit the user that owns the key, and set its Default location to the warehouse the integration should work in. The change applies to new API connections within 30 minutes.

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.
• Read-only here: this page documents the list and get-by-id calls only. Create and edit locations in the OpenBoxes application (Configuration ▸ Locations).
• Deactivation over deletion: deactivate a location that has historical transaction data rather than deleting it, because deleting one breaks the history that references it.