Skip to main content

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​

  1. Open the web space in the dashboard.
  2. Open Web space settings.
  3. Open Avacy integration on your web space.
  4. In the Integrate Avacy tab, open the Google Tag Manager item. The Team name field contains the value of <team>.
  5. Read the page address in the browser. It has the form .../banner-integration/<id>, and the final number is the web space id.
note

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​

  1. Open Avacy integration on your web space (steps 1-3 above).
  2. Open the Access Keys tab.
  3. Click Create new Access Key.
  4. Type a name in the Key name field (for example "Contact form").
  5. Click Create Access Key.
  6. Copy the key shown and keep it.
warning

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.

Headers​

HeaderValue
AuthorizationBearer <Access Key>
Content-Typeapplication/json
Acceptapplication/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.

FieldTypeRequiredDescription
consent_typestringYesform for your own forms. banner is reserved for the Avacy banner.
optinstringYesaccepted or rejected.
ip_addressstringYes, for formThe IP of the person giving consent (see below).
consent_featuresarray of stringsYes, 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_dataarray of objectsYes, for form without identifierConsent data. Each entry has label and value.
identifierstringNoIdentifier of the subject, for example their user id.
sourcestringNoOrigin of the consent, for example website.
html_formstringNoThe HTML code of the form shown to the person.
uuidstringNoUUID 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.

The ip_address field

Put 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​

CodeWhen
403The Access Key is missing, is not valid, belongs to another web space, or has been replaced by a newer one.
403The plan does not include the consent archive. The message is Your plan does not include the consent archive feature.
422A required field is missing or has a value that is not allowed, for example an optin outside the list.
429The 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.

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.

  1. Use the same uuid and the same identifier as the consent to update. Keep the uuid that the API returns on the first registration.
  2. In consent_features, list the items that are still valid, for example privacy_policy and cookie_policy. Remove the revoked ones.
  3. Leave optin as accepted: consent_features tells what was revoked.
  4. 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.

warning

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​

  1. Send the curl request from the example.
  2. Check that the response is 201 and contains a uuid.
  3. Open the Consent archive item in the dashboard side menu. In the Form consents tab, paste the uuid from the response into Search by unique ID....
  4. The consent row appears, with user-123 as the user identifier.

Common problems​

The most frequent problems:

  • 403 with message Forbidden: check that the key is the last one created for that web space and that <id> is the key's web space;
  • 403 with a message about the plan: the account's plan does not include the consent archive (available from the Plus plan);
  • 422: check optin, consent_features, consent_data and ip_address. A form consent requires all of them, except consent_data when there is an identifier.
  • The recorded IP is the server's: check that ip_address contains a valid IP address.

Last updated: 09/11/2026.