Consent archive REST API
The consent archive REST API records the consents collected by your forms. Your site sends one POST request for each consent, and the archive keeps it as proof.
Who it is for
It is for anyone who builds their own form or application and wants to store consents without the WordPress plugin.
Prerequisites
Before you start you need:
- an Avacy account on the Plus plan or higher. On a lower plan the API responds
403(see Errors); - a web space already created in the dashboard;
- the team name and the web space id (see Where to find the team and id);
- an Access Key for the web space (see Create an Access Key).
API address
The base address is https://api.avacy.eu/<team>/v4. The registration endpoint is the following.
POST https://api.avacy.eu/<team>/v4/webspaces/<id>/consents
<team> is the team name. <id> is the numeric id of the web space.
Where to find the team and id
- Open the web space in the dashboard.
- Open Web space settings.
- Open Avacy integration on your web space.
- In the Integrate Avacy tab, open the Google Tag Manager item. The Team name field contains the value of
<team>. - Read the page address in the browser. It has the form
.../banner-integration/<id>, and the final number is the web space id.
The dashboard does not show the web space id in a field. That is why you read it from the page address. The Team name field contains the same value that the dashboard uses in the address of its own API calls.
Create an Access Key
- Open Avacy integration on your web space (steps 1-3 above).
- Open the Access Keys tab.
- Click Create new Access Key.
- Type a name in the Key name field (for example "Contact form").
- Click Create Access Key.
- Copy the key shown and keep it.
The dashboard shows the key only once. Copy it right away.
Keep the Access Key on your server and call the API from there. Do not put it in your site's JavaScript: anyone who opens the page could read it and record consents in your name.
The key is valid only for the web space you created it for. For each web space, only the last key created is valid. Older keys get 403.
Record a consent
Headers
| Header | Value |
|---|---|
Authorization | Bearer <Access Key> |
Content-Type | application/json |
Accept | application/json |
Body fields
A form consent (consent_type equal to form) requires consent_type, optin, ip_address, consent_features and consent_data. If you send an identifier, consent_data can be left out: the consent is stored with an empty list.
| Field | Type | Required | Description |
|---|---|---|---|
consent_type | string | Yes | form for your own forms. banner is reserved for the Avacy banner. |
optin | string | Yes | accepted or rejected. |
ip_address | string | Yes, for form | The IP of the person giving consent (see below). |
consent_features | array of strings | Yes, for form. With optin equal to rejected it can be empty ([]) | The items the person consents to. In Avacy forms privacy_policy and cookie_policy are always present, because the form cannot be sent without them. The API does not enforce them, though: in your own form, list only the items actually accepted. The others, for example newsletter, are optional and can be revoked (see Revoke a consent). A form sent with no accepted item is recorded with rejected and [], as the WordPress plugin does from 1.5.0. |
consent_data | array of objects | Yes, for form without identifier | Consent data. Each entry has label and value. |
identifier | string | No | Identifier of the subject, for example their user id. |
source | string | No | Origin of the consent, for example website. |
html_form | string | No | The HTML code of the form shown to the person. |
uuid | string | No | UUID of the consent. If missing, the API generates it. |
For optin the API also accepts consent-all, reject-all, save-preferences and close-banner. These are banner values. In your forms use accepted or rejected.
ip_address fieldPut the person's IP in ip_address, not your server's IP. The API saves the value if it is a valid IPv4 or IPv6 address. If it is not, the API still records the consent, with the IP the call comes from.
The API also accepts strings for consent_features ("privacy_policy,cookie_policy,newsletter") and for consent_data ("name=Mario,email=mario@example.com"). The recommended form is still the JSON array.
Example with curl
Replace <team>, <id> and <Access Key> with your values.
curl -i -X POST "https://api.avacy.eu/<team>/v4/webspaces/<id>/consents" \
-H "Authorization: Bearer <Access Key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"consent_type": "form",
"optin": "accepted",
"ip_address": "203.0.113.10",
"consent_features": ["privacy_policy", "cookie_policy", "newsletter"],
"consent_data": [
{ "label": "name", "value": "Mario" },
{ "label": "email", "value": "mario@example.com" }
],
"identifier": "user-123",
"source": "website",
"html_form": "<form>Newsletter sign-up</form>"
}'
Response
The API responds 201 Created with the saved consent. The values of id, uuid, versions and the dates are examples.
{
"message": "Consent created successfully",
"data": {
"webspace_id": 1,
"ip_address": "203.0.113.10",
"versions": [
{
"slug": "privacy_policy",
"link": "https://assets.example.com/policies/...",
"date": "2026-10-27T10:30:00.000000Z"
}
],
"consent_type": "form",
"consent_features": ["privacy_policy", "cookie_policy", "newsletter"],
"optin": "accepted",
"consent_data": [
{ "label": "name", "value": "Mario" },
{ "label": "email", "value": "mario@example.com" }
],
"identifier": "user-123",
"domain": null,
"source": "website",
"html_form": "<form>Newsletter sign-up</form>",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"updated_at": "2026-10-27T10:30:00.000000Z",
"created_at": "2026-10-27T10:30:00.000000Z",
"id": 123
}
}
The versions field lists the privacy policy and the cookie policy that Avacy generates for the web space, only if they exist. The domain field contains the request's Origin header or, if missing, Referer. A server call without these headers leaves domain as null.
Errors
| Code | When |
|---|---|
403 | The Access Key is missing, is not valid, belongs to another web space, or has been replaced by a newer one. |
403 | The plan does not include the consent archive. The message is Your plan does not include the consent archive feature. |
422 | A required field is missing or has a value that is not allowed, for example an optin outside the list. |
429 | The same IP address sent more than 60 requests in one minute for the same web space. |
The 403 for an invalid key has the body {"message":"Forbidden"}. The 422 body contains message and, for each invalid field, a list in errors.
{
"message": "The selected optin is invalid.",
"errors": {
"optin": ["The selected optin is invalid."]
}
}
The 429 response has the Retry-After header, with the seconds to wait before retrying. If you record many consents at once, for example with an import, spread the requests over time.
The texts of message and errors are in English and can change. In your code, use the HTTP status code and the field names in errors.
Revoke a consent
When a person withdraws consent to an optional item, for example the newsletter, record the new choice with another POST. There is no dedicated endpoint for revocation.
- Use the same
uuidand the sameidentifieras the consent to update. Keep theuuidthat the API returns on the first registration. - In
consent_features, list the items that are still valid, for exampleprivacy_policyandcookie_policy. Remove the revoked ones. - Leave
optinasaccepted:consent_featurestells what was revoked. - Also send the other form fields (
ip_address,consent_data), as in a registration.
This example revokes the newsletter for the consent recorded in the previous example.
curl -i -X POST "https://api.avacy.eu/<team>/v4/webspaces/<id>/consents" \
-H "Authorization: Bearer <Access Key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"consent_type": "form",
"optin": "accepted",
"ip_address": "203.0.113.10",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"identifier": "user-123",
"consent_features": ["privacy_policy", "cookie_policy"],
"consent_data": [
{ "label": "name", "value": "Mario" },
{ "label": "email", "value": "mario@example.com" }
]
}'
The API responds 201 and creates a new record with the same uuid. The previous record stays in the archive as proof of the earlier choice. The current choice is the one in the record with the same uuid and the most recent created_at. If created_at is the same, the record with the highest id wins, because records created close together can have the same date. The date counts before the id, because a consent imported from a file can enter the archive after a more recent version of it.
Do not delete the previous consent to record a revocation. Deleting it also deletes the proof of the earlier choice.
List, export and import
The documented API is for recording consents. Listing, search, export and import are done from the dashboard, in the Consent archive item. The instructions are in the Consent archive (in Italian) guide.
Verify
- Send the
curlrequest from the example. - Check that the response is
201and contains auuid. - Open the Consent archive item in the dashboard side menu. In the Form consents tab, paste the
uuidfrom the response into Search by unique ID.... - The consent row appears, with
user-123as the user identifier.
Common problems
The most frequent problems:
403with messageForbidden: check that the key is the last one created for that web space and that<id>is the key's web space;403with a message about the plan: the account's plan does not include the consent archive (available from the Plus plan);422: checkoptin,consent_features,consent_dataandip_address. Aformconsent requires all of them, exceptconsent_datawhen there is anidentifier.- The recorded IP is the server's: check that
ip_addresscontains a valid IP address.
Last updated: 09/11/2026.