Record and withdraw consent by email, phone or session id
Follow one person from an anonymous session to an account, then check consent by email and withdraw it by phone.
Follow one learner, Kavya, from her first visit to the day she withdraws. You record her answer under a session id, link her email address and phone number when she signs up, check consent by email, and withdraw by phone. Every call runs on your server.
Before you start#
- A published form with the key
kalpa-accountand the purposescourse-updates-by-emailandclass-reminders-by-sms. Use your own keys in their place. - A secret key with the scopes
subjects:link,subjects:read,subjects:withdrawandconsent:check. Grant them under Scopes on the key in Install. Recording and changing consent need no extra scope. - The
clientfrom Record consent from your server. - A library that writes phone numbers in E.164, such as
libphonenumber-jsfor Node.js orphonenumbersfor Python.
Follow one person#
-
Prepare each identifier the same way on every call.
Node.jsJavaScript import { parsePhoneNumber } from 'libphonenumber-js'; export function identifiersOf({ sessionId, user }) { return { session: { subjectType: 'SESSION_ID', subjectId: `sess_${sessionId}` }, account: { subjectType: 'USER_ID', subjectId: `usr_${user.id}` }, email: { subjectType: 'EMAIL', subjectId: user.email.trim().toLowerCase(), }, phone: { subjectType: 'PHONE', subjectId: parsePhoneNumber(user.phone, 'IN').number, }, }; }Python import phonenumbers from piedap_consent import Identifier def identifiers_of(session_id, user): phone = phonenumbers.parse(user.phone, "IN") return { "session": Identifier("SESSION_ID", f"sess_{session_id}"), "account": Identifier("USER_ID", f"usr_{user.id}"), "email": Identifier("EMAIL", user.email.strip().lower()), "phone": Identifier( "PHONE", phonenumbers.format_number( phone, phonenumbers.PhoneNumberFormat.E164 ), ), }The service hashes the text it receives.
+91 98460 11223and+919846011223are two different people to it. The prefixessess_andusr_keep a session id from ever equalling an account id. -
Record Kavya's first answer under her session id, with your own context in
metadata.Node.jsJavaScript const record = await client.recordConsent({ formKey: 'kalpa-account', subjectId: ids.session.subjectId, subjectType: 'SESSION_ID', countryCode: 'IN', decisions: [ { purposeKey: 'course-updates-by-email', granted: true }, { purposeKey: 'class-reminders-by-sms', granted: true }, ], metadata: { landingPage: '/courses/data-science', campaign: 'diwali' }, idempotencyKey: `first-answer-${ids.session.subjectId}`, }); session.consentId = record.consentId;Python from piedap_consent import Decision consent = client.record_consent( form_key="kalpa-account", subject_id=ids["session"].subject_id, subject_type="SESSION_ID", country_code="IN", decisions=[ Decision("course-updates-by-email", True), Decision("class-reminders-by-sms", True), ], metadata={"landingPage": "/courses/data-science", "campaign": "diwali"}, idempotency_key=f"first-answer-{ids['session'].subject_id}", ) session["consent_id"] = consent.consent_idcURLShell curl -X POST https://dev.dpconsent.com/consent/sdk/v1/consent \ -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "formKey": "kalpa-account", "subjectId": "sess_4Hq9x2", "subjectType": "SESSION_ID", "countryCode": "IN", "decisions": [ { "purposeKey": "course-updates-by-email", "granted": true }, { "purposeKey": "class-reminders-by-sms", "granted": true } ], "metadata": { "campaign": "diwali" } }' -
When she signs up, link her account id, email address and phone number to the session's records.
Node.jsJavaScript const linked = await client.linkIdentifiers( ids.session.subjectId, 'SESSION_ID', [ids.account, ids.email, ids.phone], { idempotencyKey: `sign-up-${ids.account.subjectId}` }, ); // { records: 1, added: 3 }Python linked = client.link_identifiers( ids["session"].subject_id, "SESSION_ID", [ids["account"], ids["email"], ids["phone"]], idempotency_key=f"sign-up-{ids['account'].subject_id}", ) # {"records": 1, "added": 3}cURLShell curl -X POST https://dev.dpconsent.com/consent/sdk/v1/subjects/link \ -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "subjectId": "sess_4Hq9x2", "subjectType": "SESSION_ID", "identifiers": [ { "subjectType": "USER_ID", "subjectId": "usr_8f2K1xQz" }, { "subjectType": "EMAIL", "subjectId": "kavya.menon@example.in" }, { "subjectType": "PHONE", "subjectId": "+919846011223" } ] }' -
Check consent by email before you send a course update.
Node.jsJavaScript const check = await client.checkConsent({ subjectId: ids.email.subjectId, subjectType: 'EMAIL', purposeKey: 'course-updates-by-email', }); if (check.allowed) await sendCourseUpdate(user);Python check = client.check_consent( ids["email"].subject_id, "EMAIL", "course-updates-by-email" ) if check.allowed: send_course_update(user) -
Find her records by phone.
Node.jsJavaScript const found = await client.findSubject(ids.phone.subjectId, 'PHONE'); // records[0].matchedBy is ['PHONE']Python found = client.find_subject(ids["phone"].subject_id, "PHONE") # found["records"][0]["matchedBy"] == ["PHONE"] -
Withdraw everything by phone when she replies STOP to a class reminder.
Node.jsJavaScript const { withdrawn } = await client.withdrawSubject( ids.phone.subjectId, 'PHONE', { reason: 'Replied STOP to an SMS', idempotencyKey: `stop-${ids.phone.subjectId}`, }, ); // withdrawn is 1Python withdrawn = client.withdraw_subject( ids["phone"].subject_id, "PHONE", reason="Replied STOP to an SMS", idempotency_key=f"stop-{ids['phone'].subject_id}", )cURLShell curl -X POST https://dev.dpconsent.com/consent/sdk/v1/subjects/withdraw \ -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "subjectId": "+919846011223", "subjectType": "PHONE", "reason": "Replied STOP to an SMS" }' -
Run the check from step 4 again. It now answers
allowed: falsewithreason: "withdrawn".
What each call did#
| Step | What the service did |
|---|---|
| Record | Kept one record for the session on this form, with a keyed hash of sess_4Hq9x2 and your metadata. |
| Link | Attached the three new identifiers to every live record of the session and sealed a LINKED event in each record's history. |
| Check | Read the records held under the email address or linked to it. |
| Find | Listed those records, with matchedBy naming the identifier type that reached each one. |
| Withdraw | Set every record still in force to WITHDRAWN and refused every optional purpose. It sent one consent.withdrawn webhook per record. |
Link the new identifiers instead of recording again. A second write under her email address for the same form makes a second record, and the session's answer stays apart from it. Later answers can use her account id as the subject, with the email address and phone number in identifiers.
Do the same from the browser
The banner records under a random id it makes for the browser. To add your session id from the page, call PiedapConsent.setIdentifiers() with a SESSION_ID entry. An email address, phone number or account id sent from a browser needs an identity proof from your server. See Record consent for signed-in visitors.