{"openapi":"3.1.0","info":{"title":"BrandHubify API — integration surface","version":"1.0.0","description":"The subset of the BrandHubify API intended for third-party integration.\n\n**Authentication.** Send the caller's bearer token in `Authorization` and the\nworkspace in `accountId`. Every request is scoped to that workspace; there is no\ncross-account read.\n\n**Errors.** A handled, user-facing problem returns HTTP 200 with\n`{\"status\":\"error\",\"errorMessage\":\"...\"}`. Reserve non-2xx handling for transport\nfaults — do not treat 200 as success without reading `status`.\n\n**Webhook signatures.** Outbound deliveries carry `X-BH-Signature:`\n`t=<unix-seconds>,v1=<hex>`, an HMAC-SHA256 over `\"<t>.<raw body>\"` keyed with the\nendpoint's signing secret. Verify the MAC AND check that `t` is recent — a\nsignature alone is valid forever, so the timestamp is what makes a replay\ndetectable. Deliveries are at-least-once and may arrive out of order; dedupe on\n`X-BH-Event-Id`, which is stable across retries."},"servers":[{"url":"http://api.brandhubify.com"}],"security":[{"bearerAuth":[],"accountId":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Caller access token."},"accountId":{"type":"apiKey","in":"header","name":"accountId","description":"Workspace id. Required on every authenticated call."}},"schemas":{"Lead":{"type":"object","properties":{"leadId":{"type":"string","description":"LD-XXXXXX. The only identifier used in URLs and payloads."},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"stage":{"type":"string","enum":["NEW","CONTACTED","QUALIFIED","PROPOSAL","NEGOTIATION","WON","LOST"]},"source":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Derived. Server-written only; a value sent here is ignored."},"scoreBand":{"type":"string","enum":["HOT","WARM","COLD"]}}},"WebhookEndpoint":{"type":"object","properties":{"endpointId":{"type":"string"},"url":{"type":"string","format":"uri","description":"https only. Private and link-local addresses are refused."},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","paused","disabled"],"description":"`disabled` means WE switched it off after sustained failure."},"failureCount":{"type":"integer","description":"Consecutive failures. Reset by any success."}}},"WebhookEvent":{"type":"object","description":"The body POSTed to a subscribed endpoint.","properties":{"id":{"type":"string","description":"EVT-XXXXXXXX. Stable across retries — dedupe on this."},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"data":{"type":"object","additionalProperties":true}}}}},"paths":{"/leads/all":{"get":{"summary":"List leads","tags":["Leads"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"stage","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of leads, scoped to the caller's workspace and data scope.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"success"},"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"totalItems":{"type":"integer"}}}}}}}}},"/leads/create":{"post":{"summary":"Create a lead","description":"A repeat email from a portal-style source appends an activity to the existing lead instead of creating a duplicate.","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"responses":{"200":{"description":"The created or matched lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"default":{"description":"Handled error. The service answers 200 with status:\"error\" for user-facing problems.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"error"},"errorMessage":{"type":"string"}}}}}}}}},"/leads/scoring/score":{"post":{"summary":"Score one lead now","description":"Returns the 0–100 score, its band, and the per-signal breakdown behind it.","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["leadId"],"properties":{"leadId":{"type":"string"}}}}}},"responses":{"200":{"description":"Score and breakdown."},"default":{"description":"Handled error. The service answers 200 with status:\"error\" for user-facing problems.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"error"},"errorMessage":{"type":"string"}}}}}}}}},"/appointments/all":{"get":{"summary":"List appointments","tags":["Appointments"],"responses":{"200":{"description":"Appointments in range."}}}},"/appointments/attendance":{"get":{"summary":"Show rate for a window","description":"Denominated on DECIDED outcomes only — attended versus missed. Cancellations are excluded from both sides. `showRatePct` is null when nothing has been decided yet.","tags":["Appointments"],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Attendance totals plus a per-provider split."}}}},"/chat-widget/conversations":{"get":{"summary":"List website-chat conversations","tags":["Chat widget"],"responses":{"200":{"description":"Conversations, newest activity first."}}}},"/chat-widget/reply":{"post":{"summary":"Reply to a website-chat conversation","tags":["Chat widget"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversationId","body"],"properties":{"conversationId":{"type":"string"},"body":{"type":"string"}}}}}},"responses":{"200":{"description":"The updated thread."},"default":{"description":"Handled error. The service answers 200 with status:\"error\" for user-facing problems.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"error"},"errorMessage":{"type":"string"}}}}}}}}},"/outbound-webhooks/event-types":{"get":{"summary":"Event types available to subscribe to","tags":["Webhooks"],"responses":{"200":{"description":"The catalogue."}}}},"/outbound-webhooks/all":{"get":{"summary":"List webhook endpoints","description":"Signing secrets are never returned here.","tags":["Webhooks"],"responses":{"200":{"description":"Endpoints, without secrets.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"success"},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}}}}},"/outbound-webhooks/create":{"post":{"summary":"Create a webhook endpoint","description":"The response carries `signingSecret`. This is the ONLY time it is returned — store it before leaving the response, or rotate to get a new one.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"The endpoint plus its signing secret."},"default":{"description":"Handled error. The service answers 200 with status:\"error\" for user-facing problems.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"error"},"errorMessage":{"type":"string"}}}}}}}}},"/outbound-webhooks/deliveries":{"get":{"summary":"Delivery log","description":"Answers \"did you send it?\" — attempts, response status and the last error per delivery.","tags":["Webhooks"],"responses":{"200":{"description":"Recent deliveries."}}}},"/outbound-webhooks/deliveries/retry":{"post":{"summary":"Re-queue a dead delivery","description":"Keeps the original event id so the receiver can still dedupe.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deliveryId"],"properties":{"deliveryId":{"type":"string"}}}}}},"responses":{"200":{"description":"Re-queued."},"default":{"description":"Handled error. The service answers 200 with status:\"error\" for user-facing problems.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"error"},"errorMessage":{"type":"string"}}}}}}}}}},"tags":[{"name":"Leads","description":"CRM records and lead scoring."},{"name":"Appointments","description":"Scheduling and attendance."},{"name":"Chat widget","description":"Website chat conversations and replies."},{"name":"Webhooks","description":"Outbound event delivery to your own systems."}]}