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.
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#
- A secret key, and the
clientfrom Record consent from your server.
Send it with the answers#
-
Add
metadatato 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", }, ) -
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.
const record = await client.getConsent('cns_3f1c9a7e2b8d4c6f');
console.log(record.metadata.orderNumber);export CONSENT_ID='cns_3f1c9a7e2b8d4c6f'
curl https://test.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.
curl -X PATCH https://test.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. |