Developer kit

API reference

Base address https://zeroclauseai.com. Send your key as Authorization: Bearer zc_live_… from your server only. A field marked * is required.

The same description as a file for Postman or a code generator: /openapi.json. Guides and the SDK: developer kit.

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*stringThe website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.
subjectRefstringYour id for the patient (letters, numbers and `- _ . : @ +`, up to 100 characters).
phonestringA walk-in's mobile number (10 digits or +91…). Looked up by a keyed hash; never stored.

Response 200 (JSON)

ok*true
found*booleanfalse when there is no counting choice.
subjectRefstring | null
lookedUpBysubjectRef | 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
notestring
walkInboolean
actionaccept_all | reject_all | custom | withdraw
choicesChoicesWhat the person agreed to. A missing key means no. The response also carries `necessary: true`.
remindersbooleanAppointment reminders and updates.
marketingbooleanOffers and news. Never allowed for a child.
analyticsbooleanAnalytics. Never allowed for a child.
givenByGivenBy
role*self | parent | guardian
namestringRequired for a parent or guardian.
relationstringFor example Mother.
adultConfirmedbooleanMust be true for a parent or guardian: they are an adult and the lawful parent or guardian.
noticeVersioninteger
noticeChangedbooleanA newer notice was published since: ask again when you next see them.
channelstring | null
recordedAtstring
languagestring | null
confirmationConfirmation | 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*stringThe website (slug or id). `site` is also accepted.
subjectRefstringYour id for the patient.
actionaccept_all | reject_all | custom | withdraw`accept_all` means reminders and offers (reminders only for a child).
choicesChoicesWhat the person agreed to. A missing key means no. The response also carries `necessary: true`.
remindersbooleanAppointment reminders and updates.
marketingbooleanOffers and news. Never allowed for a child.
analyticsbooleanAnalytics. Never allowed for a child.
channelapp | whatsapp | web | api | qr
languagestringThe language the patient saw (a code the clinic offers).
phonestringThe patient's mobile number, so their confirmation can be checked against it. Stored only as a keyed hash.
assistedBystringThe staff member who helped, when it was filled in on the clinic's device.
minorbooleanThe patient is under 18: `givenBy` must be a parent.
givenByGivenBy
role*self | parent | guardian
namestringRequired for a parent or guardian.
relationstringFor example Mother.
adultConfirmedbooleanMust be true for a parent or guardian: they are an adult and the lawful parent or guardian.

Response 200 (JSON)

ok*true
consentId*integer
subjectRefstring | null
action*accept_all | reject_all | custom | withdraw
choices*object
channel*string
givenByGivenBy
role*self | parent | guardian
namestringRequired for a parent or guardian.
relationstringFor example Mother.
adultConfirmedbooleanMust be true for a parent or guardian: they are an adult and the lawful parent or guardian.
noticeVersion*integer
recordedAt*string
assistedBystring
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/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[]
onlyNeedingActionbooleanReturn 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*stringThe 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*booleantrue 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

Notice

The published privacy notice, to show inside your own app.

get/api/v1/noticenotice:read

The published privacy notice

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.

Query

siteId*stringThe website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.
langas | bn | brx | doi | en | gu | hi | kn | kok | ks | mai | ml | mni | mr | ne | or | pa | sa | sat | sd | ta | te | urA language code the clinic has switched on. Defaults to the clinic's default language.

Response 200 (JSON)

ok*true
site*object
noticeUrl*string
requestUrl*string
frontDeskConsentUrl*stringThe poster / walk-in consent page.
notice*object
dataMapobject | nullWhere data is stored, which services receive it, how long it is kept. null when not set.
outreachMessagesobjectReady WhatsApp, SMS and email messages for telling existing patients about the notice.

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 delivery409 Not possible right now

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*stringThe 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*stringSo the business can reply.
phonestring
messagestringRequired (at least 5 characters) for `correct`, `nominate` and `grievance`.

Response 200 (JSON)

