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 -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.

Create Location#

Create a new location in your instance:

curl -X POST \
  -H "X-API-Key: $OB_API_KEY" \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/api/v1/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 \
  -H "X-API-Key: $OB_API_KEY" \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/api/v1/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 -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 owner's OpenBoxes user, in this order:

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.
If no Default location is set: the single depot the user holds a location role at, if there is exactly one.
Otherwise: the organization's only depot, if there is exactly one.

If none of those apply, for example a key owner 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.
Deactivation over deletion: Set active: false instead of deleting locations that have historical transaction data.