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.
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#
- A secret key on your server. See Keys and where to use them.
- A published form of a kind drawn in a page, such as Consent screen in your app or SMS, WhatsApp and call opt-in. See Kinds of consent form.
Create the link#
-
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", ) -
Open
urlfor the person. An app opens it in an in-app browser, such as Custom Tabs on Android orSFSafariViewControlleron iOS. -
When they answer, the page goes to
returnUrlwithconsentandconsentIdadded.consentissaved,acceptedorrejected.
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.
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.
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.