Get the access codes of a booking

GET/api/v1/bookings/{booking_id}/lock-codes

Requires lock_codes.read

One entry per Lock of the booking's Property, by Lock Scope (unit, building, parking…), with its Access Window and its state. A key box gives its static_code, which does not change from one stay to the next. A smart lock gives the newest lock_code issued for this booking that is not revoked, pending included: the code is valid, the lock has not confirmed it yet. A Lock without a code for this booking is left out. A cancelled booking returns an empty list, and a revoked code is never returned.

ZenHost does not restrict when you read a code. Hand it to the guest only from the arrival day to the departure day, as Zenny does. A booking outside the Connection Scope answers not_found, exactly like a missing one.

Request

curl https://app.zenhost.com/api/v1/bookings/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7/lock-codes \
  -H "Authorization: Bearer zh_at_..."

const response = await fetch('https://app.zenhost.com/api/v1/bookings/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7/lock-codes', {
  headers: {
    Authorization: 'Bearer zh_at_...',
  },
});
const data = await response.json();

import requests

response = requests.get(
    "https://app.zenhost.com/api/v1/bookings/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7/lock-codes",
    headers={"Authorization": "Bearer zh_at_..."},
)
data = response.json()

Response

{
  "data": [
    {
      "lock_scope": "string",
      "kind": "lock_code",
      "code": "ABB",
      "valid_from": "2026-10-10T08:00:00.000Z",
      "valid_until": "2026-10-10T08:00:00.000Z",
      "status": "pending"
    }
  ]
}

{
  "error": {
    "code": "unauthorized",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "subscription_blocked",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "app_suspended",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "A human-readable explanation",
    "details": {}
  }
}

Parameters

Path parameters

booking_idstring (uuid)required
Booking id.

Responses

200The access codes of the booking.

application/jsonLockCodeList

dataLockCode[]required
One entry per Lock of the Property that has a code for this booking, the unit first. Empty for a cancelled booking.
Show 6 child attributesHide child attributes
- lock_scopestringrequired
  The area the Lock opens: one of unit, building, parking, mailbox, garage, storage, common_area, pool, garden, other. A Property has at most one Lock per scope.
- kindstringrequired
  lock_code: a code issued for this booking only. static_code: the fixed code of a key box, the same from one stay to the next.
  One of: lock_code static_code
- codestringrequired
- valid_fromstring (date-time) | nullrequired
  Start of the Access Window (operational check-in time); null for a static_code.
- valid_untilstring (date-time) | nullrequired
  End of the Access Window (operational check-out time); null for a static_code.
- statusstringrequired
  pending: the code is issued but the lock has not confirmed it yet. active: confirmed. A static_code is always active.
  One of: pending active

401Error code: unauthorized, connection_revoked.

Error codes

unauthorized The access token is missing, unknown, expired or revoked, or was issued before the account connected the App again. Refresh it; if refreshing fails, ask the owner to connect again.
connection_revoked The owner revoked the App Connection (or your App revoked its own refresh token). Stop calling for this account and drop its tokens.

402Error code: subscription_blocked.

Error codes

subscription_blocked The ZenHost subscription of the account is blocked (unpaid, cancelled…). The connection is kept: tell your customer, calls work again once the subscription is restored.

403Error code: app_suspended, forbidden_permission.

Error codes

app_suspended ZenHost suspended your App, or no longer allows it on this account. Stop calling and contact ZenHost.
forbidden_permission Your App was not granted the Permission this endpoint requires.

404Error code: not_found.

Error codes

not_found The resource does not exist or is outside the Connection Scope (both look the same), or the path is not an endpoint of /api/v1.

429Error code: rate_limited.

Header Retry-After — Seconds to wait before the next call is allowed. Limits per App Connection: 60 reads (GET), 10 writes (other POST) and 30 messages sent to guests per minute.

Error codes

rate_limited Too many calls on this App Connection. Wait for the number of seconds in Retry-After.

500Error code: internal_error.

Error codes

internal_error ZenHost failed to answer. Retry later with a back-off.

Every error code and what to do