Release a locker compartment via API

Parcel lockers and mailroom matrices release one compartment at a time when a recipient or courier is authorized. In OpenApp each compartment is modeled as a switchable entity — the same switchable.open action used for doors and gates.

This guide is for campus mail services, corporate mailrooms, and parcel-wall operators automating pickup. See Model by sector (locker / parcel matrix).

Model

1. One integration + devices represent the locker bank (or one device per compartment).
2. Each compartment is an entity with a human-readable name in metadata.
3. Classify each compartment’s device. For a switch compartment entity, Not an access opening (locker, light) is enough; a door entity must use an access opening class and attestation. Until the device is classified, opens return 409 life_safety_class_required.
4. Your app validates a pickup code, then calls switchable.open on that entity only.

Release one compartment

SDK

Python

await client.entities.actions(entity_id, "switchable.open")

TypeScript

const res = await fetch(
  `${apiBase}/entities/${entityId}/actions/switchable.open`,
  {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
      "content-type": "application/json",
      "x-org": orgId,
    },
    body: JSON.stringify({}),
  },
);
if (!res.ok) throw new Error(`open failed: ${res.status}`);

Rust

use openapp_sdk::Client;
use serde_json::json;

let client = Client::builder()
    .api_key("https://openapp.house_openapp_YOUR_SECRET")
    .build()?;

client
    .entities()
    .invoke_action(entity_id, "switchable.open", &json!({}))
    .await?;

Go

httpResp, err := client.EntitiesAPI.ExecuteEntityAction(ctx, entityID, "switchable.open").
    Body(map[string]interface{}{}).
    Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()

HTTP API (curl)

Prefer the SDK

Official SDKs handle authentication, base URLs, org headers, and typed request bodies — fewer moving parts than assembling raw HTTP. Use curl or JSON-over-HTTP when you need a minimal dependency, are generating a client from OpenAPI, or are proving connectivity before adding an SDK. See the SDK overview.

export OPENAPP_API_BASE='https://openapp.house/api/v1'
export OPENAPP_API_KEY='https://openapp.house_openapp_YOUR_SECRET'
export OPENAPP_ORG_ID='01HORG00000000000000000000'
export COMPARTMENT_ENTITY_ID='01HENTITY000000000000000000'

curl -sS -X POST \
  -H "X-API-Key: ${OPENAPP_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Org: ${OPENAPP_ORG_ID}" \
  -d '{}' \
  "${OPENAPP_API_BASE}/entities/${COMPARTMENT_ENTITY_ID}/actions/switchable.open"

Discover compartment entities

SDK

Python

rows = await client.integrations.entities(integration_id)

TypeScript

const url = new URL(
  `${apiBase}/integrations/${integrationId}/entities`,
);
url.searchParams.set("limit", "100");
url.searchParams.set("offset", "0");

const page = await fetch(url, {
  headers: {
    "x-api-key": apiKey,
    "x-org": orgId,
  },
}).then((r) => r.json());

Rust

use openapp_sdk::Client;

let client = Client::builder()
    .api_key("https://openapp.house_openapp_YOUR_SECRET")
    .build()?;

let rows = client.integrations().entities(integration_id).await?;

Go

page, httpResp, err := client.IntegrationsAPI.ListIntegrationEntities(ctx, integrationID).
    XOrg(orgID).
    OutputOptions(*openapiclient.NewMultiResourceOutputOptionsQuery()).
    Pagination(openapiclient.PaginationQuery{
        Limit:  openapiclient.PtrInt32(100),
        Offset: openapiclient.PtrInt32(0),
    }).
    Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()
_ = page

HTTP API (curl)

Prefer the SDK

Official SDKs handle authentication, base URLs, org headers, and typed request bodies — fewer moving parts than assembling raw HTTP. Use curl or JSON-over-HTTP when you need a minimal dependency, are generating a client from OpenAPI, or are proving connectivity before adding an SDK. See the SDK overview.

export INTEGRATION_ID='01HINTEGRATION00000000000000'

curl -sS \
  -H "X-API-Key: ${OPENAPP_API_KEY}" \
  -H "X-Org: ${OPENAPP_ORG_ID}" \
  "${OPENAPP_API_BASE}/integrations/${INTEGRATION_ID}/entities?limit=100&offset=0"

Map external ids (compartment numbers) to entity ids during provisioning — provision a building with scripting for bulk setup.

Safety

• Never open by numeric guess — resolve entity id from your parcel system’s authoritative mapping.
• Rate-limit automated release endpoints exposed to couriers.
• Each release is audited as entity.action.succeeded / entity.action.denied; keep the correlation id from failures to join your logs to it (audit activity).

---

← Query audit activity · Provision with scripting →