Consent links
The endpoint that creates a link opening one consent form for one person, and the page the link opens, with parameters, examples and errors.
A consent link opens one published form for one person on a page served by PIEDAP, and records the answer under that person. Paths are relative to https://dev.dpconsent.com/consent/sdk/v1. How to use it is in Send a form as a link.
Endpoints#
POST /consent-links#
Returns a link to a page where the person answers the form.
| Key | Scope | Idempotency-Key |
Webhook sent |
|---|---|---|---|
| Secret | consent:write |
Ignored | consent.created or consent.updated when the person answers |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
formKey |
string | Yes | A published form of a kind drawn in a page. |
subjectId |
string | Yes | Who answers: your id for the person, or for the child when a parent answers. |
subjectType |
string | No | USER_ID when left out. Also EMAIL, PHONE, DEVICE_ID, SESSION_ID or COOKIE_ID. |
identifiers |
array | No | Up to five more identifiers the record can be found by, such as the number the link was sent to. |
locale |
string | No | The page language, such as hi or ta. The browser's language is used when left out. |
returnUrl |
string | No | Where the page goes after the answer: a web address or your app's own link. consent and consentId are added to it. |
channel |
string | No | APP, SMS, WHATSAPP, EMAIL, IN_PERSON or PHONE. Kept with the record. |
assistedBy |
string | For IN_PERSON and PHONE |
Your reference for the member of staff, such as an employee id. Printable ASCII, up to 100 characters. Sealed as a keyed hash. |
guardian |
object | For a parental form | relationship, verification and reference, as in Consent. |
dataPrincipalType |
string | No | CHILD when left out with guardian, or PERSON_WITH_DISABILITY. |
expiresInHours |
integer | No | How long the link works: 1 to 720 hours. Seven days when left out. |
requireCode |
boolean | No | The page asks for a 6-digit code before it takes the answer. The response carries the code for you to send. Five wrong codes lock the link. |
Request
curl -X POST https://dev.dpconsent.com/consent/sdk/v1/consent-links \
-H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "formKey": "app-screen-k3x9", "subjectId": "usr_8f2K1xQz",
"channel": "APP", "returnUrl": "yourapp://consent-done" }'const { url, expiresOn } = await client.createConsentLink({
formKey: 'app-screen-k3x9',
subjectId: 'usr_8f2K1xQz',
channel: 'APP',
returnUrl: 'yourapp://consent-done',
});link = client.create_consent_link(
"app-screen-k3x9",
"usr_8f2K1xQz",
channel="APP",
return_url="yourapp://consent-done",
)Response
201:
{
"linkId": "5b0f6a52-7c1e-4bd4-9a5e-2f8f7c6d1e30",
"url": "https://dev.dpconsent.com/consent/sdk/v1/c/Qm3x9Kp2Lr7Tz1…",
"expiresOn": "2026-11-19T10:12:03.000Z"
}| Field | Type | Description |
|---|---|---|
linkId |
string | Kept with the record as metadata.linkId. |
url |
string | The link to open or send. Anyone who holds it can answer for the person until it expires. |
expiresOn |
time | When the link stops working. |
code |
string | With requireCode only: the code to send the person. It is not kept, so it cannot be fetched again. |
Errors
| Status | Code | When |
|---|---|---|
403 |
CONSENT_LINK_SERVER_ONLY |
The call was made with a publishable key. |
400 |
CONSENT_FORM_NOT_PUBLISHED |
The form has no published version. |
400 |
FORM_NOT_FOR_LINKS |
The form is a banner, a notice or an email opt-in. |
400 |
GUARDIAN_REQUIRED |
The form is for a parent or guardian, and guardian is missing. |
400 |
CAPTURE_REFERENCE_REQUIRED |
channel is IN_PERSON or PHONE, and assistedBy is missing. |
400 |
AMBIGUOUS_FORM_KEY |
The key is used on more than one property, and the API key is not tied to one. |
404 |
CONSENT_FORM_NOT_FOUND |
No form has the key. |
Also the errors every call can return.
GET /c/{token}#
The page the link opens. It needs no key: the token is the credential. It is a plain HTML form that works without JavaScript, and runs one script only to show steps and parts that wait on another answer.
The answer is posted back to the same address and recorded as the person's own. A required box left unticked, or a refusal from the record, shows the form again with a message. An unknown token answers 404, and an expired or locked one 410. A record taken after the code was entered carries metadata.confirmedBy: "CODE".