Skip to main content

Consent store integration via REST API

This section shows the integration and consultation of the consent archive, necessary to be able to store evidence of the consent to the processing of personal data that users may have knowingly given while browsing your website.

This documentation describes endpoints for managing consent within webspaces. The base URL of the API is

https://api.avacy.eu/:team/v2

POST /webspaces/:id/consents

Route parameters

id (integer, mandatory): the identifier of the web space on which the consent is created.

Parameters in the request (JSON format):

identifier (string, required): The type of identifier used for the subject (for example, email, userID).

subject: Details of the subject providing consent. Must include the identifier specified above.

ip_address (string, required): The IP address of the person providing consent.

proofs (array, optional): An array of proofs that support consensus.

legal_notices (array, optional): A list of legal notices to which the user is consenting.

preferences (object, required): An object containing the subject's preferences regarding consent.

Example:

{
  "identifier":  "email",
  "subject":  {
    "email":  "utente@example.com",
    "name":  "Mario Rossi"
  },
  "ip_address":  "192.168.0.1",
  "proofs":  "very-long-encoded-string",
  "legal_notices":  ["privacy_policy",  "terms_of_service"],
  "preferences":  {
    "newsletter":  true,
    "promotions":  false
  }
}

Successful Response

Code: 201 Created

{
  "data":  {
    "id":  123,
    "ip_address":  "192.168.0.1",
    "subject_id":  "utente@example.com",
    "proofs":  [
      {
        "type":  "screenshot",
        "value":  "stringabase64"
      }
    ],
    "legal_notices":  ["privacy_policy",  "terms_of_service"],
    "consent_data":  "{\"newsletter\": true, \"promotions\": false}",
    "subject_data":  "{\"email\": \"utente@example.com\", \"name\": \"Mario Rossi\"}"
  }
}

Error Response

Code: 400 Bad Request if the required fields are missing or invalid.

Code: 404 Not Found if the webspace with the specified ID does not exist.

Read the consents on a web space

GET /webspaces/:id/consents

Route parameters

id (integer, mandatory): the identifier of the web space from which to read the consents.

Parameters in query string

limit (integer, optional): The maximum number of consents to return. The default value is 15.

orderBy (string, optional): Field to order the results on. The default value is id.

orderType (string, optional): Order type, can be asc or desc. The default value is asc.

page (integer, optional): Page number for pagination.

startdate (date, optional): Start date to filter consents by creation date.

enddate (date, optional): End date to filter consents based on creation date.

subject_id: the identifier of the subject whose consents you want to read.

Request example:

/v2/webspaces/1/consents?limit=10&orderBy=created_at&orderType=desc&startdate=2023-01-01&enddate=2023-12-31&subject_id=utente@example.com

Success Response

Code: 200 OK

{
  "data":  [
    {
      "id":  123,
      "ip_address":  "192.168.0.1",
      "subject_id":  "utente@example.com",
      "created_at":  "2023-01-15T10:00:00Z",
      "legal_notices":  ["privacy_policy",  "terms_of_service"],
      "consent_data":  "{\"newsletter\": true, \"promotions\": false}",
      "subject_data":  "{\"email\": \"utente@example.com\", \"name\": \"Mario Rossi\"}"
    },
    {
      "id":  124,
      "ip_address":  "192.168.0.2",
      "subject_id":  "altroutente@example.com",
      "created_at":  "2023-02-10T12:30:00Z",
      "legal_notices":  ["terms_of_service"],
      "consent_data":  "{\"newsletter\": false, \"promotions\": true}",
      "subject_data":  "{\"email\": \"altroutente@example.com\", \"name\": \"Giovanna Bianchi\"}"
    }
  ],
  "meta":  {
    "current_page":  1,
    "per_page":  10,
    "total":  2
  }
}

Error Response

Code: 400 Bad Request if the query parameters are invalid.

Code: 404 Not Found if no consensus matching the criteria is found.