Build on HomingBird

A public REST API for hotel Lost & Found. Read and register found items from your PMS, guest-experience app or housekeeping tool. Each API key is scoped to a single hotel.

Get started

1. Create an API key
In HomingBird go to Admin → API keys and create a key with the scopes you need: read and/or ingest. The full key (hb_live_…) is shown once — store it safely.
2. Base URL & auth
Send your key as a bearer token. The key already identifies the hotel — no hotel id needed.
```
Base URL:  https://gethomingbird.com/v1
Header:    Authorization: Bearer hb_live_xxxxxxxx
```

3. Make your first call

curl https://gethomingbird.com/v1/items \
  -H "Authorization: Bearer hb_live_xxxxxxxx"

Endpoints

GET/v1/items

List the hotel's found items, newest first. Scope: read. Optional query params:limitstatusfound_room.

curl "https://gethomingbird.com/v1/items?status=found&limit=20" \
  -H "Authorization: Bearer hb_live_xxxxxxxx"

{
  "items": [
    { "id": "…", "title": "Black sunglasses", "category": "accessories",
      "colors": ["black"], "status": "found",
      "found_at": "2026-07-20T09:12:00Z", "found_room": "214" }
  ]
}

GET/v1/items/{id}

Fetch one item. Scope: read. Returns 404 if the item is not in your hotel.

curl https://gethomingbird.com/v1/items/ITEM_ID \
  -H "Authorization: Bearer hb_live_xxxxxxxx"

POST/v1/items

curl -X POST https://gethomingbird.com/v1/items \
  -H "Authorization: Bearer hb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Gold ring","category":"jewellery","found_room":"214"}'

{ "item": { "id": "…", "status": "found" } }

Reservations

Sync reservations from your PMS and power a guest-experience check-out prompt.

POST/v1/reservations

Upsert a reservation (keyed on your PMS external_id). Scope: ingest.

curl -X POST https://gethomingbird.com/v1/reservations \
  -H "Authorization: Bearer hb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"BKG-1029","room":"214",
       "guest_email":"a@guest.com",
       "check_in":"2026-07-01","check_out":"2026-07-05",
       "status":"checked_out"}'

GET/v1/reservations

List reservations. Scope: read. Filters: status, room, limit.

GET/v1/reservations/{external_id}/items

“Did the guest leave something?”

Returns items found in the guest's room during their stay (up to 2 days after check-out, for post-checkout cleaning) and still unclaimed. Perfect for a check-out prompt in your guest app. Scope: read.

curl https://gethomingbird.com/v1/reservations/BKG-1029/items \
  -H "Authorization: Bearer hb_live_xxxxxxxx"

{
  "reservation": { "external_id": "BKG-1029", "room": "214",
                   "check_in": "2026-07-01", "check_out": "2026-07-05" },
  "items": [ { "id": "…", "title": "Phone charger", "status": "found",
               "found_room": "214", "found_at": "2026-07-04T10:00:00Z" } ],
  "count": 1
}

Webhooks

Get pushed events instead of polling. Register an HTTPS endpoint and subscribe to the events you care about.

Events

item.found — a new item was registered
item.status_changed — status changed (stored, released, shipped…)
claim.created — a guest submitted a claim
claim.approved — staff approved a claim

Verify the signature

Every request carries HomingBird-Signature: t=<ts>,v1=<hmac>. RecomputeHMAC_SHA256(secret, "{ts}.{raw_body}")and compare. Reject if it doesn't match or the timestamp is old. Failed deliveries retry with exponential backoff (up to 5 attempts).

Register an endpoint with the create_webhook_endpoint RPC (owner/manager) — the signing secretwhsec_… is returned once (an Admin → Webhooks UI is coming). Point it at thewebhook-echo tester first to inspect exactly what we send.

Rate limits

120 requests per minute per key. Responses include X-RateLimit-Limit; on 429 a Retry-After header tells you when to retry.

Errors

All errors use { "error": { "code", "message" } }. Codes: unauthorized, forbidden_scope, not_found, rate_limited, validation_error.

Coming next

Outbound webhooks (item found, claim approved, shipment delivered), reservations & a “did the guest leave something?” endpoint for guest-experience platforms, and OAuth2 for marketplace apps. Want early access? Get in touch.