Conventions

These rules apply to every endpoint in this reference.

Base URL and version#

All paths in this reference are relative to:

https://console.dpconsent.com/consent/sdk/v1

Item	Value
Version	The `v1` segment of the path. Every endpoint here is under it.
Live reference	Swagger at https://console.dpconsent.com/consent/api/docs, under the tags SDK, SDK — people and Hosted pages
SDKs	Node.js and Python wrap the server calls

Endpoint entries#

Every endpoint in this reference is laid out the same way.

Part	What it tells you
Heading	The method and the path, relative to the base URL
Key	Which key may call it: publishable, secret or none
Scope	The scope a secret key needs
`Idempotency-Key`	`Accepted` when the header makes the call safe to repeat, `Checked, not replayed` when it is checked but no response is stored, `Ignored` otherwise
Webhook sent	The events the call queues
Parameters	Each parameter with its type and whether it is required
Request	A cURL example, with Node.js and Python where the SDKs wrap the call
Response	The status and the body
Errors	The errors of its own, on top of the errors every call can return

Requests#

Rule	Detail
Body	JSON, sent with `Content-Type: application/json`
Path parameters	The names in braces, such as `{consentId}`
Other parameters	In the query string for `GET`, in the JSON body for `POST` and `PATCH`
Unknown fields	Dropped without an error
String values	Stored as sent. HTML tags are not removed, so escape a value when you render it.
Clients that cannot send `PATCH`	Send `POST` with the header `X-HTTP-Method-Override: PATCH`

Request header	Use
`Authorization`	`Bearer` and a secret key. See Authentication.
`X-Piedap-Key`	A publishable key
`X-Piedap-App`	The application id of a mobile app, in place of `Origin`
`Idempotency-Key`	Makes a write safe to repeat. See Idempotency.
`X-Request-Id`	Your own request id, 8 to 100 letters, digits, dots, colons, hyphens or underscores

Responses#

Rule	Detail
Body	JSON, except the hosted pages and the runtime files
Success	The object itself, with no wrapper
Times	ISO 8601 strings in UTC, such as `2026-09-24T10:12:03.000Z`
Errors	See Errors

Status	Meaning
`200`	Done
`201`	A new consent record was created
`202`	An email opt-in is waiting for confirmation

Response header	Meaning
`X-Request-Id`	The id of this request. It is yours if you sent a valid one. Quote it when you report a problem.
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`	Where the key stands. See Rate limits.
`Retry-After`	Seconds to wait after a `429`
`Idempotent-Replayed`	`true` when the response is a stored one

Pagination#

No endpoint under /sdk/v1 is paginated. POST /subjects/find returns every record held for the person, oldest first.

The test flag#

Every consent record carries test, and every webhook event carries the same flag.

Written with	`test`	Kept
A test key	`true`	Apart from live records, and deleted 30 days after the last change
A live key	`false`	As live evidence

Updates, withdrawals and the calls on a person reach only records of the key's own kind. Made with a test key, they never touch a live record. How to use test records is in Test your integration.

Idempotency#

A write that carries an Idempotency-Key header is applied once, however many times you send it.

Item	Rule
Endpoints	`POST /consent`, `PATCH /consent/{consentId}`, `POST /consent/{consentId}/withdraw` and `POST /email-consent`.
Calls on a person	`POST /subjects/withdraw`, `/erase` and `/link` check the header but store no response. A repeat runs again and changes nothing more.
Other endpoints	Ignore the header.
Key format	1 to 255 printable ASCII characters, with no spaces
Stored for	24 hours
Scope of a key	One project and one API key. The same value under two API keys never collides.
Same request	The same method, path and JSON body. The order of the JSON keys does not matter.

You send	You get
A key for the first time	The request is handled as usual and its response is stored
The same key and the same request	The stored response, with `Idempotent-Replayed: true`. Nothing is recorded again.
The same key and a different request	`422` with the code `IDEMPOTENCY_KEY_REUSED`
The same key while the first request is still running	A wait of up to two seconds, then `409` with the code `IDEMPOTENCY_REQUEST_IN_PROGRESS`
A key that is empty, too long or has spaces	`400`

A response below 500 that comes from handling the request is stored and replayed, a 400 with a code included. After such a refusal, fix the request and send it with a new key. A failed field check, a refused key, a rate limit and a 5xx response are not stored, so the same key tries again.

Name the event in the key, not the attempt:

Shell

curl -X POST https://console.dpconsent.com/consent/sdk/v1/consent/$CONSENT_ID/withdraw \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: close-usr_8f2K1xQz" \
  -d '{ "reason": "Account closed" }'

Limits#

What	Limit
A JSON request body	100 KB
`metadata`	8,192 bytes of JSON from a server; 6 KB from the browser runtime
`decisions`	1 to 100 in one request
`identifiers`	5 in one call
`subjectId`	255 characters
`formKey`, `purposeKey`	60 characters
`pageUrl`, `reason`, `returnUrl`	500 characters
`guardian.reference`	200 characters
`email`	255 characters
`locale`	10 characters
`consentId` in `GET /form`	Up to five ids, separated by commas
`Idempotency-Key`	255 characters

What	Lasts
A stored idempotency key	24 hours
An email confirmation link	48 hours
A consent portal link	7 days
A test record	30 days after its last change

The SDK examples#

The Node.js and Python tabs in this reference use a client made once at start-up:

Node.jsJavaScript

import { ConsentClient } from '@piedap/consent/server';

const client = new ConsentClient({
  apiUrl: 'https://console.dpconsent.com/consent',
  secretKey: process.env.PIEDAP_SECRET_KEY,
});

Python

import os
from piedap_consent import ConsentClient

client = ConsentClient(
    "https://console.dpconsent.com/consent",
    os.environ["PIEDAP_SECRET_KEY"],
)