{"openapi":"3.1.0","info":{"title":"LynBro PBX — Part A (site side)","version":"1.0.0","x-contract":"partner/v1","description":"Endpoints the LynBro AI phone calls on a booking system to read the catalogue and free time and to book, move and cancel. Times are UTC with Z, money in minor units, ids are strings.\n\n**Lynbro Signature v1.** Every request carries\n\n```\nX-Lynbro-Timestamp: <unix seconds>\nX-Lynbro-Event-Id: <uuid, new per HTTP attempt>\nX-Lynbro-Signature: v1=<hex HMAC-SHA256(secret, ts + \".\" + METHOD + \" \" + path + \".\" + raw_body)>\nX-Lynbro-Key: lynbro-pbx\nX-Lynbro-Contract: partner/v1\n```\n\n`path` = the request target exactly as sent, with `?query` (PHP: `$_SERVER['REQUEST_URI']`). `raw_body` = the bytes received (empty for GET). Verify in this order: timestamp within ±300 s → constant-time compare (`hash_equals`) against the current and, during rotation, the previous secret → event id not seen in the last 300 s (replay cache) → only then parse the body. Anything else: **401** with the error envelope. Header names are case-insensitive: `X-LynBro-Signature` is the same header. An empty secret must fail closed.\n\nConformance suite: https://pbx-app.lynbro.dk/partner/v1/conformance.py (suite 1.0.0)."},"servers":[{"url":"{base}","variables":{"base":{"default":"https://example.dk/wp-json/lynbro-pbx/v1"}}}],"security":[{"LynbroSignatureV1":[]}],"paths":{"/health":{"get":{"operationId":"health","summary":"Liveness, no heavy systems","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/catalog":{"get":{"operationId":"catalog","summary":"Services, staff, locations. Do not send hidden items.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/slots":{"get":{"operationId":"slots","summary":"Really free start times, at most `limit`","parameters":[{"name":"service_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"staff_id","in":"query","schema":{"type":"string"}},{"name":"location_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"Empty list is a normal answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Slots"}}}},"404":{"description":"Unknown service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/appointments":{"post":{"operationId":"createAppointment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAppointment"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentCard"}}}},"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentCard"}}}},"404":{"description":"Unknown service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"slot taken | already_booked | online_terms_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/appointments/{id}/reschedule":{"post":{"operationId":"rescheduleAppointment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time"},"staff_id":{"type":["string","null"]},"notify_customer":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The card; a NEW id if your system re-created it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentCard"}}}},"404":{"description":"No such appointment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Slot taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/appointments/{id}/cancel":{"post":{"operationId":"cancelAppointment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"notify_customer":{"type":"boolean"}}}}}},"responses":{"200":{"description":"status=cancelled; fee_minor/fee_reason if a fee applies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentCard"}}}},"404":{"description":"No such appointment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{phone}/appointments":{"get":{"operationId":"customerAppointments","parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"},"description":"URL-encoded E.164 (%2B4512345678)"},{"name":"include_past","in":"query","schema":{"type":"string","enum":["0","1"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Unknown number → {\"appointments\": []}, not 404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentList"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{phone}":{"get":{"operationId":"customer","parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"},"description":"URL-encoded E.164 (%2B4512345678)"}],"description":"Caller ID is a hint, not an identity: name and what is needed to greet and confirm the next visit. Never payment data, addresses, passwords or other people's bookings.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"404":{"description":"Unknown number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Signature missing, wrong, stale or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"LynbroSignatureV1":{"type":"apiKey","in":"header","name":"X-Lynbro-Signature","description":"**Lynbro Signature v1.** Every request carries\n\n```\nX-Lynbro-Timestamp: <unix seconds>\nX-Lynbro-Event-Id: <uuid, new per HTTP attempt>\nX-Lynbro-Signature: v1=<hex HMAC-SHA256(secret, ts + \".\" + METHOD + \" \" + path + \".\" + raw_body)>\nX-Lynbro-Key: lynbro-pbx\nX-Lynbro-Contract: partner/v1\n```\n\n`path` = the request target exactly as sent, with `?query` (PHP: `$_SERVER['REQUEST_URI']`). `raw_body` = the bytes received (empty for GET). Verify in this order: timestamp within ±300 s → constant-time compare (`hash_equals`) against the current and, during rotation, the previous secret → event id not seen in the last 300 s (replay cache) → only then parse the body. Anything else: **401** with the error envelope. Header names are case-insensitive: `X-LynBro-Signature` is the same header. An empty secret must fail closed."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}},"Health":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"version":{"type":"string"},"contract":{"type":"string"}}},"Service":{"type":"object","required":["id","name","duration_min"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"category_id":{"type":["string","null"]},"duration_min":{"type":"integer"},"buffer_min":{"type":"integer"},"price_minor":{"type":["integer","null"]},"currency":{"type":"string"},"staff_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"i18n":{"type":"object"},"active":{"type":"boolean"},"online_bookable":{"type":"boolean"},"hidden":{"type":"boolean"},"staff_prices":{"type":"array","items":{"type":"object","required":["staff_id"],"properties":{"staff_id":{"type":"string"},"price_minor":{"type":["integer","null"]},"duration_min":{"type":["integer","null"]}}}},"removal_extras":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"price_minor":{"type":["integer","null"]},"duration_min":{"type":["integer","null"]}}}}}},"Staff":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"service_ids":{"type":"array","items":{"type":"string"}},"location_ids":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"hidden":{"type":"boolean"}}},"Location":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"timezone":{"type":"string"},"active":{"type":"boolean"}}},"Catalog":{"type":"object","required":["services"],"properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"staff":{"type":"array","items":{"$ref":"#/components/schemas/Staff"}},"locations":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}}},"Slot":{"type":"object","required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time","description":"ISO-8601 in UTC with Z, e.g. 2026-10-01T09:00:00Z"},"ends_at":{"type":"string","format":"date-time","description":"ISO-8601 in UTC with Z, e.g. 2026-10-01T09:00:00Z"},"staff_id":{"type":["string","null"]},"staff_name":{"type":["string","null"]},"location_id":{"type":["string","null"]},"price_minor":{"type":["integer","null"]}}},"Slots":{"type":"object","required":["slots"],"properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}}}},"Appointment":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["confirmed","requested","cancelled","completed","no_show"]},"starts_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601 in UTC with Z, e.g. 2026-10-01T09:00:00Z"},"ends_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601 in UTC with Z, e.g. 2026-10-01T09:00:00Z"},"service_id":{"type":["string","null"]},"service_name":{"type":["string","null"]},"staff_id":{"type":["string","null"]},"staff_name":{"type":["string","null"]},"location_id":{"type":["string","null"]},"price_minor":{"type":["integer","null"]},"currency":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"customer_phone":{"type":["string","null"]},"can_cancel":{"type":"boolean"},"can_reschedule":{"type":"boolean"},"notification_sent":{"type":["boolean","null"]},"fee_minor":{"type":["integer","null"]},"fee_reason":{"type":["string","null"]}}},"AppointmentCard":{"type":"object","required":["appointment"],"properties":{"appointment":{"$ref":"#/components/schemas/Appointment"}}},"AppointmentList":{"type":"object","required":["appointments"],"properties":{"appointments":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}}}},"Customer":{"type":"object","required":["customer"],"properties":{"customer":{"type":"object","required":["name"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"visits_total":{"type":["integer","null"]},"last_visit_at":{"type":["string","null"]},"favourite_service":{"type":["string","null"]},"favourite_staff":{"type":["string","null"]},"notes":{"type":["string","null"]},"loyalty":{"type":["object","null"]}}}}},"CreateAppointment":{"type":"object","required":["service_id","starts_at","customer","idempotency_key"],"properties":{"service_id":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"staff_id":{"type":["string","null"]},"location_id":{"type":["string","null"]},"customer":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"E.164"},"name":{"type":["string","null"]},"email":{"type":["string","null"]}}},"notes":{"type":["string","null"]},"extras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"integer"}}}},"source":{"type":"string","enum":["phone-ai"]},"idempotency_key":{"type":"string","description":"Same key → the same appointment, never a second one. Store it BEFORE creating."},"notify_customer":{"type":"boolean","description":"Present and true when the tenant switched on 'booking confirmations are sent by the site': send the booking's normal confirmation. Absent → your own default. The PBX itself never sends a confirmation for such a tenant."},"confirm":{"type":"boolean","description":"Only for providers connected with the two-phase option; WordPress connections never receive it."}}}}}}