Consent Docs

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.

Tutorial2 min readFor web, backend and mobile developers

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-account and the purposes course-updates-by-email and class-reminders-by-sms. Use your own keys in their place.
  • A secret key with the scopes subjects:link, subjects:read, subjects:withdraw and consent:check. Grant them under Scopes on the key in Install. Recording and changing consent need no extra scope.
  • The client from Record consent from your server.
  • A library that writes phone numbers in E.164, such as libphonenumber-js for Node.js or phonenumbers for Python.

Follow one person#

  1. 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 11223 and +919846011223 are two different people to it. The prefixes sess_ and usr_ keep a session id from ever equalling an account id.

  2. 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_id
    cURLShell
    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" }
      }'
  3. 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" }
        ]
      }'
  4. 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)
  5. 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"]
  6. 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 1
    Python
    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"
      }'
  7. Run the check from step 4 again. It now answers allowed: false with reason: "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.

Next steps#

↑↓ to move, Enter to open