4

Integration & API

SL-03

How a departmental system records consent without reimplementing any of it. The contract is deliberately narrow: you tell us what was shown and what was agreed, and we own the artefact, the trail and the propagation.

DischargesS.6S.5R.3
API keys
4
Active
3
Calls, 30 days
5,16,754
Webhook subscribers
32

Endpoints

POST/v1/consents
Record a consent artefact
Requires the notice version shown to the principal. A grant submitted without one is rejected — you cannot evidence informed consent after the fact.
GET/v1/consents/{reference}
Fetch an artefact with its full event trail
The hash chain is returned so a caller can verify immutability independently.
POST/v1/consents/{reference}/withdraw
Withdraw consent
Returns the propagation plan — the list of systems that must stop processing, and by when.
GET/v1/purposes
List active purposes with legal basis
Purposes on legitimate use are flagged so a caller does not ask for consent it does not need.
GET/v1/notices/{id}
Fetch a published notice in a given language
Always fetch at render time. Caching a notice is how a stale version ends up on screen.
GET/v1/principals/{id}/consents
All artefacts held for a principal
Used by the Data Principal portal and by any Consent Manager holding a link.

Recording a consent

TypeScript
// Recording a consent artefact. The notice version is not optional —
// it is what makes the consent evidentially "informed" under Section 5.
const res = await fetch("https://api.aiventuretech.io/v1/consents", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CONSENT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": submissionId,
  },
  body: JSON.stringify({
    principalRef: "FAM-8827-4410",        // your identifier, never an Aadhaar number
    noticeId: "not-01",
    noticeVersion: "3.2",
    language: "hi",                        // the language actually displayed
    channel: "kiosk",
    purposes: [
      { id: "pur-03", agreed: true },
      { id: "pur-04", agreed: true },
    ],
    collectedAt: new Date().toISOString(),
  }),
});

const artefact = await res.json();
// artefact.reference  → show this to the principal
// artefact.hash       → chained to the previous event; verify if you wish
// artefact.withdrawalUrl → must be offered on the same channel