Consent Docs

Send a form as a link

Create a link that opens one consent form for one person, for an app's consent screen, an SMS or WhatsApp opt-in, a parent or staff at a branch.

How-to2 min readFor web, backend and mobile developers

A consent link opens one published form for one person, on a page served by PIEDAP. Use it where your own page cannot show the form: an app's first-run screen, a message to a phone number, a parent, or staff at a branch. The answer is recorded under the person you name.

Before you start#

  1. On your server, create a link for the signed-in person.

    Node.jsJavaScript
    const { url } = await consent.createConsentLink({
      formKey: 'app-screen-k3x9',
      subjectId: user.id,
      subjectType: 'USER_ID',
      channel: 'APP',
      returnUrl: 'yourapp://consent-done',
    });
    Python
    link = client.create_consent_link(
        "app-screen-k3x9",
        user.id,
        "USER_ID",
        channel="APP",
        return_url="yourapp://consent-done",
    )
  2. Open url for the person. An app opens it in an in-app browser, such as Custom Tabs on Android or SFSafariViewController on iOS.

  3. When they answer, the page goes to returnUrl with consent and consentId added. consent is saved, accepted or rejected.

A link works for seven days unless you send expiresInHours. Opening it again shows the answer saved last time, and a new answer updates the same record.

Send it to a phone number#

Create the link with channel: 'SMS' or 'WHATSAPP', and the number in identifiers. Send url in your message. Opening the link from that message confirms the number is the person's, and the record can be found by the number.

To confirm the number apart from the link, send requireCode: true. The response carries a 6-digit code for your SMS or WhatsApp sender. The page asks for it before it takes the answer, and locks after five wrong codes.

JavaScript
const { url } = await consent.createConsentLink({
  formKey: 'messages-opt-in-7tq2',
  subjectId: user.id,
  channel: 'SMS',
  identifiers: [{ subjectType: 'PHONE', subjectId: '+919800000000' }],
});

Ask a parent or guardian#

A form of the kind Consent from a parent or guardian needs the verified parent. Send guardian with how you verified them, and send the link to the parent. Without guardian, the link is refused with GUARDIAN_REQUIRED.

JavaScript
const { url } = await consent.createConsentLink({
  formKey: 'parental-2kd8',
  subjectId: child.id,
  channel: 'EMAIL',
  guardian: {
    relationship: 'PARENT',
    verification: 'EXISTING_ACCOUNT',
    reference: parent.id,
  },
});

Take answers at a branch or call#

Send channel: 'IN_PERSON' or 'PHONE', and your reference for the member of staff in assistedBy, such as an employee id. Staff open the link on a tablet or read it out on the call. The record is sealed as staff-attested, with the reference stored as a keyed hash. See Record consent taken in a branch, by phone or on paper.

↑↓ to move, Enter to open