Skip to main content

Collection points and forms

A collection point is a named place where you collect consent, such as a newsletter signup. You build it in the dashboard (Consent Management → Collection Points): choose the notice, the purposes and profile questions the form offers, the websites allowed to show it, and the texts. You edit a draft and publish it; every collected consent is recorded against the collection point, so you can see where it came from. Retiring a collection point stops it accepting submissions and keeps the records already collected.

The two calls below are what the public form page makes. Use the base URL and the X-Org-Api-Key (publishable) header from the overview. Neither needs a principal token, because the visitor has no account yet.

Get the form​

GET /forms/{code}/schema?lang=en

code is the collection point's code, for example cpt_k3m9x2q7. Returns the published version:

{
"entity": {
"code": "cpt_k3m9x2q7",
"version": 3,
"noticeId": 12,
"language": "en",
"texts": { "title": "Join our newsletter", "submitLabel": "Sign up" },
"purposes": [
{ "code": "news", "name": "Product news", "description": "...", "mandatory": false }
],
"fields": [
{ "code": "fld_8k2m1x", "fieldType": "NUMBER", "required": false, "labels": { "en": { "label": "Age" } } }
],
"authenticationRequired": false
},
"success": true
}

A form that does not exist, is not published or is retired answers the same error, so a visitor learns nothing about your other forms. If the collection point lists allowed websites, only a browser on one of them gets an answer.

Submit the form​

POST /forms/{code}/submit
FieldTypeNotes
emailstringRequired unless the form needs sign-in
namestringOptional
languagestringWhich language of the notice was shown
purposeSelectionsobjectpurposeCode → boolean, only purposes the form offers. At least one must be true. Mandatory purposes are always recorded as on
choicesobjectTopic and preference answers, as in Grant consent
fieldsobjectProfile question code → answer
pageUrlstringThe page the form is on
curl -X POST "$CMP_BASE/forms/cpt_k3m9x2q7/submit" \
-H "X-Org-Api-Key: $CMP_PUBLIC_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "asha@example.com", "purposeSelections": { "news": true }, "fields": { "fld_8k2m1x": "34" } }'

201 Created with { "entity": { "recorded": true, "collectionPointCode": "cpt_k3m9x2q7" } }.

The submission is all or nothing: the consent and the answers are saved together, and if any part is refused (an answer of the wrong type, a purpose the form does not offer) nothing is saved and the error names the problem. Profile answers are saved only after consent, and only for a purpose that is granted.

The consent is recorded with the method WEB_FORM (or the one you chose), the collection point and its version, and the website. A collection_point.submitted webhook is sent with the collection point code and the consent record id, never the answers.

An email address is not proof of identity

Bytemonk does not send confirmation emails, so a form that only asks for an email address cannot prove the address belongs to the visitor. To keep that from being used against someone else, such a form never overwrites the profile answers of a person who already exists, and its answer is identical whether or not the address was known. If you need to be certain who is submitting, set the collection point to require sign-in: the form then takes the person from the X-Principal-Token header of a signed-in session and ignores email.

Limits​

Submissions are rate limited per address and per form (an error says to try again in a few minutes).

Which region rule applies​

GET /consent-rules/current

Org key only. Returns the region rule that applies to the caller's own address, so a banner or page can pick its default before it knows who the visitor is:

{ "entity": { "matched": true, "name": "EU visitors", "country": "DE", "defaultState": "OPT_IN", "showBanner": true, "requireExplicit": true, "purposeCodes": [] } }

defaultState is OPT_IN (nothing is on until the person agrees) or OPT_OUT (optional purposes start on until the person declines). matched is false when no rule covers the visitor, and then nothing changes. A rule is advice for whatever draws the banner; it never changes a decision that was recorded.