Consent
Record, check and find consent for your own patients or customers.
get/api/v1/consentconsent:read
Is this person's consent on file?
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.
Query
| siteId* | string | The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website. |
| subjectRef | string | Your id for the patient (letters, numbers and `- _ . : @ +`, up to 100 characters). |
| phone | string | A walk-in's mobile number (10 digits or +91…). Looked up by a keyed hash; never stored. |
Response 200 (JSON)
| ok* | true | |
| found* | boolean | false when there is no counting choice. |
| subjectRef | string | null | |
| lookedUpBy | subjectRef | phone | subjectRef+phone | |
| status* | consented | withdrawn | no_record | awaiting_confirmation | `awaiting_confirmation`: a walk-in typed their number but has not confirmed from that phone yet. Treat it as no consent. |
| canSendReminders* | boolean | |
| canSendMarketing* | boolean | |
| note | string | |
| walkIn | boolean | |
| action | accept_all | reject_all | custom | withdraw | |
| choices | Choices | What the person agreed to. A missing key means no. The response also carries `necessary: true`. |
| reminders | boolean | Appointment reminders and updates. |
| marketing | boolean | Offers and news. Never allowed for a child. |
| analytics | boolean | Analytics. Never allowed for a child. |
| givenBy | GivenBy | |
| role* | self | parent | guardian | |
| name | string | Required for a parent or guardian. |
| relation | string | For example Mother. |
| adultConfirmed | boolean | Must be true for a parent or guardian: they are an adult and the lawful parent or guardian. |
| noticeVersion | integer | |
| noticeChanged | boolean | A newer notice was published since: ask again when you next see them. |
| channel | string | null | |
| recordedAt | string | |
| language | string | null | |
| confirmation | Confirmation | null | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery
post/api/v1/consentconsent:write
Record a choice you collected yourself
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.
Request body (JSON)
| siteId* | string | The website (slug or id). `site` is also accepted. |
| subjectRef | string | Your id for the patient. |
| action | accept_all | reject_all | custom | withdraw | `accept_all` means reminders and offers (reminders only for a child). |
| choices | Choices | What the person agreed to. A missing key means no. The response also carries `necessary: true`. |
| reminders | boolean | Appointment reminders and updates. |
| marketing | boolean | Offers and news. Never allowed for a child. |
| analytics | boolean | Analytics. Never allowed for a child. |
| channel | app | whatsapp | web | api | qr | |
| language | string | The language the patient saw (a code the clinic offers). |
| phone | string | The patient's mobile number, so their confirmation can be checked against it. Stored only as a keyed hash. |
| assistedBy | string | The staff member who helped, when it was filled in on the clinic's device. |
| minor | boolean | The patient is under 18: `givenBy` must be a parent. |
| givenBy | GivenBy | |
| role* | self | parent | guardian | |
| name | string | Required for a parent or guardian. |
| relation | string | For example Mother. |
| adultConfirmed | boolean | Must be true for a parent or guardian: they are an adult and the lawful parent or guardian. |
Response 200 (JSON)
| ok* | true | |
| consentId* | integer | |
| subjectRef | string | null | |
| action* | accept_all | reject_all | custom | withdraw | |
| choices* | object | |
| channel* | string | |
| givenBy | GivenBy | |
| role* | self | parent | guardian | |
| name | string | Required for a parent or guardian. |
| relation | string | For example Mother. |
| adultConfirmed | boolean | Must be true for a parent or guardian: they are an adult and the lawful parent or guardian. |
| noticeVersion* | integer | |
| recordedAt* | string | |
| assistedBy | string | |
| confirm* | ConfirmInfo | null | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery409 Not possible right now429 Too fast503 Our side
post/api/v1/consent-linkconsent:write
A personal consent link or QR for one patient
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.
Request body (JSON)
| siteId* | string | |
| subjectRef* | string | |
| days | integer | 1 to 30, default 7. |
| phone | string | |
| assistedBy | string | |
| minor | boolean | |
Response 200 (JSON)
| ok* | true | |
| subjectRef* | string | |
| url* | string | Open it in a browser, or show it as a QR. |
| expiresAt* | string | |
| phoneRegistered | boolean | |
| assisted | boolean | |
| minor | boolean | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery409 Not possible right now
post/api/v1/preferences-linkconsent:write
A patient's own "My privacy choices" page
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.
Request body (JSON)
| siteId* | string | |
| subjectRef* | string | |
| days | integer | 1 to 365, default 180. |
| phone | string | |
| minor | boolean | |
Response 200 (JSON)
| ok* | true | |
| subjectRef* | string | |
| url* | string | The patient's page. Send it to that patient only. |
| expiresAt* | string | |
| phoneRegistered | boolean | |
| minor | boolean | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery409 Not possible right now
post/api/v1/consent/lookupconsent:read
Consent of up to 500 patients at once
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.
Request body (JSON)
| siteId* | string | |
| subjectRefs* | string[] | |
| onlyNeedingAction | boolean | Return only the patients you still have to ask. |
Response 200 (JSON)
| ok* | true | |
| checked* | integer | |
| count* | integer | |
| needs* | object | |
| noticeVersion* | integer | |
| patients* | PatientConsent[] | |
| subjectRef* | string | |
| status* | consented | withdrawn | no_record | |
| canSendReminders* | boolean | |
| canSendMarketing* | boolean | |
| noticeChanged* | boolean | |
| child* | boolean | |
| confirmed* | boolean | null | |
| recordedAt* | string | null | |
| channel* | string | null | |
| needs* | ask | ask_again | null | `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). |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery
get/api/v1/consent/summaryconsent:read
Totals for the whole website or clinic
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.
Query
| siteId* | string | The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website. |
Response 200 (JSON)
| ok* | true | |
| noticeVersion* | integer | |
| people* | integer | |
| consented* | integer | |
| withdrawn* | integer | |
| canSendReminders* | integer | |
| canSendMarketing* | integer | |
| children* | integer | |
| confirmedFromOwnPhone* | integer | |
| awaitingConfirmation* | integer | |
| needAskingAgain* | integer | |
| walkIns* | integer | |
| truncated* | boolean | true when there were more than 100,000 records and only the newest were counted. |
Errors: 401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery500 Our side
Requests
People asking to see, correct or erase their data.
get/api/v1/requestsrequests:read
The latest 200 privacy requests
Needs a key with the requests:read permission.
Query
| siteId* | string | The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website. |
Response 200 (JSON)
| ok* | true | |
| total* | integer | |
| requests* | object[] | |
Errors: 401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery500 Our side
post/api/v1/requestsrequests:write
Send a privacy request on someone's behalf
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.
Request body (JSON)
| siteId* | string | |
| kind* | access | correct | erase | withdraw | nominate | grievance | |
| name* | string | |
| email* | string | So the business can reply. |
| phone | string | |
| message | string | Required (at least 5 characters) for `correct`, `nominate` and `grievance`. |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery409 Not possible right now500 Our side
Breach
Report a suspected breach: starts the 6-hour and 72-hour clocks. Nothing is sent to CERT-In or the Board for you.
post/api/v1/breachbreach:write
Report a suspected breach
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.
Request body (JSON)
| siteId* | string | |
| incidentType | unauthorized_access | data_leak | ransomware | lost_device | wrong_recipient | other | |
| detectedAt | string | When you found out: within the last 90 days, not in the future. Default: now. |
| affectedCount | integer | If known. |
| description | string | What was found, in plain words. |
Response 200 (JSON)
| ok* | true | |
| incidentRef* | string | For example `INC-20261106-A1B2C3`. |
| incidentType* | unauthorized_access | data_leak | ransomware | lost_device | wrong_recipient | other | |
| detectedAt* | string | |
| deadlines* | object | |
| breachPlanUrl | string | |
| drafts* | object | Drafts with [blanks]. Fill them in and have your lawyer check them. |
| checklist* | string[] | |
| note* | string | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery
Counter screen
The optional screen at the desk that shows a patient's personal consent QR.
get/api/v1/displayconsent:read
The paired counter screens
A screen is online when it asked for its state in the last 20 seconds. Needs a key with the consent:read permission.
Query
| siteId* | string | The website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website. |
Errors: 401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery
post/api/v1/displayconsent:write
Show or clear a patient's QR on a counter screen
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.
Request body (JSON)
| siteId* | string | |
| action* | "show" | |
| subjectRef* | string | |
| displayId | string | Needed only when the clinic has more than one screen. |
| phone | string | |
| minor | boolean | |
| assistedBy | string | |
| minutes | integer | How long the QR works: 1 to 120, default 10. |
Response 200 (JSON)
| ok* | true | |
| displayId* | string | |
| expiresAt* | string | |
| online* | boolean | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key402 The account's plan has paused after the grace period403 The key may not do this404 No such website, webhook or delivery409 Not possible right now503 Our side
Sites (platform)
Software that sets up many clinics: create and update them by your own id. Needs a live platform key.
get/api/v1/sitessites:manage
Your clinics
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.
Query
| externalRef | string | Your own id for one clinic. |
Response 200 (JSON)
| ok* | true | |
| total* | integer | |
| sites* | Site[] | |
| id* | string | |
| externalRef* | string | null | |
| slug* | string | |
| businessName* | string | |
| sector | healthcare | education | ecommerce | manufacturing | realestate | hospitality | wellness | professional | automobile | recruitment | |
| websiteUrl | string | null | |
| status* | draft | published | |
| noticeVersion* | integer | |
| publishedAt | string | null | |
| languages* | as | bn | brx | doi | en | gu | hi | kn | kok | ks | mai | ml | mni | mr | ne | or | pa | sa | sat | sd | ta | te | ur[] | |
| defaultLanguage* | string | |
| grievanceOfficer | string | null | |
| grievanceEmail | string | null | |
| grievancePhone | string | null | |
| missingForPublish* | string[] | What is still missing before the notice can be published. |
| dataMap | object | null | |
| noticeUrl* | string | |
| requestUrl* | string | |
| frontDeskConsentUrl* | string | |
| badgeUrl* | string | |
Errors: 401 No key, or not a ZeroClause key403 The key may not do this500 Our side
post/api/v1/sitessites:manage
Create or update a clinic (safe to repeat)
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.
Request body (JSON)
| externalRef* | string | Your own id for the clinic (letters, numbers and `- _ . : @ +`, up to 100). The same value updates the same clinic. |
| businessName* | string | |
| sector | healthcare | education | ecommerce | manufacturing | realestate | hospitality | wellness | professional | automobile | recruitment | |
| websiteUrl | string | |
| languages | as | bn | brx | doi | en | gu | hi | kn | kok | ks | mai | ml | mni | mr | ne | or | pa | sa | sat | sd | ta | te | ur[] | English is always included. |
| defaultLanguage | string | |
| grievanceOfficer | string | |
| grievanceEmail | string | |
| grievancePhone | string | |
| responseDays | integer | 1 to 90. |
| processors | string | Service providers you share data with (a notice needs this or a data map). |
| dataMap | object | Where data is stored, which services receive it and how long it is kept. |
| brandColor | string | `#rrggbb`. |
| clientEmail | string | For agency-managed clinics: the business that is also told about privacy requests. |
| publish | boolean | Publish the notice (only when it is new or something in it changed). |
Response 200 (JSON)
| ok* | true | |
| created* | boolean | |
| published* | boolean | |
| publishError | string | Why publishing did not happen (for example a missing grievance contact). |
| site* | Site | |
| id* | string | |
| externalRef* | string | null | |
| slug* | string | |
| businessName* | string | |
| sector | healthcare | education | ecommerce | manufacturing | realestate | hospitality | wellness | professional | automobile | recruitment | |
| websiteUrl | string | null | |
| status* | draft | published | |
| noticeVersion* | integer | |
| publishedAt | string | null | |
| languages* | as | bn | brx | doi | en | gu | hi | kn | kok | ks | mai | ml | mni | mr | ne | or | pa | sa | sat | sd | ta | te | ur[] | |
| defaultLanguage* | string | |
| grievanceOfficer | string | null | |
| grievanceEmail | string | null | |
| grievancePhone | string | null | |
| missingForPublish* | string[] | What is still missing before the notice can be published. |
| dataMap | object | null | |
| noticeUrl* | string | |
| requestUrl* | string | |
| frontDeskConsentUrl* | string | |
| badgeUrl* | string | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key403 The key may not do this500 Our side503 Our side
Webhooks
One webhook address for all your clinics, and its delivery log. Needs a live platform key.
get/api/v1/webhooksites:manage
Your webhook address
Needs a live platform key with the sites:manage permission.
Response 200 (JSON)
| ok* | true | |
| webhook* | Webhook | null | |
| events* | consent.recorded | consent.withdrawn | consent.confirmed | request.created[] | |
Errors: 401 No key, or not a ZeroClause key403 The key may not do this500 Our side503 Our side
post/api/v1/webhooksites:manage
Set or replace your webhook address
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.
Request body (JSON)
| url* | string | A public https:// address on your own server. |
| events | consent.recorded | consent.withdrawn | consent.confirmed | request.created[] | Default: all four. |
Response 200 (JSON)
| ok* | true | |
| webhook* | Webhook | |
| id* | string | |
| target_url* | string | |
| events* | consent.recorded | consent.withdrawn | consent.confirmed | request.created[] | |
| is_active* | boolean | Switched off after 20 events in a row could not be delivered. |
| last_triggered_at | string | null | |
| last_status | integer | null | |
| failure_count | integer | null | |
| created_at | string | |
| signingSecret* | string | Shown once. Keep it on your server. |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key403 The key may not do this503 Our side
delete/api/v1/webhooksites:manage
Remove your webhook
Needs a live platform key with the sites:manage permission.
Errors: 401 No key, or not a ZeroClause key403 The key may not do this500 Our side503 Our side
get/api/v1/webhook/deliveriessites:manage
The delivery log of your webhook
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.
Response 200 (JSON)
| ok* | true | |
| deliveries* | Delivery[] | |
| id* | string | |
| webhook_id* | string | |
| site_id | string | null | |
| event* | string | |
| event_id* | string | The same on every attempt. |
| status* | pending | delivered | dead | |
| attempts* | integer | |
| next_attempt_at | string | null | |
| last_status | integer | null | |
| last_error | string | null | |
| created_at* | string | |
| delivered_at | string | null | |
Errors: 401 No key, or not a ZeroClause key403 The key may not do this500 Our side503 Our side
post/api/v1/webhook/deliveriessites:manage
Send a dead event again
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.
Request body (JSON)
| id* | string | The delivery id from the log. |
Response 200 (JSON)
| ok* | true | |
| status* | integer | What your server answered (0: no answer). |
| delivered* | boolean | |
Errors: 400 The request is wrong401 No key, or not a ZeroClause key403 The key may not do this404 No such website, webhook or delivery409 Not possible right now500 Our side503 Our side
Webhook events
We send a signed POST to your webhook address. Check the signature before you trust it (see the developer kit for ready code).
consent.recorded
A person gave or changed their consent.
Answer 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.
**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.
consent.withdrawn
A person withdrew or refused consent.
Answer 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.
**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.
consent.confirmed
A person confirmed their choice from their own phone.
Answer 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.
**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.
request.created
A privacy request arrived.
Answer 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.
**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.
Event body (JSON)
| id* | string | `evt_…`. The same on every retry: use it to ignore duplicates. |
| event* | consent.recorded | consent.withdrawn | consent.confirmed | request.created | webhook.test | |
| siteId* | string | The website this is about. |
| externalRef | string | null | |
| createdAt* | string | |
| data* | object | 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. |