Consent Docs
Open console

Forms

The endpoint that returns the published consent form for a visitor, with its parameters, response fields, examples and errors.

Reference2 min readFor developers calling the REST API

One endpoint returns the form a visitor should see. Paths are relative to https://console.dpconsent.com/consent/sdk/v1.

Endpoints#

GET /form#

Returns the published form for a visitor: the wording, the purposes, the law that applies and what this visitor has already answered.

Key Scope Idempotency-Key Webhook sent
Publishable or secret None Ignored None

Parameters

Name Type Required Description
formKey string, up to 60 No Asks for one form by its key and skips the choice by region. A form that region rules target is still served only where those rules match.
country 2 letters No Overrides the country worked out from the request. From a server, pass the person's country. Without it the API locates your server.
subdivision 1 to 3 letters or digits No State or province, such as KA.
locale string, up to 10 No Language for the wording, such as hi or pt-BR.
consentId string No Up to five consent ids, separated by commas. The one that belongs to the resolved form is returned as state.
propertyKey string, up to 60 No Names the property when the request alone does not decide it.
debug 1 or true No Adds the full rule-by-rule trace to resolution. For set-up only.

Request

cURLShell
curl "https://console.dpconsent.com/consent/sdk/v1/form?formKey=kalpa-account&country=IN" \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY"
Node.jsJavaScript
const { form } = await client.resolveForm({
  formKey: 'kalpa-account',
  country: 'IN',
});
Python
resolved = client.resolve_form(form_key="kalpa-account", country="IN")
form = resolved["form"]

Response

200, trimmed:

JSON
{
  "form": {
    "id": "0b9c6f0e-6a55-4c1e-9d0a-2f6f0f4f7a11",
    "versionId": "7c0d2f5b-3d1c-4f87-8a53-0f4d6c1e9b20",
    "key": "kalpa-account",
    "name": "Account messages",
    "type": "PREFERENCE_CENTRE",
    "version": 3,
    "contentHash": "9b1f04c7…",
    "locale": "en",
    "locales": ["en", "hi"],
    "copy": {
      "title": "Messages from Kalpa Learning",
      "body": "Choose what we may send you."
    },
    "purposes": [
      {
        "key": "course-updates-by-email",
        "name": "Course updates by email",
        "category": "MARKETING",
        "legalBasis": "CONSENT",
        "alwaysOn": false,
        "vendors": []
      }
    ],
    "consentTtlDays": 365
  },
  "consentModel": "OPT_IN",
  "law": "DPDP",
  "geo": {
    "countryCode": "IN",
    "subdivisionCode": null,
    "source": "header"
  },
  "resolution": { "explanation": "…" },
  "state": null,
  "reconsent": null
}
Field Type Description
form object or null The form version to show. null, still with status 200, when no form is targeted at the visitor's location. Nothing needs to be asked there.
form.purposes array The purposes to answer. One with alwaysOn: true needs no answer.
form.version integer The published version number.
form.layout, form.policy mixed What the browser runtime uses to draw the banner.
consentModel string The consent model that applies, such as OPT_IN.
law string or null The law of the region rule that matched, such as DPDP.
geo object The location used: countryCode, subdivisionCode and source.
resolution object or null Why this form was chosen. With debug, the full trace. null for a form asked for by formKey that no region rule targets.
state object or null The visitor's record for this form, as a consent record. Needs consentId.
reconsent object or null { "reason", "changes" } when the visitor must be asked again. reason is FORM_CHANGED, VERSION_CHANGED or EXPIRED.
runtime, experiment, honourGlobalPrivacyControl mixed Settings for the browser runtime.

Errors

Status Code When
404 FORM_NOT_FOUND No form has the formKey you sent.
400 AMBIGUOUS_FORM_KEY The formKey exists on more than one property. Send propertyKey, or use a key tied to one property.
400 CONSENT_FORM_NOT_PUBLISHED The form has no published version.
403 PROPERTY_NOT_FOR_KEY The key is tied to a different property than propertyKey names, or its property is no longer active.

Also the errors every call can return.

↑↓ to move, Enter to open