Skip to main content
Use this endpoint to record a patient consent document. Consents are scoped to one of four categories — privacy, treatment, research, or advance directive — and can include verification details confirming the patient signed, plus provisions that specify what is permitted or denied and for how long.

​
Request

POST https://api.clinikapi.com/v1/consents

​
Headers

​
x-api-key
string
required
Your ClinikAPI secret key (clk_live_* or clk_test_*).
​
Content-Type
string
required
Must be application/json.

​
Body

​
patientId
string
required
The ID of the patient giving consent (e.g. pt_abc123).
​
scope
string
required
The consent scope. One of: patient-privacy, treatment, research, adr.
​
category
string | string[]
required
Consent category code or array of codes (e.g. "hipaa-notice", ["treatment-consent", "surgical-consent"]).
​
status
string
Consent status. One of: draft, proposed, active, rejected, inactive. Defaults to active.
​
dateTime
string
ISO 8601 timestamp of when consent was given.
​
performerId
string
ID of the practitioner or patient who is the consenting party.
​
organizationId
string
ID of the custodian organization holding the consent.
​
policyUri
string
URI of the policy document the patient is consenting to (e.g. "https://clinic.com/hipaa-notice").
​
verification
object
Verification details confirming the consent was obtained.
​
provision
object
Rules defining what is permitted or denied under this consent.

​
Response

Returns 201 Created with the new consent resource wrapped in the standard envelope.
​
data.id
string
The generated consent ID (e.g. consent_abc123).
​
data.patientId
string
Patient reference.
​
data.scope
string
Consent scope as submitted.
​
data.status
string
Consent status.
​
data.provision
object
Provision rules, if provided.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Examples

​
curl

curl -X POST https://api.clinikapi.com/v1/consents \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "pt_abc123",
    "status": "active",
    "scope": "patient-privacy",
    "category": "hipaa-notice",
    "policyUri": "https://clinic.com/hipaa-notice",
    "verification": {
      "verified": true,
      "verifiedWith": "pt_abc123",
      "verificationDate": "2025-01-15T10:00:00Z"
    }
  }'

​
TypeScript SDK

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

const { data } = await clinik.consents.sign({
  patientId: 'pt_abc123',
  status: 'active',
  scope: 'patient-privacy',
  category: 'hipaa-notice',
  policyUri: 'https://clinic.com/hipaa-notice',
  verification: {
    verified: true,
    verifiedWith: 'pt_abc123',
    verificationDate: '2025-01-15T10:00:00Z',
  },
});

console.log(data.id); // consent_abc123