ok*true
request*object

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
incidentTypeunauthorized_access | data_leak | ransomware | lost_device | wrong_recipient | other
detectedAtstringWhen you found out: within the last 90 days, not in the future. Default: now.
affectedCountintegerIf known.
descriptionstringWhat was found, in plain words.

Response 200 (JSON)

ok*true
incidentRef*stringFor example `INC-20261106-A1B2C3`.
incidentType*unauthorized_access | data_leak | ransomware | lost_device | wrong_recipient | other
detectedAt*string
deadlines*object
breachPlanUrlstring
drafts*objectDrafts 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*stringThe website: its slug (for example `my-clinic-1a2b3c`) or its id. With a test key, your sandbox website.

Response 200 (JSON)

displays*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 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
displayIdstringNeeded only when the clinic has more than one screen.
phonestring
minorboolean
assistedBystring
minutesintegerHow 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

externalRefstringYour own id for one clinic.

Response 200 (JSON)

ok*true
total*integer
sites*Site[]
id*string
externalRef*string | null
slug*string
businessName*string
sectorhealthcare | education | ecommerce | manufacturing | realestate | hospitality | wellness | professional | automobile | recruitment
websiteUrlstring | null
status*draft | published
noticeVersion*integer
publishedAtstring | 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
grievanceOfficerstring | null
grievanceEmailstring | null
grievancePhonestring | null
missingForPublish*string[]What is still missing before the notice can be published.
dataMapobject | 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*stringYour own id for the clinic (letters, numbers and `- _ . : @ +`, up to 100). The same value updates the same clinic.
businessName*string
sectorhealthcare | education | ecommerce | manufacturing | realestate | hospitality | wellness | professional | automobile | recruitment
websiteUrlstring
languagesas | 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.
defaultLanguagestring
grievanceOfficerstring
grievanceEmailstring
grievancePhonestring
responseDaysinteger1 to 90.
processorsstringService providers you share data with (a notice needs this or a data map).
dataMapobjectWhere data is stored, which services receive it and how long it is kept.
brandColorstring`#rrggbb`.
clientEmailstringFor agency-managed clinics: the business that is also told about privacy requests.
publishbooleanPublish the notice (only when it is new or something in it changed).

Response 200 (JSON)

ok*true
created*boolean
published*boolean
publishErrorstringWhy publishing did not happen (for example a missing grievance contact).
site*Site
id*string
externalRef*string | null
slug*string
businessName*string
sectorhealthcare | education | ecommerce | manufacturing | realestate | hospitality | wellness | professional | automobile | recruitment
websiteUrlstring | null
status*draft | published
noticeVersion*integer
publishedAtstring | 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
grievanceOfficerstring | null
grievanceEmailstring | null
grievancePhonestring | null
missingForPublish*string[]What is still missing before the notice can be published.
dataMapobject | 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*stringA public https:// address on your own server.
eventsconsent.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*booleanSwitched off after 20 events in a row could not be delivered.
last_triggered_atstring | null
last_statusinteger | null
failure_countinteger | null
created_atstring
signingSecret*stringShown 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.

Response 200 (JSON)

ok*true

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_idstring | null
event*string
event_id*stringThe same on every attempt.
status*pending | delivered | dead
attempts*integer
next_attempt_atstring | null
last_statusinteger | null
last_errorstring | null
created_at*string
delivered_atstring | 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*stringThe delivery id from the log.

Response 200 (JSON)

ok*true
status*integerWhat 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

Sandbox

Only with a test key on your sandbox website.

post/api/v1/sandbox/confirmconsent:write

Act as the patient who confirms from their own phone

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.

Request body (JSON)

siteId*string
subjectRef*string
viawhatsapp | sms | missed_call

Response 200 (JSON)

ok*true
subjectRef*string
via*string
fromRegisteredNumberboolean | null
simulated*true

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 now

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*stringThe website this is about.
externalRefstring | null
createdAt*string
data*objectWhat 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.