Consent Docs

Attach your own data to a record

Keep your own context with a consent record, such as a campaign, a landing page or an order number, and read it back from your server.

How-to1 min readFor web, backend and mobile developers

Send metadata with a write to keep your own context next to the answer: a campaign, a landing page, an order number or your app's version. It is context only. To find, withdraw or erase a person by an email address, phone number or session id, link it as an identifier.

Before you start#

Send it with the answers#

  1. Add metadata to the write. It is any JSON object.

    Node.jsJavaScript
    const record = await client.recordConsent({
      formKey: 'kalpa-account',
      subjectId: 'usr_8f2K1xQz',
      subjectType: 'USER_ID',
      countryCode: 'IN',
      decisions: [{ purposeKey: 'course-updates-by-email', granted: true }],
      metadata: {
        campaign: 'diwali',
        landingPage: '/courses/data-science',
        orderNumber: 'KA-2026-11840',
      },
    });
    Python
    consent = client.record_consent(
        form_key="kalpa-account",
        subject_id="usr_8f2K1xQz",
        subject_type="USER_ID",
        country_code="IN",
        decisions=[Decision("course-updates-by-email", True)],
        metadata={
            "campaign": "diwali",
            "landingPage": "/courses/data-science",
            "orderNumber": "KA-2026-11840",
        },
    )
  2. On a web page, set the fields before the visitor answers. The runtime sends them with the next answer.

    JavaScript
    PiedapConsent.setMetadata({ campaign: 'diwali', storeRegion: 'south' });

Read it back#

Read the record with a secret key. A browser never receives metadata.

Node.jsJavaScript
const record = await client.getConsent('cns_3f1c9a7e2b8d4c6f');
console.log(record.metadata.orderNumber);
cURLShell
export CONSENT_ID='cns_3f1c9a7e2b8d4c6f'

curl https://dev.dpconsent.com/consent/sdk/v1/consent/$CONSENT_ID \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY"

Your team sees the same fields on the record in the console. Consent webhooks and receipts do not carry them.

Replace it#

Send metadata with the next change of answers. The change needs at least one decision.

Shell
curl -X PATCH https://dev.dpconsent.com/consent/sdk/v1/consent/$CONSENT_ID \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decisions": [
      { "purposeKey": "class-reminders-by-sms", "granted": true }
    ],
    "metadata": { "campaign": "pongal", "orderNumber": "KA-2027-00412" }
  }'

Rules#

Rule Detail
Size Up to 8,192 bytes of JSON from a server, and 6,144 bytes through setMetadata(). A larger value from a server is refused with 400 METADATA_TOO_LARGE. setMetadata() returns false and keeps the old value.
Replacement A write that sends metadata replaces the whole object. A write without it keeps the object as it is.
History Each write keeps the metadata it carried with that step of the record's history.
Fields the runtime adds The browser runtime adds sdk and layer.
Storage Kept as you send it, not hashed. Never put an email address, phone number, token or other personal data in it.
Erasure Erasing the person clears it. See Withdraw or erase a person.

↑↓ to move, Enter to open