{"openapi":"3.1.0","info":{"title":"Privacy by ZeroClause API","version":"1.0.0","summary":"Consent, privacy requests and breach reporting for India's DPDP Act, for your own software.","description":"Use this API from **your server** to record and check consent, send people their own privacy pages, receive privacy requests, report a breach and keep your clinics in sync. Keep your API key on the server: never put it in a website or app that customers download.\n\n**Authentication.** Create a key in the dashboard (Integrations & API). Send it as `Authorization: Bearer zc_live_…` (or `x-api-key`). A *site key* opens one website. A *platform key* opens every website of your account and can create clinics (`sites:manage`). A *test key* (`zc_test_…`) works only on your sandbox website, with made-up data: nobody is emailed and nothing real is touched. A test key on a real website, and a live key on the sandbox, are both refused. A *platform test key* (`zc_test_…`, made in Integrations & API → API access) is for software with many clinics: with it `/api/v1/sites` creates up to 20 practice clinics (sandbox, made-up data, emptied after 30 idle days), and the key then works on them like a site test key. It cannot reach real clinics or `/api/v1/webhook`.\n\n**Permissions.** Each operation lists the permission it needs (`consent:read`, `consent:write`, `notice:read`, `requests:read`, `requests:write`, `breach:write`, `sites:manage`). A key without it gets `403 missing_scope:<permission>`.\n\n**Errors.** Every failure is JSON: `{ \"error\": \"code\", \"message\": \"…\" }` with the matching HTTP status.\n\n**Webhooks.** We call your server when consent is recorded, withdrawn or confirmed and when a privacy request arrives. See the `webhooks` section for the payload and the signature. Events that your server does not accept are retried (1 min, 5 min, 30 min, 2 h, 6 h, 24 h) with the same event id.\n\n**Not legal advice.** This API gives tools to help you meet the Digital Personal Data Protection Act, 2023. It does not certify that anyone complies.","contact":{"name":"ZeroClauseAI support","email":"support@zeroclauseai.com","url":"https://zeroclauseai.com/dpdp/developers"}},"externalDocs":{"description":"Developer guide and SDK","url":"https://zeroclauseai.com/dpdp/developers"},"servers":[{"url":"https://zeroclauseai.com","description":"Production (live keys and test keys)"}],"tags":[{"name":"Consent","description":"Record, check and find consent for your own patients or customers."},{"name":"Notice","description":"The published privacy notice, to show inside your own app."},{"name":"Requests","description":"People asking to see, correct or erase their data."},{"name":"Breach","description":"Report a suspected breach: starts the 6-hour and 72-hour clocks. Nothing is sent to CERT-In or the Board for you."},{"name":"Counter screen","description":"The optional screen at the desk that shows a patient's personal consent QR."},{"name":"Sites (platform)","description":"Software that sets up many clinics: create and update them by your own id. Needs a live platform key."},{"name":"Webhooks","description":"One webhook address for all your clinics, and its delivery log. Needs a live platform key."},{"name":"Sandbox","description":"Only with a test key on your sandbox website."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/api/v1/consent":{"get":{"operationId":"getConsent","tags":["Consent"],"summary":"Is this person's consent on file?","description":"Ask this right before you send a reminder or an offer. Pass the patient id (`subjectRef`), the mobile number a walk-in typed at the poster (`phone`), or both. The newest choice that counts wins: a withdrawal counts at once, and a walk-in \"yes\" counts only after the person confirmed from that same phone. Offers (`canSendMarketing`) are never allowed for a child. Needs a key with the `consent:read` permission.","parameters":[{"name":"siteId","in":"query","required":true,"description":"The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.","schema":{"type":"string"}},{"name":"subjectRef","in":"query","description":"Your id for the patient (letters, numbers and `- _ . : @ +`, up to 100 characters).","schema":{"type":"string"}},{"name":"phone","in":"query","description":"A walk-in's mobile number (10 digits or +91…). Looked up by a keyed hash; never stored.","schema":{"type":"string"}}],"responses":{"200":{"description":"The person's current consent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-required-scope":"consent:read"},"post":{"operationId":"recordConsent","tags":["Consent"],"summary":"Record a choice you collected yourself","description":"Save what a patient chose, in your app, on WhatsApp or at the front desk. Every record is chained to the one before it, so it cannot be edited or removed later without being detected. A \"yes\" linked to a patient also gets a 6-digit code the patient can send from their own phone to prove it was them (`confirm` in the answer). For a child send `minor: true` and the parent in `givenBy`; offers and analytics are then always off. Up to 300 records a minute per server address. Needs a key with the `consent:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordConsentRequest"}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordConsentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"consent:write"}},"/api/v1/consent-link":{"post":{"operationId":"createConsentLink","tags":["Consent"],"summary":"A personal consent link or QR for one patient","description":"The patient opens it, chooses, and the choice is saved against their id. Show it as a QR at the desk or send it by WhatsApp. Valid 1 to 30 days (default 7). Needs a key with the `consent:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentLinkRequest"}}}},"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentLinkResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"x-required-scope":"consent:write"}},"/api/v1/preferences-link":{"post":{"operationId":"createPreferencesLink","tags":["Consent"],"summary":"A patient's own \"My privacy choices\" page","description":"A personal page where the patient sees what they agreed to, changes it, withdraws it, and asks for their rights. No sign-in: the link is the key, so send it to that patient only. Valid 1 to 365 days (default 180). It opens in the clinic's default language; add `&lang=hi` (any supported language) to open it in another. Needs a key with the `consent:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesLinkRequest"}}}},"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesLinkResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"x-required-scope":"consent:write"}},"/api/v1/consent/lookup":{"post":{"operationId":"lookupConsent","tags":["Consent"],"summary":"Consent of up to 500 patients at once","description":"Send your own patient ids. Each comes back as `consented`, `withdrawn` or `no_record` (never asked). With `onlyNeedingAction: true` you get only the patients you still have to ask (`needs: \"ask\"`) or ask again after a newer notice (`needs: \"ask_again\"`). People who said no are never listed. Needs a key with the `consent:read` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupRequest"}}}},"responses":{"200":{"description":"The status of each patient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-required-scope":"consent:read"}},"/api/v1/consent/summary":{"get":{"operationId":"getConsentSummary","tags":["Consent"],"summary":"Totals for the whole website or clinic","description":"One count per person (their newest choice). Only people who have a record are counted: to find patients who were never asked, use `lookupConsent` with your own list. Needs a key with the `consent:read` permission.","parameters":[{"name":"siteId","in":"query","required":true,"description":"The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.","schema":{"type":"string"}}],"responses":{"200":{"description":"The totals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"consent:read"}},"/api/v1/notice":{"get":{"operationId":"getNotice","tags":["Notice"],"summary":"The published privacy notice","description":"The notice text in one of the clinic's languages, its grievance contact, the public links, the data map, and ready messages for telling existing patients about the notice. Needs a key with the `notice:read` permission.","parameters":[{"name":"siteId","in":"query","required":true,"description":"The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.","schema":{"type":"string"}},{"name":"lang","in":"query","description":"A language code the clinic has switched on. Defaults to the clinic's default language.","schema":{"type":"string","enum":["as","bn","brx","doi","en","gu","hi","kn","kok","ks","mai","ml","mni","mr","ne","or","pa","sa","sat","sd","ta","te","ur"]}}],"responses":{"200":{"description":"The notice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoticeResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"x-required-scope":"notice:read"}},"/api/v1/requests":{"get":{"operationId":"listRequests","tags":["Requests"],"summary":"The latest 200 privacy requests","description":"Needs a key with the `requests:read` permission.","parameters":[{"name":"siteId","in":"query","required":true,"description":"The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.","schema":{"type":"string"}}],"responses":{"200":{"description":"The requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"requests:read"},"post":{"operationId":"createRequest","tags":["Requests"],"summary":"Send a privacy request on someone's behalf","description":"For when a person asks at the front desk or in your app. Same checks, emails and reply-by date as the hosted form; the person is treated as verified. In a sandbox nobody is emailed. Needs a key with the `requests:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequestRequest"}}}},"responses":{"200":{"description":"The request was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequestResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"requests:write"}},"/api/v1/breach":{"post":{"operationId":"reportBreach","tags":["Breach"],"summary":"Report a suspected breach","description":"Works out the deadlines (CERT-In within 6 hours for cyber incidents, the Data Protection Board's detailed report within 72 hours), saves the incident in the dashboard, alerts the owner by bell and email, and returns draft notices with [blanks] for facts only the business knows. **Nothing is sent to CERT-In, the Board or anyone for you**, and the drafts are guidance, not legal advice. With a test key the incident is a practice drill and nobody is alerted. Needs a key with the `breach:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreachRequest"}}}},"responses":{"200":{"description":"Deadlines, checklist and drafts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreachResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-required-scope":"breach:write"}},"/api/v1/display":{"get":{"operationId":"listDisplays","tags":["Counter screen"],"summary":"The paired counter screens","description":"A screen is online when it asked for its state in the last 20 seconds. Needs a key with the `consent:read` permission.","parameters":[{"name":"siteId","in":"query","required":true,"description":"The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.","schema":{"type":"string"}}],"responses":{"200":{"description":"The screens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisplayList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-required-scope":"consent:read"},"post":{"operationId":"controlDisplay","tags":["Counter screen"],"summary":"Show or clear a patient's QR on a counter screen","description":"`action: \"show\"` shows that patient's personal consent QR (valid 1 to 120 minutes, default 10). The screen never shows a name or an id. `action: \"clear\"` takes it off. With several screens, say which with `displayId`. Needs a key with the `consent:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DisplayShowRequest"},{"$ref":"#/components/schemas/DisplayClearRequest"}],"discriminator":{"propertyName":"action"}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DisplayShowResponse"},{"$ref":"#/components/schemas/DisplayClearResponse"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanPaused"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"consent:write"}},"/api/v1/sites":{"get":{"operationId":"listSites","tags":["Sites (platform)"],"summary":"Your clinics","description":"Needs a platform key with the `sites:manage` permission. A live key lists your real clinics (the sandbox is not listed); a platform test key lists only your practice clinics.","parameters":[{"name":"externalRef","in":"query","description":"Your own id for one clinic.","schema":{"type":"string"}}],"responses":{"200":{"description":"The clinics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"},"post":{"operationId":"upsertSite","tags":["Sites (platform)"],"summary":"Create or update a clinic (safe to repeat)","description":"The same `externalRef` updates the clinic instead of making a second one, so retries never duplicate. Add `publish: true` to publish the notice (it only publishes again when something in the notice changed). Needs a platform key with the `sites:manage` permission. With a platform TEST key the clinic is a practice clinic (sandbox): the plan and agreement are not needed, missing contact details get made-up ones, there are at most 20, and a live key never sees them. Answers 201 when the clinic was created, 200 when it was updated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpsertRequest"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpsertResponse"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpsertResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"}},"/api/v1/webhook":{"get":{"operationId":"getWebhook","tags":["Webhooks"],"summary":"Your webhook address","description":"Needs a live platform key with the `sites:manage` permission.","responses":{"200":{"description":"The webhook (or null) and the events you can subscribe to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookGetResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"},"post":{"operationId":"setWebhook","tags":["Webhooks"],"summary":"Set or replace your webhook address","description":"One address for all your clinics (each event says which clinic it is about). Must be a public `https://` address. Returns a new signing secret, **once**. Needs a live platform key with the `sites:manage` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSetRequest"}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSetResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"},"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Remove your webhook","description":"Needs a live platform key with the `sites:manage` permission.","responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"}},"/api/v1/webhook/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"The delivery log of your webhook","description":"The latest 50 events. `pending`: we will try again at `next_attempt_at`. `delivered`: your server answered 2xx. `dead`: all 7 attempts failed. Needs a live platform key with the `sites:manage` permission.","responses":{"200":{"description":"The deliveries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"},"post":{"operationId":"redeliverWebhook","tags":["Webhooks"],"summary":"Send a dead event again","description":"Sends it again by hand, with the same event id. Possible for 14 days after it first failed, while the webhook is switched on. The saved copy of an event (it holds personal data) is deleted as soon as it is delivered. Needs a live platform key with the `sites:manage` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The delivery id from the log."}},"required":["id"]}}}},"responses":{"200":{"description":"Tried again.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"status":{"type":"integer","description":"What your server answered (0: no answer)."},"delivered":{"type":"boolean"}},"required":["ok","status","delivered"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"sites:manage"}},"/api/v1/sandbox/confirm":{"post":{"operationId":"sandboxConfirm","tags":["Sandbox"],"summary":"Act as the patient who confirms from their own phone","description":"There is no patient phone in a sandbox, so this confirms that patient's waiting choice as if they had sent the code from their registered number, and fires the `consent.confirmed` webhook. Any other website answers `403 sandbox_only`. Needs a key with the `consent:write` permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxConfirmRequest"}}}},"responses":{"200":{"description":"Confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxConfirmResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"x-required-scope":"consent:write"}}},"webhooks":{"consent_recorded":{"post":{"operationId":"webhook_consent_recorded","tags":["Webhooks"],"summary":"Event consent.recorded","description":"A person gave or changed their consent.\n\nAnswer with any 2xx status within 5 seconds. Otherwise we try again (1 min, 5 min, 30 min, 2 h, 6 h, 24 h) with the **same event id** (`id`, also the `X-ZeroClause-Event-Id` header), so keep the ids you have handled and ignore repeats. After 7 failed attempts the event is `dead` and can be re-sent for 14 days.\n\n**Verify the signature.** `X-ZeroClause-Signature: t=<unix seconds>,v1=<hex>` where `v1` is HMAC-SHA256 of `<t>.<raw request body>` with your signing secret (starts with `whsec_`). Use the raw body, and reject deliveries older than 5 minutes.","security":[],"parameters":[{"name":"X-ZeroClause-Event","in":"header","schema":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created","webhook.test"]}},{"name":"X-ZeroClause-Event-Id","in":"header","schema":{"type":"string"}},{"name":"X-ZeroClause-Attempt","in":"header","description":"1 to 7","schema":{"type":"integer","minimum":1,"maximum":7}},{"name":"X-ZeroClause-Signature","in":"header","required":true,"schema":{"type":"string","examples":["t=1793000000,v1=9f2c…"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received. Any 2xx counts."}}}},"consent_withdrawn":{"post":{"operationId":"webhook_consent_withdrawn","tags":["Webhooks"],"summary":"Event consent.withdrawn","description":"A person withdrew or refused consent.\n\nAnswer with any 2xx status within 5 seconds. Otherwise we try again (1 min, 5 min, 30 min, 2 h, 6 h, 24 h) with the **same event id** (`id`, also the `X-ZeroClause-Event-Id` header), so keep the ids you have handled and ignore repeats. After 7 failed attempts the event is `dead` and can be re-sent for 14 days.\n\n**Verify the signature.** `X-ZeroClause-Signature: t=<unix seconds>,v1=<hex>` where `v1` is HMAC-SHA256 of `<t>.<raw request body>` with your signing secret (starts with `whsec_`). Use the raw body, and reject deliveries older than 5 minutes.","security":[],"parameters":[{"name":"X-ZeroClause-Event","in":"header","schema":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created","webhook.test"]}},{"name":"X-ZeroClause-Event-Id","in":"header","schema":{"type":"string"}},{"name":"X-ZeroClause-Attempt","in":"header","description":"1 to 7","schema":{"type":"integer","minimum":1,"maximum":7}},{"name":"X-ZeroClause-Signature","in":"header","required":true,"schema":{"type":"string","examples":["t=1793000000,v1=9f2c…"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received. Any 2xx counts."}}}},"consent_confirmed":{"post":{"operationId":"webhook_consent_confirmed","tags":["Webhooks"],"summary":"Event consent.confirmed","description":"A person confirmed their choice from their own phone.\n\nAnswer with any 2xx status within 5 seconds. Otherwise we try again (1 min, 5 min, 30 min, 2 h, 6 h, 24 h) with the **same event id** (`id`, also the `X-ZeroClause-Event-Id` header), so keep the ids you have handled and ignore repeats. After 7 failed attempts the event is `dead` and can be re-sent for 14 days.\n\n**Verify the signature.** `X-ZeroClause-Signature: t=<unix seconds>,v1=<hex>` where `v1` is HMAC-SHA256 of `<t>.<raw request body>` with your signing secret (starts with `whsec_`). Use the raw body, and reject deliveries older than 5 minutes.","security":[],"parameters":[{"name":"X-ZeroClause-Event","in":"header","schema":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created","webhook.test"]}},{"name":"X-ZeroClause-Event-Id","in":"header","schema":{"type":"string"}},{"name":"X-ZeroClause-Attempt","in":"header","description":"1 to 7","schema":{"type":"integer","minimum":1,"maximum":7}},{"name":"X-ZeroClause-Signature","in":"header","required":true,"schema":{"type":"string","examples":["t=1793000000,v1=9f2c…"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received. Any 2xx counts."}}}},"request_created":{"post":{"operationId":"webhook_request_created","tags":["Webhooks"],"summary":"Event request.created","description":"A privacy request arrived.\n\nAnswer with any 2xx status within 5 seconds. Otherwise we try again (1 min, 5 min, 30 min, 2 h, 6 h, 24 h) with the **same event id** (`id`, also the `X-ZeroClause-Event-Id` header), so keep the ids you have handled and ignore repeats. After 7 failed attempts the event is `dead` and can be re-sent for 14 days.\n\n**Verify the signature.** `X-ZeroClause-Signature: t=<unix seconds>,v1=<hex>` where `v1` is HMAC-SHA256 of `<t>.<raw request body>` with your signing secret (starts with `whsec_`). Use the raw body, and reject deliveries older than 5 minutes.","security":[],"parameters":[{"name":"X-ZeroClause-Event","in":"header","schema":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created","webhook.test"]}},{"name":"X-ZeroClause-Event-Id","in":"header","schema":{"type":"string"}},{"name":"X-ZeroClause-Attempt","in":"header","description":"1 to 7","schema":{"type":"integer","minimum":1,"maximum":7}},{"name":"X-ZeroClause-Signature","in":"header","required":true,"schema":{"type":"string","examples":["t=1793000000,v1=9f2c…"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received. Any 2xx counts."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zc_live_… or zc_test_…","description":"`Authorization: Bearer zc_live_<48 hex>`"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same key, in a header of its own."}},"responses":{"BadRequest":{"description":"The request is wrong (`bad_json`, `invalid_phone`, `valid_subjectRef_required`, `invalid_action`, `invalid_channel`, `too_many`, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"valid_subjectRef_required"}}}},"Unauthorized":{"description":"No key, or not a ZeroClause key (`missing_api_key`, `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key"}}}},"PlanPaused":{"description":"The account's plan has paused after the grace period (`plan_paused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"plan_paused"}}}},"Forbidden":{"description":"The key may not do this (`revoked_api_key`, `key_not_for_this_site`, `missing_scope:<permission>`, `test_key_live_site`, `live_key_sandbox_site`, `test_key_not_allowed`, `platform_key_required`, `sandbox_only`, `link_expired_or_invalid`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"missing_scope:consent:write"}}}},"NotFound":{"description":"No such website, webhook or delivery (`site_not_found`, `no_webhook`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"site_not_found"}}}},"Conflict":{"description":"Not possible right now (`notice_not_published`: publish the notice first; `nothing_waiting`; `cannot_redeliver`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"notice_not_published"}}}},"TooManyRequests":{"description":"Too fast (`rate_limit_exceeded`, `too_many_for_this_number`). Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limit_exceeded"}}}},"ServerError":{"description":"Our side (`not_saved`, `lookup_failed`, `summary_failed`, `setup_incomplete`, `auth_service_unavailable`). Safe reads can be tried again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"lookup_failed"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"A short code."},"message":{"type":"string","description":"A sentence for a person, on some errors."}},"required":["error"]},"Choices":{"type":"object","properties":{"reminders":{"type":"boolean","description":"Appointment reminders and updates."},"marketing":{"type":"boolean","description":"Offers and news. Never allowed for a child."},"analytics":{"type":"boolean","description":"Analytics. Never allowed for a child."}},"description":"What the person agreed to. A missing key means no. The response also carries `necessary: true`.","additionalProperties":true},"GivenBy":{"type":"object","properties":{"role":{"type":"string","enum":["self","parent","guardian"]},"name":{"type":"string","description":"Required for a parent or guardian."},"relation":{"type":"string","description":"For example Mother."},"adultConfirmed":{"type":"boolean","description":"Must be true for a parent or guardian: they are an adult and the lawful parent or guardian."}},"required":["role"]},"ConfirmInfo":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","description":"The 6-digit code the patient sends from their own phone.","pattern":"^[0-9]{6}$"},"expiresAt":{"type":"string","format":"date-time"},"number":{"type":"string","description":"Our number, digits only."},"numberDisplay":{"type":"string"},"whatsappUrl":{"type":"string"},"smsUrl":{"type":"string"},"missedCall":{"type":"boolean","description":"A missed call to our number also confirms (when a phone number was given)."}},"required":["id","code","expiresAt","number","numberDisplay","whatsappUrl","smsUrl","missedCall"]},"Confirmation":{"type":"object","properties":{"status":{"type":"string","enum":["pending","confirmed","expired"]},"via":{"oneOf":[{"type":"string","enum":["whatsapp","sms","missed_call"]},{"type":"null"}]},"fromRegisteredNumber":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"assistedBy":{"oneOf":[{"type":"string"},{"type":"null"}]},"confirmedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"label":{"type":"string","description":"The proof in plain words."}},"required":["status"]},"ConsentStatus":{"type":"object","properties":{"ok":{"const":true},"found":{"type":"boolean","description":"false when there is no counting choice."},"subjectRef":{"oneOf":[{"type":"string"},{"type":"null"}]},"lookedUpBy":{"type":"string","enum":["subjectRef","phone","subjectRef+phone"]},"status":{"type":"string","enum":["consented","withdrawn","no_record","awaiting_confirmation"],"description":"`awaiting_confirmation`: a walk-in typed their number but has not confirmed from that phone yet. Treat it as no consent."},"canSendReminders":{"type":"boolean"},"canSendMarketing":{"type":"boolean"},"note":{"type":"string"},"walkIn":{"type":"boolean"},"action":{"type":"string","enum":["accept_all","reject_all","custom","withdraw"]},"choices":{"$ref":"#/components/schemas/Choices"},"givenBy":{"$ref":"#/components/schemas/GivenBy"},"noticeVersion":{"type":"integer"},"noticeChanged":{"type":"boolean","description":"A newer notice was published since: ask again when you next see them."},"channel":{"oneOf":[{"type":"string"},{"type":"null"}]},"recordedAt":{"type":"string","format":"date-time"},"language":{"oneOf":[{"type":"string"},{"type":"null"}]},"confirmation":{"oneOf":[{"$ref":"#/components/schemas/Confirmation"},{"type":"null"}]}},"required":["ok","found","status","canSendReminders","canSendMarketing"]},"RecordConsentRequest":{"type":"object","properties":{"siteId":{"type":"string","description":"The website (slug or id). `site` is also accepted."},"subjectRef":{"type":"string","description":"Your id for the patient.","maxLength":100},"action":{"type":"string","enum":["accept_all","reject_all","custom","withdraw"],"default":"custom","description":"`accept_all` means reminders and offers (reminders only for a child)."},"choices":{"$ref":"#/components/schemas/Choices"},"channel":{"type":"string","enum":["app","whatsapp","web","api","qr"],"default":"api"},"language":{"type":"string","description":"The language the patient saw (a code the clinic offers)."},"phone":{"type":"string","description":"The patient's mobile number, so their confirmation can be checked against it. Stored only as a keyed hash."},"assistedBy":{"type":"string","description":"The staff member who helped, when it was filled in on the clinic's device."},"minor":{"type":"boolean","description":"The patient is under 18: `givenBy` must be a parent."},"givenBy":{"$ref":"#/components/schemas/GivenBy"}},"required":["siteId"]},"RecordConsentResponse":{"type":"object","properties":{"ok":{"const":true},"consentId":{"type":"integer"},"subjectRef":{"oneOf":[{"type":"string"},{"type":"null"}]},"action":{"type":"string","enum":["accept_all","reject_all","custom","withdraw"]},"choices":{"type":"object","properties":{"necessary":{"const":true},"reminders":{"type":"boolean"},"marketing":{"type":"boolean"},"analytics":{"type":"boolean"}}},"channel":{"type":"string"},"givenBy":{"$ref":"#/components/schemas/GivenBy"},"noticeVersion":{"type":"integer"},"recordedAt":{"type":"string","format":"date-time"},"assistedBy":{"type":"string"},"confirm":{"oneOf":[{"$ref":"#/components/schemas/ConfirmInfo"},{"type":"null"}]}},"required":["ok","consentId","action","choices","channel","noticeVersion","recordedAt","confirm"]},"ConsentLinkRequest":{"type":"object","properties":{"siteId":{"type":"string"},"subjectRef":{"type":"string"},"days":{"type":"integer","description":"1 to 30, default 7.","minimum":1,"maximum":30,"default":7},"phone":{"type":"string"},"assistedBy":{"type":"string"},"minor":{"type":"boolean"}},"required":["siteId","subjectRef"]},"ConsentLinkResponse":{"type":"object","properties":{"ok":{"const":true},"subjectRef":{"type":"string"},"url":{"type":"string","description":"Open it in a browser, or show it as a QR.","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"phoneRegistered":{"type":"boolean"},"assisted":{"type":"boolean"},"minor":{"type":"boolean"}},"required":["ok","subjectRef","url","expiresAt"]},"PreferencesLinkRequest":{"type":"object","properties":{"siteId":{"type":"string"},"subjectRef":{"type":"string"},"days":{"type":"integer","description":"1 to 365, default 180.","minimum":1,"maximum":365,"default":180},"phone":{"type":"string"},"minor":{"type":"boolean"}},"required":["siteId","subjectRef"]},"PreferencesLinkResponse":{"type":"object","properties":{"ok":{"const":true},"subjectRef":{"type":"string"},"url":{"type":"string","description":"The patient's page. Send it to that patient only.","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"phoneRegistered":{"type":"boolean"},"minor":{"type":"boolean"}},"required":["ok","subjectRef","url","expiresAt"]},"LookupRequest":{"type":"object","properties":{"siteId":{"type":"string"},"subjectRefs":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500},"onlyNeedingAction":{"type":"boolean","description":"Return only the patients you still have to ask."}},"required":["siteId","subjectRefs"]},"PatientConsent":{"type":"object","properties":{"subjectRef":{"type":"string"},"status":{"type":"string","enum":["consented","withdrawn","no_record"]},"canSendReminders":{"type":"boolean"},"canSendMarketing":{"type":"boolean"},"noticeChanged":{"type":"boolean"},"child":{"type":"boolean"},"confirmed":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"recordedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"channel":{"oneOf":[{"type":"string"},{"type":"null"}]},"needs":{"oneOf":[{"type":"string","enum":["ask","ask_again"]},{"type":"null"}],"description":"`ask`: never asked, send the link. `ask_again`: answered under an older notice. null: nothing to do (someone who said no is never asked again)."}},"required":["subjectRef","status","canSendReminders","canSendMarketing","noticeChanged","child","confirmed","recordedAt","channel","needs"]},"LookupResponse":{"type":"object","properties":{"ok":{"const":true},"checked":{"type":"integer"},"count":{"type":"integer"},"needs":{"type":"object","properties":{"ask":{"type":"integer"},"ask_again":{"type":"integer"}},"required":["ask","ask_again"]},"noticeVersion":{"type":"integer"},"patients":{"type":"array","items":{"$ref":"#/components/schemas/PatientConsent"}}},"required":["ok","checked","count","needs","noticeVersion","patients"]},"ConsentSummary":{"type":"object","properties":{"ok":{"const":true},"noticeVersion":{"type":"integer"},"people":{"type":"integer"},"consented":{"type":"integer"},"withdrawn":{"type":"integer"},"canSendReminders":{"type":"integer"},"canSendMarketing":{"type":"integer"},"children":{"type":"integer"},"confirmedFromOwnPhone":{"type":"integer"},"awaitingConfirmation":{"type":"integer"},"needAskingAgain":{"type":"integer"},"walkIns":{"type":"integer"},"truncated":{"type":"boolean","description":"true when there were more than 100,000 records and only the newest were counted."}},"required":["ok","noticeVersion","people","consented","withdrawn","canSendReminders","canSendMarketing","children","confirmedFromOwnPhone","awaitingConfirmation","needAskingAgain","walkIns","truncated"]},"NoticeResponse":{"type":"object","properties":{"ok":{"const":true},"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"businessName":{"type":"string"},"sector":{"type":"string","enum":["healthcare","education","ecommerce","manufacturing","realestate","hospitality","wellness","professional","automobile","recruitment"]},"noticeVersion":{"type":"integer"},"publishedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"languages":{"type":"array","items":{"type":"string","enum":["as","bn","brx","doi","en","gu","hi","kn","kok","ks","mai","ml","mni","mr","ne","or","pa","sa","sat","sd","ta","te","ur"]}},"defaultLanguage":{"type":"string"},"grievanceOfficer":{"oneOf":[{"type":"string"},{"type":"null"}]},"grievanceEmail":{"oneOf":[{"type":"string"},{"type":"null"}]},"grievancePhone":{"oneOf":[{"type":"string"},{"type":"null"}]},"responseDays":{"type":"integer"}},"required":["id","slug","businessName","noticeVersion","languages","defaultLanguage"]},"noticeUrl":{"type":"string","format":"uri"},"requestUrl":{"type":"string","format":"uri"},"frontDeskConsentUrl":{"type":"string","description":"The poster / walk-in consent page.","format":"uri"},"notice":{"type":"object","properties":{"language":{"type":"string"},"title":{"type":"string"},"intro":{"type":"array"},"sections":{"type":"array","description":"Headings, paragraphs, lists and tables, as structured data (no HTML)."},"updated":{"type":"string"}},"required":["language","title","sections"]},"dataMap":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Where data is stored, which services receive it, how long it is kept. null when not set."},"outreachMessages":{"type":"object","description":"Ready WhatsApp, SMS and email messages for telling existing patients about the notice."}},"required":["ok","site","noticeUrl","requestUrl","frontDeskConsentUrl","notice"]},"CreateRequestRequest":{"type":"object","properties":{"siteId":{"type":"string"},"kind":{"type":"string","enum":["access","correct","erase","withdraw","nominate","grievance"]},"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","description":"So the business can reply.","format":"email"},"phone":{"type":"string"},"message":{"type":"string","description":"Required (at least 5 characters) for `correct`, `nominate` and `grievance`.","maxLength":3000}},"required":["siteId","kind","name","email"]},"CreateRequestResponse":{"type":"object","properties":{"ok":{"const":true},"request":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["access","correct","erase","withdraw","nominate","grievance"]},"status":{"type":"string"},"dueAt":{"type":"string","description":"The business must reply by this time.","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","status","dueAt","createdAt"]}},"required":["ok","request"]},"RequestList":{"type":"object","properties":{"ok":{"const":true},"total":{"type":"integer"},"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["access","correct","erase","withdraw","nominate","grievance"]},"name":{"type":"string"},"email":{"type":"string"},"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"message":{"oneOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"dueAt":{"type":"string","format":"date-time"},"resolution":{"oneOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"resolvedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","kind","status","dueAt","createdAt"]}}},"required":["ok","total","requests"]},"BreachRequest":{"type":"object","properties":{"siteId":{"type":"string"},"incidentType":{"type":"string","enum":["unauthorized_access","data_leak","ransomware","lost_device","wrong_recipient","other"],"default":"other"},"detectedAt":{"type":"string","description":"When you found out: within the last 90 days, not in the future. Default: now.","format":"date-time"},"affectedCount":{"type":"integer","description":"If known.","minimum":0},"description":{"type":"string","description":"What was found, in plain words.","maxLength":2000}},"required":["siteId"]},"BreachResponse":{"type":"object","properties":{"ok":{"const":true},"incidentRef":{"type":"string","description":"For example `INC-20261106-A1B2C3`."},"incidentType":{"type":"string","enum":["unauthorized_access","data_leak","ransomware","lost_device","wrong_recipient","other"]},"detectedAt":{"type":"string","format":"date-time"},"deadlines":{"type":"object","properties":{"certIn":{"type":"string","description":"Within 6 hours. Only for cyber incidents (not `lost_device` or `wrong_recipient`).","format":"date-time"},"dataProtectionBoardAndPeople":{"type":"string"},"dataProtectionBoardDetailedReport":{"type":"string","description":"Within 72 hours.","format":"date-time"}},"required":["dataProtectionBoardAndPeople","dataProtectionBoardDetailedReport"]},"breachPlanUrl":{"type":"string","format":"uri"},"drafts":{"type":"object","properties":{"certInEmail":{"type":"object","properties":{"to":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"}},"required":["to","subject","body"]},"personNotice":{"type":"object","properties":{"subject":{"type":"string"},"message":{"type":"string"}},"required":["subject","message"]}},"required":["personNotice"],"description":"Drafts with [blanks]. Fill them in and have your lawyer check them."},"checklist":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["ok","incidentRef","incidentType","detectedAt","deadlines","drafts","checklist","note"]},"DisplayShowRequest":{"type":"object","properties":{"siteId":{"type":"string"},"action":{"const":"show"},"subjectRef":{"type":"string"},"displayId":{"type":"string","description":"Needed only when the clinic has more than one screen."},"phone":{"type":"string"},"minor":{"type":"boolean"},"assistedBy":{"type":"string"},"minutes":{"type":"integer","description":"How long the QR works: 1 to 120, default 10.","minimum":1,"maximum":120}},"required":["siteId","action","subjectRef"]},"DisplayClearRequest":{"type":"object","properties":{"siteId":{"type":"string"},"action":{"const":"clear"},"displayId":{"type":"string"}},"required":["siteId","action"]},"DisplayShowResponse":{"type":"object","properties":{"ok":{"const":true},"displayId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"online":{"type":"boolean"}},"required":["ok","displayId","expiresAt","online"]},"DisplayClearResponse":{"type":"object","properties":{"ok":{"const":true},"cleared":{"type":"boolean"}},"required":["ok","cleared"]},"DisplayList":{"type":"object","properties":{"displays":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"online":{"type":"boolean"},"showing":{"type":"string","enum":["waiting","qr","done"]}},"required":["id","name","online","showing"]}}},"required":["displays"]},"Site":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"oneOf":[{"type":"string","description":"Your own id for the clinic."},{"type":"null"}]},"slug":{"type":"string"},"businessName":{"type":"string"},"sector":{"type":"string","enum":["healthcare","education","ecommerce","manufacturing","realestate","hospitality","wellness","professional","automobile","recruitment"]},"websiteUrl":{"oneOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["draft","published"]},"noticeVersion":{"type":"integer"},"publishedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"languages":{"type":"array","items":{"type":"string","enum":["as","bn","brx","doi","en","gu","hi","kn","kok","ks","mai","ml","mni","mr","ne","or","pa","sa","sat","sd","ta","te","ur"]}},"defaultLanguage":{"type":"string"},"grievanceOfficer":{"oneOf":[{"type":"string"},{"type":"null"}]},"grievanceEmail":{"oneOf":[{"type":"string"},{"type":"null"}]},"grievancePhone":{"oneOf":[{"type":"string"},{"type":"null"}]},"missingForPublish":{"type":"array","items":{"type":"string"},"description":"What is still missing before the notice can be published."},"dataMap":{"oneOf":[{"type":"object"},{"type":"null"}]},"noticeUrl":{"type":"string","format":"uri"},"requestUrl":{"type":"string","format":"uri"},"frontDeskConsentUrl":{"type":"string","format":"uri"},"badgeUrl":{"type":"string","format":"uri"}},"required":["id","externalRef","slug","businessName","status","noticeVersion","languages","defaultLanguage","missingForPublish","noticeUrl","requestUrl","frontDeskConsentUrl","badgeUrl"]},"SiteUpsertRequest":{"type":"object","properties":{"externalRef":{"type":"string","description":"Your own id for the clinic (letters, numbers and `- _ . : @ +`, up to 100). The same value updates the same clinic.","maxLength":100},"businessName":{"type":"string","minLength":2,"maxLength":150},"sector":{"type":"string","enum":["healthcare","education","ecommerce","manufacturing","realestate","hospitality","wellness","professional","automobile","recruitment"],"default":"healthcare"},"websiteUrl":{"type":"string"},"languages":{"type":"array","items":{"type":"string","enum":["as","bn","brx","doi","en","gu","hi","kn","kok","ks","mai","ml","mni","mr","ne","or","pa","sa","sat","sd","ta","te","ur"]},"description":"English is always included."},"defaultLanguage":{"type":"string"},"grievanceOfficer":{"type":"string"},"grievanceEmail":{"type":"string","format":"email"},"grievancePhone":{"type":"string"},"responseDays":{"type":"integer","description":"1 to 90.","minimum":1,"maximum":90},"processors":{"type":"string","description":"Service providers you share data with (a notice needs this or a data map)."},"dataMap":{"type":"object","description":"Where data is stored, which services receive it and how long it is kept."},"brandColor":{"type":"string","description":"`#rrggbb`."},"clientEmail":{"type":"string","description":"For agency-managed clinics: the business that is also told about privacy requests."},"publish":{"type":"boolean","description":"Publish the notice (only when it is new or something in it changed)."}},"required":["externalRef","businessName"]},"SiteUpsertResponse":{"type":"object","properties":{"ok":{"const":true},"created":{"type":"boolean"},"published":{"type":"boolean"},"publishError":{"type":"string","description":"Why publishing did not happen (for example a missing grievance contact)."},"site":{"$ref":"#/components/schemas/Site"}},"required":["ok","created","published","site"]},"SiteList":{"type":"object","properties":{"ok":{"const":true},"total":{"type":"integer"},"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}},"required":["ok","total","sites"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"target_url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created"]}},"is_active":{"type":"boolean","description":"Switched off after 20 events in a row could not be delivered."},"last_triggered_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_status":{"oneOf":[{"type":"integer"},{"type":"null"}]},"failure_count":{"oneOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","target_url","events","is_active"]},"WebhookSetRequest":{"type":"object","properties":{"url":{"type":"string","description":"A public https:// address on your own server.","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created"]},"description":"Default: all four."}},"required":["url"]},"WebhookSetResponse":{"type":"object","properties":{"ok":{"const":true},"webhook":{"$ref":"#/components/schemas/Webhook"},"signingSecret":{"type":"string","description":"Shown once. Keep it on your server."}},"required":["ok","webhook","signingSecret"]},"WebhookGetResponse":{"type":"object","properties":{"ok":{"const":true},"webhook":{"oneOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created"]}}},"required":["ok","webhook","events"]},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"webhook_id":{"type":"string"},"site_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"event":{"type":"string"},"event_id":{"type":"string","description":"The same on every attempt."},"status":{"type":"string","enum":["pending","delivered","dead"]},"attempts":{"type":"integer"},"next_attempt_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_status":{"oneOf":[{"type":"integer","description":"What your server answered (0: no answer)."},{"type":"null"}]},"last_error":{"oneOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"delivered_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","webhook_id","event","event_id","status","attempts","created_at"]},"DeliveryList":{"type":"object","properties":{"ok":{"const":true},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["ok","deliveries"]},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"`evt_…`. The same on every retry: use it to ignore duplicates."},"event":{"type":"string","enum":["consent.recorded","consent.withdrawn","consent.confirmed","request.created","webhook.test"]},"siteId":{"type":"string","description":"The website this is about."},"externalRef":{"oneOf":[{"type":"string","description":"Your own clinic id (platform webhooks)."},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","description":"What happened. For `consent.*`: `consentId`, `subjectRef`, `action`, `choices`, `channel`, `givenBy`, `noticeVersion`, `recordedAt`; `consent.confirmed` adds `via`, `fromRegisteredNumber`, `confirmedAt`. For a walk-in (filed under their phone) `subjectRef` is null and `walkIn: true` with `phone`. For `request.created`: the request."}},"required":["id","event","siteId","createdAt","data"]},"SandboxConfirmRequest":{"type":"object","properties":{"siteId":{"type":"string"},"subjectRef":{"type":"string"},"via":{"type":"string","enum":["whatsapp","sms","missed_call"],"default":"whatsapp"}},"required":["siteId","subjectRef"]},"SandboxConfirmResponse":{"type":"object","properties":{"ok":{"const":true},"subjectRef":{"type":"string"},"via":{"type":"string"},"fromRegisteredNumber":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"simulated":{"const":true}},"required":["ok","subjectRef","via","simulated"]}}}}