Check consent before you process

Call the consent check from your server right before you use a person's data for a purpose, such as before one SMS of a campaign goes out. It answers yes or no, says why, and names the records behind the answer.

Before you start#

A secret key with the scope Check whether a person allows a purpose (consent:check). Tick it under Scopes on the key in Install. Without it the call answers 403 SCOPE_REQUIRED.
Keep one key for checks only and use it nowhere else. Every secret key can also read and write records.
The client from Record consent from your server.
Consent recorded under the identifier you check, or linked to it. A consent recorded only under a cookie id is not found by a customer id. See Identifiers.

Check one person#

Choose the identifier your system holds. Write phone numbers in E.164, such as +919846011223.
Add the person's other identifiers in alsoKnownAs, up to four, so a refusal recorded under any of them counts.

Call the check with the purpose key. Add partnerKey when you share with one partner.

Node.jsJavaScript

const check = await client.checkConsent({
  subjectId: customer.cif,
  subjectType: 'USER_ID',
  alsoKnownAs: [{ subjectType: 'PHONE', subjectId: customer.mobile }],
  purposeKey: 'offers-by-sms',
});

if (!check.allowed) {
  skipMessage(customer, check.reason);
} else {
  await sendOffer(customer, check.basedOn[0]);
}

Python

from piedap_consent import Identifier

check = client.check_consent(
    customer.cif,
    "USER_ID",
    "offers-by-sms",
    also_known_as=[Identifier("PHONE", customer.mobile)],
)

if not check.allowed:
    skip_message(customer, check.reason)
else:
    send_offer(customer, check.based_on[0])

cURLShell

curl -X POST https://console.dpconsent.com/consent/sdk/v1/consent/check \
  -H "Authorization: Bearer $PIEDAP_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CIF00412873",
    "subjectType": "USER_ID",
    "alsoKnownAs": [
      { "subjectType": "PHONE", "subjectId": "+919846011223" }
    ],
    "purposeKey": "offers-by-sms"
  }'

Go ahead only when allowed is true. Keep basedOn[0].consentId and proofHash in your own processing log.

Read the answer#

`reason`	What to do
`granted`	Go ahead.
`refused`, `withdrawn`, `erased`	Do not process, and do not ask again by this channel.
`expired`	Do not process. Ask the person again.
`pending_confirmation`	Wait until the person confirms their email opt-in.
`no_record`	Nothing held answers this purpose. Ask first.
`not_consent_based`	The purpose declares another basis. Your counsel decides whether it applies.
`unavailable`	Returned by the SDKs only. See the next section.

If you need the person's own confirmation, treat attestedByStaffOnly: true on a basedOn entry as not allowed. A note PHONE_NOT_E164 means a phone number was not in E.164 and was looked up as sent.

When the check cannot answer#

The Node.js and Python helpers wait one second, never retry, and return unavailable with allowed: false. cause says why: timeout, network, rate_limited or server_error. The code above therefore holds the message back.

Going ahead when the check is unavailable is a decision for you and your counsel. If you make it, write it out:

JavaScript

if (check.allowed || check.unavailable) {
  await sendOffer(customer, check.basedOn?.[0]);
}

To wait longer, pass { timeoutMs: 2000 } in Node.js or timeout=2.0 in Python. A wrong key, scope, purpose or partner still throws.

Before you start#

Check one person#

Read the answer#

When the check cannot answer#

Related#