Consent Docs

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.

Reference3 min readFor developers calling the REST API

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

cURLShell
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" }'
Node.jsJavaScript
const { url, expiresOn } = await client.createConsentLink({
  formKey: 'app-screen-k3x9',
  subjectId: 'usr_8f2K1xQz',
  channel: 'APP',
  returnUrl: 'yourapp://consent-done',
});
Python
link = client.create_consent_link(
    "app-screen-k3x9",
    "usr_8f2K1xQz",
    channel="APP",
    return_url="yourapp://consent-done",
)

Response

201:

JSON
{
  "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".

↑↓ to move, Enter to open