Iubenda logo
Start generating

Documentation

Table of Contents

Consent Database – HTTP API Documentation

❗️ Important

Please note that from June 3rd, 2024, our Consent Solution HTTP API will no longer support the fulltext filter. This means it will stop working after this date. To avoid any issues, we advise you to update any setups that currently use the fulltext filter.

The Consent Database HTTP API allows you to record and retrieve consent actions performed by your users, who will be referred to within the solution as “subjects”.

Update: We’ve now added a Beta channel. Here you can test all the latest features before they’re moved to the Current channel.

Headers

Authentication

In order to write into the API, we provide two kinds of keys:

  • Public key, commonly used by the Javascript library
  • Private key, commonly used by the HTTP API

All calls performed to the API, both via HTTP or JS, indicate whether the call was authenticated by a private or public key. This allows you to give more trust to calls that came from the private key, which come with an increased level of reliability when it comes to verifying that the data was truly sent by you.

For the HTTP API, the private key must be sent via the ApiKey header. Public API keys are accepted only on the POST /public/consent endpoint.

Update: To secure all communications between REST API and clients, support for HTTP protocol is being dropped in all Consent Database API calls. After 31 Jan 2023, all requests for Consent Database APIs must adhere to HTTPS protocol.

Content-Type

In order to send data to our HTTP API, the Content-Type header must be set to application/json or application/x-www-form-urlencoded.

❗️ Consent Database HTTP APIs only support UTF-8 encoded JSON. The APls will return HTTP status 400 for any other encoding headings sent with a request.

API Output

By default, every json response is unescaped. We recommend users to escape the values that might contain HTML and/or JavaScript code if they are going to render them from a web page to avoid XSS attacks.

❗️ Warning

The parameter unescape_json, which was used to unescape the response json by passing unescape_json=true to any request is now ignored and every request considers it as a default.

Rate Limits

By default, you can perform a maximum of 50 requests per second and 108000 requests per hour. Server-side, the API will respond with “429 Too Many Requests” if these limits are exceeded

Max Request Size

There is a maximum of 1 MB per call. Server-side, the API will respond with “413 Request Entity Too Large” if these limits are exceeded.

LIST consents

Examples →

GET https://consent.iubenda.com/consent

For Beta:

GET https://consent.iubenda.com/beta/consent

All fields are optional, but some are auto-filled if not provided.

Accepted query parameters:

from_time optional String Filter by consents timestamp. Returns all consents from that time onward (inclusive). Valid formats: 2018-02-22 00:40:00 UTC, 2018-02-22T00:40:00Z (ISO 8601), 1519260000 (unix timestamp in seconds). Default null
to_time optional String Filter by consents timestamp. Returns all consents from that time backward (inclusive). Valid formats: 2018-02-22 00:40:00 UTC, 2018-02-22T00:40:00Z (ISO 8601), 1519260000 (unix timestamp in seconds). Default null
source optional String Filter by consents source. Possible values: public, private. Default null
ip_address optional String Filter by IP address. Default null. Valid formats (IP address format). Default ‘none’
subject_id optional String Filter by Subject ID. Default null
subject_email_exact optional String Filter by Subject email. It must exactly match (case sensitive). Default null
subject_email optional String Filter by Subject email. It matches the string partially (case insensitive). Default null deprecated
subject_first_name optional String Filter by Subject first name. It must exactly match (case sensitive). Default null
subject_last_name optional String Filter by Subject last name. It must exactly match (case sensitive). Default null
subject_full_name optional String Filter by Subject full name. It matches the string partially (case insensitive). Default null deprecated
subject_verified optional Boolean Filter by subject verified status. Possible values: true, false. Default null
fulltext optional String Filters for results with the value provided being contained in either subject’s id, first_name, last_name, full_name, email. Default null deprecated
starting_after optional String Cursor which indicates after which Consent the results should be returned (cursor excluded). Default null
limit optional Numeric Number indicating the number of results returned. Min: 1, Max: 100. Default 10

This method supports cursor-based pagination via the starting_after parameter. This parameter takes an existing consent and returns objects after it.

Keeping in mind that the results are ordered by default by timestamp descending.

Some fields are deprecated and might not be performant. We discourage their use as we might drop the support in the future.

Response:

# 200 OK
[{
    "id": "b04c4b2b-80b7-439f-8997-ade3d35cbb95",
    "timestamp": "2018-06-04T08:11:34.000+00:00",
    "owner": "521686",
    "source": "private",
    "subject": {
      "id": "0e371678-634a-4016-83ce-9b7c36f828e6",
      "email": "83ce_634a_4016_9b7c36f828e6_0e371678@example.com",
      "first_name": "Kianna",
      "last_name": "Fahey",
      "full_name": "Kianna Fahey",
      "phones": [
        { "number": "+395555555555", "label": "personal", "country": "IT" }
      ]
    },
    "preferences": {
      "newsletter": false
    }
  },
  {
    "id": "ee6644ea-08e9-4aaa-a7a9-18602731a123",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "681109",
    "source": "public",
    "subject": {
      "id": "8c6d1b71-0908-4604-948f-2f706500b5b1",
      "email": "0908.8c6d1b71.2f706500b5b1.4604.948f@example.org",
      "first_name": "Eleanora",
      "last_name": "Adams",
      "full_name": "Eleanora Adams",
      "verified": false
    },
    "preferences": {
      "newsletter": true
    }
  },
  {
    "id": "e7a9f5db-481e-4c80-ac7d-a35e35d37f98",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "178473",
    "source": "private",
    "subject": {
      "id": "d084ab70-0460-4523-94b2-44841055b49c",
      "email": "94b2_4523_44841055b49c_0460_d084ab70@example.com",
      "first_name": "Abbie",
      "last_name": "Heidenreich",
      "full_name": "Abbie Heidenreich",
      "verified": false
    },
    "preferences": {
      "third_party": true
    }
  },
  {
    "id": "e3481085-296c-4b11-a999-73d5d1309128",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "393753",
    "source": "private",
    "subject": {
      "id": "be8ca546-150d-4a6e-b2ac-ef76fb8a279e",
      "email": "b2ac_ef76fb8a279e_150d_4a6e_be8ca546@example.net",
      "first_name": "Grace",
      "last_name": "Dooley",
      "full_name": "Grace Dooley",
      "verified": false
    },
    "preferences": {
      "another_preference_key": false,
      "newsletter": false
    }
  },
  {
    "id": "e1be0320-a854-4b01-a468-49b1752ee4f3",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "629879",
    "source": "public",
    "subject": {
      "id": "f8878254-c7ae-4169-b474-19e90d7b2f4f",
      "email": "f8878254_b474_19e90d7b2f4f_4169_c7ae@example.net",
      "first_name": "Providenci",
      "last_name": "Kulas",
      "full_name": "Providenci Kulas",
      "verified": false
    },
    "preferences": {
      "newsletter": false,
      "random_preference_key": true,
      "third_party": true,
      "another_preference_key": false
    }
  },
  {
    "id": "cbe2bba8-d31d-4a27-9e2d-b38de4f22a68",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "989797",
    "source": "public",
    "subject": {
      "id": "6387dc5d-d474-4da8-8c40-8b197dee8d7c",
      "email": "6387dc5d.4da8.d474.8c40.8b197dee8d7c@example.com",
      "first_name": "Alan",
      "last_name": "Rutherford",
      "full_name": "Alan Rutherford",
      "verified": false
    },
    "preferences": {
      "newsletter": true,
      "random_preference_key": true
    }
  },
  {
    "id": "ca429c28-e1cd-4b95-87ae-48adb8fe56bb",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "885846",
    "source": "public",
    "subject": {
      "id": "b2ad578d-0aa9-4bd5-becd-e2e7a2019e7a",
      "email": "b2ad578d.becd.e2e7a2019e7a.0aa9.4bd5@example.net",
      "first_name": "Ruby",
      "last_name": "Lemke",
      "full_name": "Ruby Lemke",
      "verified": false
    },
    "preferences": {
      "third_party": true,
      "random_preference_key": false
    }
  },
  {
    "id": "bf12770e-840a-40cd-ab79-5d88576b6b73",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "369168",
    "source": "public",
    "subject": {
      "id": "d4f24d92-56c2-4372-8696-fec829da5ccc",
      "email": "fec829da5ccc.8696.4372.56c2.d4f24d92@example.com",
      "first_name": "Hank",
      "last_name": "Klein",
      "full_name": "Hank Klein",
      "verified": false
    },
    "preferences": {
      "newsletter": false
    }
  },
  {
    "id": "b489e2d4-2fc6-44e1-ba54-e5f81000d30a",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "781022",
    "source": "public",
    "subject": {
      "id": "38bc623f-b386-4b66-8ee6-5e7d91c19800",
      "email": "38bc623f.8ee6.4b66.5e7d91c19800.b386@example.net",
      "first_name": "Kamren",
      "last_name": "Pacocha",
      "full_name": "Kamren Pacocha",
      "verified": false
    },
    "preferences": {
      "newsletter": true
    }
  },
  {
    "id": "b2ec7aa8-35e7-470c-8b51-bd39fa686a3a",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "527898",
    "source": "public",
    "subject": {
      "id": "0cc94c66-d9eb-4ace-af3d-1d48fba265f9",
      "email": "1d48fba265f9_4ace_af3d_d9eb_0cc94c66@example.net",
      "first_name": "Maryjane",
      "last_name": "Wiegand",
      "full_name": "Maryjane Wiegand",
      "verified": false
    },
    "preferences": {
      "newsletter": true
    }
  }
]

Please note, this method doesn’t include the proofs and legal notices of the Consent. You should call GET /consent/:id to get the complete Consent event.

GET consent

Examples →

GET https://consent.iubenda.com/consent/:id

For Beta:

GET https://consent.iubenda.com/beta/consent/:id
200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26+00:00",
  "owner": "1234",
  "subject": {
    "id": "J02eZvKYlo2ClwuJ1",
    "email": "subject@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phones": [
      { "number": "+395555555555", "label": "personal", "country": "IT" }
    ],
    "verified": false
  },
  "preferences": {
    "privacy_policy": true,
    "newsletter": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": "123"
    },
    {
      "identifier": "terms",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof form"
    }
  ],
  "proof_documents": [
      {
        "id" : "85812b7c-f6a5-4861-a180-a74303446e08", 
        "name" : "test.pdf"
      },
      {
        "id" : "f8cbc695-5228-4ba4-a017-dc2a50c67e25",
        "name" : "test.html"
      }
  ]
}

In addition to the properties outlined previously:

id Unique identifier of the specific consent event
owner Unique identifier of the API key owner
source private public Whether the consent was filed from the public or the private API key

CREATE consent

Examples →

POST https://consent.iubenda.com/consent

For Beta:

POST https://consent.iubenda.com/beta/consent
{
  "subject": {
    "id": "J02eZvKYlo2ClwuJ1",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phones": [
      { "number": "+395555555555", "label": "personal" }
    ],
    "verified": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": "123"
    },
    {
      "identifier": "terms",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof form"
    }
  ],
  "proof_documents_ids": [
    "85812b7c-f6a5-4861-a180-a74303446e08", 
    "f8cbc695-5228-4ba4-a017-dc2a50c67e25"
  ],
  "preferences": {
    "newsletter": false,
    "privacy_policy": true
  }
}

This call will post a new consent.

The response is the following:

# 200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "subject_id": "testsubject"
}
timestamp auto-filled if not provided String ISO 8601 timestamp at which the consent occurred
subject Object
id auto-filled if not provided String
email String
first_name String
last_name String
full_name String
verified Boolean Reserved field used to signal whether a subject is verified, for instance via the double opt-in method
legal_notices Array Array of objects containing legal_notices data
identifier String privacy_policy, cookie_policy, term or a custom identifier
version auto-filled if not provided String
proofs Array Array of objects containing proof data
content Text
form Text
preferences Object Set of key-value pairs with user preferences for the consent action
ip_address auto-filled if using `autodetect_ip_address` String Considered only when using a `private` key. Saves the passed IP address on the Consent. Default null
autodetect_ip_address Default `true` String Considered only when using a `public` key. Enables or disables (true, false) the IP address autedetection. Default true
proof_document_ids Array Array of String IDs for documents that provide proof of the consent

LAST consent

Examples →

For Beta:

GET https://consent.iubenda.com/beta/subjects/:id/consent/last

The Last Consent method returns the last consent created for the given subject.

The response is the following:

# 200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "checksum": "336dd0c5ee2253794b8cca6ee2b2fec835ab25a7097c4405014d02e4ffe4d5e5",
  "owner": "1",
  "subject": {
    "id": "custom_subject_id",
    "owner_id": "1",
    "email": "subject@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "verified": false
  },
  "preferences": {
    "privacy_policy": true,
    "newsletter": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": 123
    },
    {
      "identifier": "term",
      "version": 123
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof_1 form"
    },
    {
      "content": "proof_2",
      "form": "proof_2 form"
    }
  ],
  "ip_address": null
}

Subjects

LIST subjects

Examples →

GET https://consent.iubenda.com/subjects

For Beta:

GET https://consent.iubenda.com/beta/subjects

All fields are optional, but some are auto-filled if not provided.

Accepted query parameters:

id optional String Filter by id. It must exactly match. Default null
email_exact optional String Filter by email. It must exactly match (case sensitive). Default null
email optional String Filter by email. It matches the string partially (case insensitive) Deprecated
first_name optional String Filter by first name. It must exactly match (case sensitive). Default null
last_name optional String Filter by last name. It must exactly match (case sensitive). Default null
full_name optional String Filter by full name. It matches the string partially (case insensitive) Deprecated
from_time optional String Filter by subjects timestamp. Returns all subjects from that time onward (inclusive). Valid formats: 2018-02-22 00:40:00 UTC, 2018-02-22T00:40:00Z (ISO 8601), 1519260000 (unix timestamp in seconds). Default null
to_time optional String Filter by subjects timestamp. Returns all subjects from that time backward (inclusive). Valid formats: 2018-02-22 00:40:00 UTC, 2018-02-22T00:40:00Z (ISO 8601), 1519260000 (unix timestamp in seconds). Default null
verified optional Boolean Filter by verified status. Possible values: true, false. Default null
fulltext optional String Filters for results with the value provided being contained in either id, first_name, last_name, full_name, email. Default null deprecated
starting_after optional String Cursor which indicates after which Subject the results should be returned (cursor excluded). Default null
limit optional Numeric Number indicating the number of results returned. Min: 1, Max: 101. Default 10
phone optional String Filter all subjects containing the given number. Phone number must include the country code. The plus (+) sign can be omitted. Default null

This method supports cursor-based pagination via the starting_after parameter. This parameter takes an existing subject and returns objects after it.

Response:

# 200 OK
[
  {
    "id": "d2a55da5-0777-4625-94bd-b69948703e71",
    "owner_id": "131132",
    "email": "rath.jorge@example.com",
    "first_name": "Jorge",
    "last_name": "Rath",
    "full_name": "Jorge Rath",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
  },
  {
    "id": "b75c6d0c-550f-4f84-9e92-2f351d481220",
    "owner_id": "131132",
    "email": "aufderhar_alfonso@example.net",
    "first_name": "Alfonso",
    "last_name": "Aufderhar",
    "full_name": "Alfonso Aufderhar",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
  },
  {
    "id": "a9c8c720-cb07-4a52-81c3-7cb7fb4f877e",
    "owner_id": "131132",
    "email": "vandervort.furman@example.net",
    "first_name": "Furman",
    "last_name": "Vandervort",
    "full_name": "Furman Vandervort",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
  },
  {
    "id": "6ccc2802-3bcb-49af-a4c5-14dc89ba94bc",
    "owner_id": "131132",
    "email": "alvis.rohan@example.org",
    "first_name": "Alvis",
    "last_name": "Rohan",
    "full_name": "Alvis Rohan",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
  },
  {
    "id": "5900f856-619e-42b0-92a5-b2ebd016ac01",
    "owner_id": "131132",
    "email": "brown.marlee@example.net",
    "first_name": "Marlee",
    "last_name": "Brown",
    "full_name": "Marlee Brown",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
  }
]

Some fields are deprecated and might not be performant. We discourage their use as we might drop the support in the future.

GET subjects

Examples →

GET https://consent.iubenda.com/subjects/:id

For Beta:

GET https://consent.iubenda.com/beta/subjects/:id
# 200 OK
{
  "id": "testsubject",
  "owner_id": "1",
  "email": "subject@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phones": [
      { "number": "+395555555555", "label": "personal", "country": "IT" }
    ],
  "verified": false,
  "preferences": {
    "privacy_policy": {
      "value": true,
      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"
    },
    "newsletter": {
      "value": true,
      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"
    }
  }
}

CREATE subjects

Examples →

POST https://consent.iubenda.com/subjects

For Beta:

POST https://consent.iubenda.com/beta/subjects
{
  "id": "testsubject",
  "email": "subject@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "verified": false
  "phones": [
    { "number": "+395555555555", "label": "personal" }
  ]
}

This method will post a new subject. It can also be used from within the consent one. Check the reference within the consent method for the details.

id auto-filled if not provided String
email optional String
first_name optional String
last_name optional String
full_name optional String
verified optional Boolean Reserved field used to signal whether a subject is verified, for instance via the double opt-in method
phones optional Array Array of objects containing phone number data
number optional String A valid number with country code prefix
label optional String Arbitrary text used to identify the phone number
Coming soon
custom_attributes optional Object A set of key-value pairs containing custom attributes

The response is the following:

# 200 OK
{
  "id": "testsubject",
  "created_at": "2018-05-04T14:52:26Z"
}

UPDATE subjects

Examples →

PUT|PATCH https://consent.iubenda.com/subjects/:id

For Beta:

PUT|PATCH https://consent.iubenda.com/beta/subjects/:id
{
  "first_name": "Mary",
  "verified": true
}

This call will update an existing subject.

The response is the following:

# 200 OK
{
  "id": "testsubject",
  "created_at": "2018-05-04T14:52:26Z"
}

Legal Notices

LIST Legal Notices

Examples →

GET https://consent.iubenda.com/legal_notices

For Beta:

GET https://consent.iubenda.com/beta/legal_notices

The documents are returned ordered by timestamp.

All fields are optional, but some are auto-filled if not provided.
Accepted query parameters:

id optional String Filter by id. It must exactly match. Default null
identifier optional String Filter by identifier. It must exactly match (case sensitive). Default null
version optional Numeric Filter by version. It must exactly match. Default null
language optional String Filter by legal notices which contents include the specified language (using short form like ‘en’, ‘it’ etc.). Default null
from_time optional String Filter by legal notices timestamp. Returns all legal notices from that time onward (inclusive). Valid formats: 2018-02-22 00:40:00 UTC, 2018-02-22T00:40:00Z (ISO 8601), 1519260000 (unix timestamp in seconds). Default null
to_time optional String Filter by legal notices timestamp. Returns all legal notices from that time backward (inclusive). Valid formats: 2018-02-22 00:40:00 UTC, 2018-02-22T00:40:00Z (ISO 8601), 1519260000 (unix timestamp in seconds). Default null
starting_after_version optional Numeric Cursor which indicates after which Legal Notice’s version the results should be returned (cursor excluded). Default null
starting_after_identifier optional String Cursor which indicates after which Legal Notice’s identifier the results should be returned (cursor excluded). Default null
limit optional Numeric Number indicating the number of results returned. Min: 1, Max: 101. Default 10

This method supports cursor-based pagination via the starting_after_version and starting_after_identifier parameters. These parameters take an existing Legal Notice and return objects after it. Both parameters are required in order to paginate.

Response:

# 200 OK

[
  {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 20,
    "timestamp": "2018-10-09T12:38:04Z",
    "content": {
      "en": "Et vinculum clam decerno arguo admoveo velum sponte tot suppellex venustas defendo dolor decumbo est.",
      "it": "Collum tutis esse confugo porro urbs varius abscido turpis decor praesentium tardus voluptate fugit numquam."
    }
  },
  {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 19,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Venia valde vel surculus capitulus adfectus patior comparo acsi cur vero super cursim.",
      "it": "Consuasor arcesso conscendo crudelis cauda aer aut adeptio illo argentum comis subiungo subito colo."
    }
  },
  {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 18,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Ullus voco aufero speculum fugiat audacia laboriosam vilicus amita trans aut ut.",
      "it": "Alo veritatis ipsa tristis cuius occaecati adflicto creta verecundia facere solvo despirmatio cupiditate crinis aqua bos."
    }
  },
  {
    "id": "0_privacy_policy",
    "owner_id": "0",
    "identifier": "privacy_policy",
    "version": 17,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Confero succedo caelum adhaero quo vir deorsum quaerat utor sit ustulo cribro.",
      "it": "Bibo cubitum unus est ambitus contego apparatus alo via abutor utroque xiphias voco."
    }
  },
  {
    "id": "0_privacy_policy",
    "owner_id": "0",
    "identifier": "privacy_policy",
    "version": 16,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Qui porro culpo attero benevolentia aut sed sulum adfero artificiose adsidue tam amo validus vel spectaculum.",
      "it": "Cerno ipsum fugit compello cursim ter surgo asporto debilito excepturi adversus facere."
    }
  },
  {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 15,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Tunc timidus veritatis maiores advenio aperio testimonium defluo celo cuius adsuesco deripio.",
      "it": "Depulso dignissimos vinitor curatio caelestis cedo et sum concedo id admoneo appositus."
    }
  },
  {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 14,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Repellat mollitia desidero videlicet est textilis stips nisi aequus solum depromo agnitio usus.",
      "it": "Vomito tonsor comitatus illum aut usitas laboriosam canonicus tepesco benigne confugo trado."
    }
  },
  {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 13,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Temperantia alias somniculosus absorbeo utique caecus terror demitto trucido desidero baiulus sublime.",
      "it": "Perspiciatis at tredecim curriculum comprehendo deduco corrupti attonbitus barba cruentus communis comparo thorax cauda spero vito anser."
    }
  },
  {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 12,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Allatus cena surculus ventito ver adversus torrens demo venustas toties veritas qui cado vis.",
      "it": "Talio avoco aptus compono et subiungo peior bellum depromo aureus torqueo adeptio nobis."
    }
  },
  {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 11,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
      "en": "Aliquam cubicularis tergum utor cinis concido ratione vociferor uter deduco tertius verecundia alo claustrum sto vos aegrotatio.",
      "it": "Corona ut comes sub coaegresco caute casus laboriosam tremo vulariter aegrotatio pauci callide assentator basium."
    }
  }
]

GET a Legal Notice version

Examples →

GET https://consent.iubenda.com/legal_notices/:identifier/:version

For Beta:

GET https://consent.iubenda.com/beta/legal_notices/:identifier/:version

Response:

# GET /legal_notices/privacy_policy/1
# 200 OK
{
    "identifier": "privacy_policy",
    "content": "legal text",
    "timestamp": "2018-05-16T13:55:57+00:00",
    "version": 1,
    "documents": [
      {
        "id" : "85812b7c-f6a5-4861-a180-a74303446e08", 
        "name" : "test.pdf"
      },
      {
        "id" : "f8cbc695-5228-4ba4-a017-dc2a50c67e25",
        "name" : "test.html"
      }
    ]
}

GET all Legal Notice versions

Examples →

GET https://consent.iubenda.com/legal_notices/:identifier

For Beta:

GET https://consent.iubenda.com/beta/legal_notices/:identifier

The documents are returned ordered by version.

Accepted query parameters:

limit optional Number Limit the number of results. Default 10
starting_after optional Number Cursor for use in pagination. Default null

This method supports cursor-based pagination via the starting_after parameter. This parameter takes an existing Legal Notice version and returns objects in reverse order.

# 200 OK
[
    {
        "identifier": "privacy_policy",
        "timestamp": "2018-05-16T13:55:57+00:00",
        "version": 3,
        "documents": [
          {
            "id" : "85812b7c-f6a5-4861-a180-a74303446e08", 
            "name" : "name"
          },
          {
            "id" : "f8cbc695-5228-4ba4-a017-dc2a50c67e25",
            "name" : "something"
          }        
        ]
    },
    {
        "identifier": "privacy_policy",
        "timestamp": "2018-03-16T13:55:57+00:00",
        "version": 2,
        "documents": [
          {
            "id" : "85812b7c-f6a5-4861-a180-a74303446e08", 
            "name" : "name"
          }
        ]
    },
    {
        "identifier": "privacy_policy",
        "timestamp": "2018-01-16T13:55:57+00:00",
        "version": 1,
        "documents: []
    }
]

Please note, this method doesn’t include the content of the Legal Notice, only the metadata for each. You should call GET /legal_notices/:identifier/:version to get the full document.

If you use iubenda for your legal documents, we’ll automatically update the contents of the legal_notices method for you whenever your legal documents are changed. You can read about how to enable this feature here.

CREATE a Legal Notice

Examples →

POST https://consent.iubenda.com/legal_notices

For Beta:

POST https://consent.iubenda.com/beta/legal_notices
{
    "identifier": "privacy_policy",
    "content": "privacy policy content",
    "timestamp": "2018-05-16T13:55:57_00:00",
    "document_ids": [
      "85812b7c-f6a5-4861-a180-a74303446e08", 
      "f8cbc695-5228-4ba4-a017-dc2a50c67e25"
    ]
}

With multi-language content:

{
    "identifier": "privacy_policy",
    "content": {
    "en": "privacy policy content",
    "it": "contenuto della privacy policy"
  },
    "timestamp": "2018-05-16T13:55:57_00:00",
    "document_ids": [
      "85812b7c-f6a5-4861-a180-a74303446e08", 
      "f8cbc695-5228-4ba4-a017-dc2a50c67e25"
    ]
}

Response:

# 200 OK
{
  "identifier": "privacy_policy",
  "timestamp": "2018-05-16T13:55:57Z",
  "version": 1
}

CREATE multiple Legal Notices

POST https://consent.iubenda.com/legal_notices

For Beta:

POST https://consent.iubenda.com/beta/legal_notices
[
  {
    "identifier": "privacy_policy",
    "content": "privacy policy content",
    "timestamp": "2018-05-16T13:55:57Z"
  },
  {
    "identifier": "cookie_policy",
    "content": "cookie policy content",
    "timestamp": "2018-05-16T13:55:57Z"
  }
]

Response:

# 200 OK
[
  {
    "identifier": "privacy_policy",
    "timestamp": "2018-05-16T13:55:57Z",
    "version": 1
  },
  {
    "identifier": "cookie_policy",
    "timestamp": "2018-05-16T13:55:57Z",
    "version": 1
  }
]

Document

CREATE Document

The Create Document method will post a new document.

POST https://consent.iubenda.com/beta/documents

Accepted query parameters:

file optional the uploaded file (max 1MB)

Response:

# 200 OK
{
  "id": "bd25e1fc-da53-4b48-8fef-0ecb6068f666",
  "name": "text_of_contract.txt",
  "mime_type": "text/plain",
  "timestamp": "2019-06-11T15:20:07+00:00",
}

LIST Documents

The Index Document method will show all documents.

For Beta:

GET https://consent.iubenda.com/beta/documents

The results are ordered by timestamp in descending order (DESC).
Accepted query parameters:

starting_after_identifier optional String Cursor which indicates after which Legal Notice’s identifier the results should be returned (cursor excluded). Default null
limit optional Numeric Number indicating the number of results returned. Min: 1, Max: 101. Default 10

Response:

# 200 OK
[
  {
    "id": "bd25e1fc-da53-4b48-8fef-0ecb6068f666",
    "name": "text_of_contract.txt",
    "mime_type": "text/plain",
    "timestamp": "2019-06-11T15:20:07+00:00",
    "referenced": true
  },
  {
    "id": "bd25e1fc-da53-4b48-8fef-0ecb6068f666",
    "name": "contract_image.jpg",
    "mime_type": "image/jpeg",
    "timestamp": "2020-06-11T15:20:07+00:00",
    "referenced":false
  },
  ...
]

SHOW Document

The Show Document method will show a document.

For Beta:

GET https://consent.iubenda.com/beta/documents/:id

Response:

File data

Examples

POST /consent

$ curl https://consent.iubenda.com/consent \
  -X POST \
  -H "ApiKey: your-private-api-key" \
  -H "Content-Type: application/json" \
  -d  '{ "subject": { "id": "J02eZvKYlo2ClwuJ1", "email": "subject@example.com" }, "preferences": { "newsletter": true }, "legal_notices": [{ "identifier": "privacy_policy" }], "proofs": [{ "content": "proof_content", "form": "proof_form" }], "ip_address": "127.0.0.1" }'

Response:


{
    "id": "1dbbc6f8-6a57-4407-b687-d6e6f818742f",
    "timestamp": "2018-06-06T09:48:44.265Z",
    "subject_id": "J02eZvKYlo2ClwuJ1"
}
GET /consent

$ curl https://consent.iubenda.com/consent/ \
  -H "ApiKey: your-private-api-key"

Response:


[{
    "id": "b04c4b2b-80b7-439f-8997-ade3d35cbb95",
    "timestamp": "2018-06-04T08:11:34.000+00:00",
    "owner": "12345",
    "source": "private",
    "subject": {
        "id": "0e371678-634a-4016-83ce-9b7c36f828e6",
        "email": "83ce_634a_4016_9b7c36f828e6_0e371678@example.com",
        "first_name": "Kianna",
        "last_name": "Fahey",
        "full_name": "Kianna Fahey",
        "verified": false
    },
    "preferences": {
        "newsletter": false
    },
    "ip_address": "79.42.49.139"
}, {
    "id": "ee6644ea-08e9-4aaa-a7a9-18602731a123",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "12345",
    "source": "public",
    "subject": {
        "id": "8c6d1b71-0908-4604-948f-2f706500b5b1",
        "email": "0908.8c6d1b71.2f706500b5b1.4604.948f@example.org",
        "first_name": "Eleanora",
        "last_name": "Adams",
        "full_name": "Eleanora Adams",
        "verified": false
    },
    "preferences": {
        "newsletter": true
    },
    "ip_address": null
}, {
    "id": "bf12770e-840a-40cd-ab79-5d88576b6b73",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "12345",
    "source": "public",
    "subject": {
        "id": "d4f24d92-56c2-4372-8696-fec829da5ccc",
        "email": "fec829da5ccc.8696.4372.56c2.d4f24d92@example.com",
        "first_name": "Hank",
        "last_name": "Klein",
        "full_name": "Hank Klein",
        "verified": false
    },
    "preferences": {
        "newsletter": false
    },
    "ip_address": "79.42.49.139"
}]
GET /consent/:id

$ curl https://consent.iubenda.com/consent/1dbbc6f8-6a57-4407-b687-d6e6f818742f \
  -H "ApiKey: your-private-api-key"

Response:


{
    "id": "1dbbc6f8-6a57-4407-b687-d6e6f818742f",
    "timestamp": "2018-05-04T14:52:26Z",
    "owner": "1",
    "subject": {
        "id": "custom_subject_id",
        "owner_id": "1",
        "email": "subject@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "verified": false
    },
    "preferences": {
        "privacy_policy": true,
        "newsletter": false
    },
    "legal_notices": [{
        "identifier": "privacy_policy",
        "version": "123.0"
    }, {
        "identifier": "term",
        "version": "123.0"
    }],
    "proofs": [{
        "content": "proof_1",
        "form": "proof_1 form"
    }, {
        "content": "proof_2",
        "form": "proof_2 form"
    }],
    "ip_address": null
}
POST /consent

$consent_data = array(
    "subject" => array(
        "id" => "J02eZvKYlo2ClwuJ1",
        "email" => "subject@example.com"
    ),
    "legal_notices" => array(
        array(
            "identifier" => "newsletter"
        ),
        array(
            "identifier" => "privacy_policy"
        )
    ),
    "proofs" => array(
        array(
            "content" => "proof_content",
            "form" => "proof_form"
        )
    ),
    "preferences" => array(
        "newsletter" => true,
        "privacy_policy" => true
    ),
    "ip_address" => "127.0.0.1"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/consent');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($consent_data));

$response = curl_exec($req);

Response:


{
    "id": "7abe5f70-22e4-4181-878c-9f931034fab5",
    "timestamp": "2018-06-08T08:25:30.395Z",
    "subject_id": "J02eZvKYlo2ClwuJ1"
}
GET /consent

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/consent');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


[{
    "id": "b04c4b2b-80b7-439f-8997-ade3d35cbb95",
    "timestamp": "2018-06-04T08:11:34.000+00:00",
    "owner": "12345",
    "source": "private",
    "subject": {
        "id": "0e371678-634a-4016-83ce-9b7c36f828e6",
        "email": "83ce_634a_4016_9b7c36f828e6_0e371678@example.com",
        "first_name": "Kianna",
        "last_name": "Fahey",
        "full_name": "Kianna Fahey",
        "verified": false
    },
    "preferences": {
        "newsletter": false
    },
    "ip_address": "79.42.49.139"
}, {
    "id": "ee6644ea-08e9-4aaa-a7a9-18602731a123",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "12345",
    "source": "public",
    "subject": {
        "id": "8c6d1b71-0908-4604-948f-2f706500b5b1",
        "email": "0908.8c6d1b71.2f706500b5b1.4604.948f@example.org",
        "first_name": "Eleanora",
        "last_name": "Adams",
        "full_name": "Eleanora Adams",
        "verified": false
    },
    "preferences": {
        "newsletter": true
    },
    "ip_address": null
}, {
    "id": "bf12770e-840a-40cd-ab79-5d88576b6b73",
    "timestamp": "2018-06-04T08:11:33.000+00:00",
    "owner": "12345",
    "source": "public",
    "subject": {
        "id": "d4f24d92-56c2-4372-8696-fec829da5ccc",
        "email": "fec829da5ccc.8696.4372.56c2.d4f24d92@example.com",
        "first_name": "Hank",
        "last_name": "Klein",
        "full_name": "Hank Klein",
        "verified": false
    },
    "preferences": {
        "newsletter": false
    },
    "ip_address": "79.42.49.139"
}]
GET /consent/:id

$req = curl_init();
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/consent/7abe5f70-22e4-4181-878c-9f931034fab5');
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


{
    "id": "1dbbc6f8-6a57-4407-b687-d6e6f818742f",
    "timestamp": "2018-05-04T14:52:26Z",
    "owner": "1",
    "subject": {
        "id": "custom_subject_id",
        "owner_id": "1",
        "email": "subject@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "verified": false
    },
    "preferences": {
        "privacy_policy": true,
        "newsletter": false
    },
    "legal_notices": [{
        "identifier": "privacy_policy",
        "version": "123.0"
    }, {
        "identifier": "term",
        "version": "123.0"
    }],
    "proofs": [{
        "content": "proof_1",
        "form": "proof_1 form"
    }, {
        "content": "proof_2",
        "form": "proof_2 form"
    }],
    "ip_address": null
}

Subjects

POST /subjects

$ curl https://consent.iubenda.com/subjects \
    -X POST \
    -H "ApiKey: your-private-api-key" \
    -H "Content-Type: application/json" \
    -d '{ "email": "john@example.com", "first_name": "John", "last_name": "Doe" }'

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "timestamp": "2018-06-06T11:05:41.600Z"
}
GET /subjects

$ curl https://consent.iubenda.com/subjects \
  -X GET \
  -H "ApiKey: your-private-api-key" \
  -H "Content-Type: application/json"

Response:


[{
    "id": "d2a55da5-0777-4625-94bd-b69948703e71",
    "owner_id": "131132",
    "email": "rath.jorge@example.com",
    "first_name": "Jorge",
    "last_name": "Rath",
    "full_name": "Jorge Rath",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "b75c6d0c-550f-4f84-9e92-2f351d481220",
    "owner_id": "131132",
    "email": "aufderhar_alfonso@example.net",
    "first_name": "Alfonso",
    "last_name": "Aufderhar",
    "full_name": "Alfonso Aufderhar",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "a9c8c720-cb07-4a52-81c3-7cb7fb4f877e",
    "owner_id": "131132",
    "email": "vandervort.furman@example.net",
    "first_name": "Furman",
    "last_name": "Vandervort",
    "full_name": "Furman Vandervort",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "6ccc2802-3bcb-49af-a4c5-14dc89ba94bc",
    "owner_id": "131132",
    "email": "alvis.rohan@example.org",
    "first_name": "Alvis",
    "last_name": "Rohan",
    "full_name": "Alvis Rohan",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "5900f856-619e-42b0-92a5-b2ebd016ac01",
    "owner_id": "131132",
    "email": "brown.marlee@example.net",
    "first_name": "Marlee",
    "last_name": "Brown",
    "full_name": "Marlee Brown",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}]
GET /subjects/:id

$ curl https://consent.iubenda.com/subjects/9f5a50f6-052c-4595-8bc4-760dc05d86ba \
  -H "ApiKey: your-private-api-key"

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "owner_id": "123",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": null,
    "preferences": null,
    "verified": false,
    "timestamp": "2018-06-06T11:05:41+00:00"
}
PATCH /subjects/:id

$ curl https://consent.iubenda.com/subjects/9f5a50f6-052c-4595-8bc4-760dc05d86ba \
  -X PATCH \
  -H "ApiKey: your-private-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "mary@example.com", "first_name": "Mary", "last_name": "Doe" }'

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "timestamp": "2018-06-06T11:05:41.000+00:00"
}
GET /beta/subjects

$ curl https://consent.iubenda.com/beta/subjects \
  -X GET \
  -H "ApiKey: your-private-api-key" \
  -H "Content-Type: application/json"

Response:


[{
    "id": "d2a55da5-0777-4625-94bd-b69948703e71",
    "owner_id": "131132",
    "email": "rath.jorge@example.com",
    "first_name": "Jorge",
    "last_name": "Rath",
    "full_name": "Jorge Rath",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "b75c6d0c-550f-4f84-9e92-2f351d481220",
    "owner_id": "131132",
    "email": "aufderhar_alfonso@example.net",
    "first_name": "Alfonso",
    "last_name": "Aufderhar",
    "full_name": "Alfonso Aufderhar",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "a9c8c720-cb07-4a52-81c3-7cb7fb4f877e",
    "owner_id": "131132",
    "email": "vandervort.furman@example.net",
    "first_name": "Furman",
    "last_name": "Vandervort",
    "full_name": "Furman Vandervort",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "6ccc2802-3bcb-49af-a4c5-14dc89ba94bc",
    "owner_id": "131132",
    "email": "alvis.rohan@example.org",
    "first_name": "Alvis",
    "last_name": "Rohan",
    "full_name": "Alvis Rohan",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "5900f856-619e-42b0-92a5-b2ebd016ac01",
    "owner_id": "131132",
    "email": "brown.marlee@example.net",
    "first_name": "Marlee",
    "last_name": "Brown",
    "full_name": "Marlee Brown",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}]
GET /beta/subjects/:id

$ curl https://consent.iubenda.com/beta/subjects/9f5a50f6-052c-4595-8bc4-760dc05d86ba \
  -H "ApiKey: your-private-api-key"

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "owner_id": "123",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": null,
    "preferences": null,
    "verified": false,
    "timestamp": "2018-06-06T11:05:41+00:00"
}
PATCH /beta/subjects/:id

$ curl https://consent.iubenda.com/beta/subjects/9f5a50f6-052c-4595-8bc4-760dc05d86ba \
  -X PATCH \
  -H "ApiKey: your-private-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "mary@example.com", "first_name": "Mary", "last_name": "Doe" }'

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "timestamp": "2018-06-06T11:05:41.000+00:00"
}
POST /subjects

$subject_data = array(
    "email" => "subject@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/subjects');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($subject_data));

$response = curl_exec($req);

Response:


{
    "id": "df39c1bf-5f27-4c3a-bf94-64360cc7e4f8",
    "timestamp": "2018-06-11T08:57:13.662Z"
}
GET /subjects

$subject_data = array(
    "email" => "subject@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/subjects');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($subject_data));

$response = curl_exec($req);

Response:


[{
    "id": "d2a55da5-0777-4625-94bd-b69948703e71",
    "owner_id": "131132",
    "email": "rath.jorge@example.com",
    "first_name": "Jorge",
    "last_name": "Rath",
    "full_name": "Jorge Rath",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "b75c6d0c-550f-4f84-9e92-2f351d481220",
    "owner_id": "131132",
    "email": "aufderhar_alfonso@example.net",
    "first_name": "Alfonso",
    "last_name": "Aufderhar",
    "full_name": "Alfonso Aufderhar",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "a9c8c720-cb07-4a52-81c3-7cb7fb4f877e",
    "owner_id": "131132",
    "email": "vandervort.furman@example.net",
    "first_name": "Furman",
    "last_name": "Vandervort",
    "full_name": "Furman Vandervort",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "6ccc2802-3bcb-49af-a4c5-14dc89ba94bc",
    "owner_id": "131132",
    "email": "alvis.rohan@example.org",
    "first_name": "Alvis",
    "last_name": "Rohan",
    "full_name": "Alvis Rohan",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "5900f856-619e-42b0-92a5-b2ebd016ac01",
    "owner_id": "131132",
    "email": "brown.marlee@example.net",
    "first_name": "Marlee",
    "last_name": "Brown",
    "full_name": "Marlee Brown",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}]
GET /subjects/:id

$req = curl_init();
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/subjects/df39c1bf-5f27-4c3a-bf94-64360cc7e4f8');
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "owner_id": "123",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": null,
    "preferences": null,
    "verified": false,
    "timestamp": "2018-06-06T11:05:41+00:00"
}
PATCH /subjects/:id

$subject_data = array(
    "first_name" => "Mary"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/subjects/df39c1bf-5f27-4c3a-bf94-64360cc7e4f8');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($subject_data));

$response = curl_exec($req);

Response:


{
    "id": "df39c1bf-5f27-4c3a-bf94-64360cc7e4f8",
    "timestamp": "2018-06-11T08:57:13.000+00:00"
}
POST /beta/subjects

$subject_data = array(
    "email" => "subject@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/beta/subjects');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($subject_data));

$response = curl_exec($req);

Response:


{
    "id": "df39c1bf-5f27-4c3a-bf94-64360cc7e4f8",
    "timestamp": "2018-06-11T08:57:13.662Z"
}
GET /beta/subjects

$subject_data = array(
    "email" => "subject@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/beta/subjects');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($subject_data));

$response = curl_exec($req);

Response:


[{
    "id": "d2a55da5-0777-4625-94bd-b69948703e71",
    "owner_id": "131132",
    "email": "rath.jorge@example.com",
    "first_name": "Jorge",
    "last_name": "Rath",
    "full_name": "Jorge Rath",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "b75c6d0c-550f-4f84-9e92-2f351d481220",
    "owner_id": "131132",
    "email": "aufderhar_alfonso@example.net",
    "first_name": "Alfonso",
    "last_name": "Aufderhar",
    "full_name": "Alfonso Aufderhar",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "a9c8c720-cb07-4a52-81c3-7cb7fb4f877e",
    "owner_id": "131132",
    "email": "vandervort.furman@example.net",
    "first_name": "Furman",
    "last_name": "Vandervort",
    "full_name": "Furman Vandervort",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "6ccc2802-3bcb-49af-a4c5-14dc89ba94bc",
    "owner_id": "131132",
    "email": "alvis.rohan@example.org",
    "first_name": "Alvis",
    "last_name": "Rohan",
    "full_name": "Alvis Rohan",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}, {
    "id": "5900f856-619e-42b0-92a5-b2ebd016ac01",
    "owner_id": "131132",
    "email": "brown.marlee@example.net",
    "first_name": "Marlee",
    "last_name": "Brown",
    "full_name": "Marlee Brown",
    "preferences": null,
    "verified": true,
    "timestamp": "2018-09-12T16:22:21+00:00"
}]
GET /beta/subjects/:id
$req = curl_init();
$req = curl_init();
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/beta/subjects/df39c1bf-5f27-4c3a-bf94-64360cc7e4f8');
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


{
    "id": "9f5a50f6-052c-4595-8bc4-760dc05d86ba",
    "owner_id": "123",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": null,
    "preferences": null,
    "verified": false,
    "timestamp": "2018-06-06T11:05:41+00:00"
}
PATCH /beta/subjects/:id 

$subject_data = array(
    "first_name" => "Mary"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/beta/subjects/df39c1bf-5f27-4c3a-bf94-64360cc7e4f8');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($subject_data));

$response = curl_exec($req);

Response:


{
    "id": "df39c1bf-5f27-4c3a-bf94-64360cc7e4f8",
    "timestamp": "2018-06-11T08:57:13.000+00:00"
}
POST /legal_notices

$ curl https://consent.iubenda.com/legal_notices \
  -X POST \
  -H "ApiKey: your-private-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "identifier": "privacy_policy", "content": "privacy policy legal text" }'

Response:


{
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-06-06T15:56:10.090Z"
}
GET /legal_notices

$ curl https://consent.iubenda.com/legal_notices \
  -H "ApiKey: your-private-api-key"

Response:


[{
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 20,
    "timestamp": "2018-10-09T12:38:04Z",
    "content": {
        "en": "Et vinculum clam decerno arguo admoveo velum sponte tot suppellex venustas defendo dolor decumbo est.",
        "it": "Collum tutis esse confugo porro urbs varius abscido turpis decor praesentium tardus voluptate fugit numquam."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 19,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Venia valde vel surculus capitulus adfectus patior comparo acsi cur vero super cursim.",
        "it": "Consuasor arcesso conscendo crudelis cauda aer aut adeptio illo argentum comis subiungo subito colo."
    }
}, {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 18,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Ullus voco aufero speculum fugiat audacia laboriosam vilicus amita trans aut ut.",
        "it": "Alo veritatis ipsa tristis cuius occaecati adflicto creta verecundia facere solvo despirmatio cupiditate crinis aqua bos."
    }
}, {
    "id": "0_privacy_policy",
    "owner_id": "0",
    "identifier": "privacy_policy",
    "version": 17,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Confero succedo caelum adhaero quo vir deorsum quaerat utor sit ustulo cribro.",
        "it": "Bibo cubitum unus est ambitus contego apparatus alo via abutor utroque xiphias voco."
    }
}, {
    "id": "0_privacy_policy",
    "owner_id": "0",
    "identifier": "privacy_policy",
    "version": 16,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Qui porro culpo attero benevolentia aut sed sulum adfero artificiose adsidue tam amo validus vel spectaculum.",
        "it": "Cerno ipsum fugit compello cursim ter surgo asporto debilito excepturi adversus facere."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 15,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Tunc timidus veritatis maiores advenio aperio testimonium defluo celo cuius adsuesco deripio.",
        "it": "Depulso dignissimos vinitor curatio caelestis cedo et sum concedo id admoneo appositus."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 14,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Repellat mollitia desidero videlicet est textilis stips nisi aequus solum depromo agnitio usus.",
        "it": "Vomito tonsor comitatus illum aut usitas laboriosam canonicus tepesco benigne confugo trado."
    }
}, {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 13,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Temperantia alias somniculosus absorbeo utique caecus terror demitto trucido desidero baiulus sublime.",
        "it": "Perspiciatis at tredecim curriculum comprehendo deduco corrupti attonbitus barba cruentus communis comparo thorax cauda spero vito anser."
    }
}, {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 12,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Allatus cena surculus ventito ver adversus torrens demo venustas toties veritas qui cado vis.",
        "it": "Talio avoco aptus compono et subiungo peior bellum depromo aureus torqueo adeptio nobis."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 11,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Aliquam cubicularis tergum utor cinis concido ratione vociferor uter deduco tertius verecundia alo claustrum sto vos aegrotatio.",
        "it": "Corona ut comes sub coaegresco caute casus laboriosam tremo vulariter aegrotatio pauci callide assentator basium."
    }
}]
GET /legal_notices/:identifier/:version

$ curl https://consent.iubenda.com/legal_notices/privacy_policy/1 \
  -H "ApiKey: your-private-api-key"

Response:


{
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-06-06T15:56:10.000+00:00",
    "content": "privacy policy legal text"
}
GET /legal_notices/:identifier

$ curl https://consent.iubenda.com/legal_notices/privacy_policy \
  -H "ApiKey: your-private-api-key"

Response:


[{
    "identifier": "privacy_policy",
    "version": 3,
    "timestamp": "2018-05-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}, {
    "identifier": "privacy_policy",
    "version": 2,
    "timestamp": "2018-03-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}, {
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-01-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}]

With limit and pagination parameters:


$ curl https://consent.iubenda.com/legal_notices/privacy_policy?limit=20&starting_after=3 \
  -H "ApiKey: your-private-api-key" \
  -G

Response:


[{
    "identifier": "privacy_policy",
    "version": 2,
    "timestamp": "2018-03-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}, {
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-01-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}]
POST /legal_notices

$legal_notice_data = array(
    "identifier" => "privacy_policy",
    "content" => "privacy policy legal text"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/legal_notices');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($legal_notice_data));

$response = curl_exec($req);

Response:


{
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-06-11T10:26:00.413Z"
}
GET /legal_notices

$legal_notice_data = array(
    "identifier" => "privacy_policy",
    "content" => "privacy policy legal text"
);

$req = curl_init();
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/legal_notices');
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));
curl_setopt($req, CURLOPT_POST, true);
curl_setopt($req, CURLOPT_POSTFIELDS, json_encode($legal_notice_data));

$response = curl_exec($req);

Response:


[{
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 20,
    "timestamp": "2018-10-09T12:38:04Z",
    "content": {
        "en": "Et vinculum clam decerno arguo admoveo velum sponte tot suppellex venustas defendo dolor decumbo est.",
        "it": "Collum tutis esse confugo porro urbs varius abscido turpis decor praesentium tardus voluptate fugit numquam."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 19,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Venia valde vel surculus capitulus adfectus patior comparo acsi cur vero super cursim.",
        "it": "Consuasor arcesso conscendo crudelis cauda aer aut adeptio illo argentum comis subiungo subito colo."
    }
}, {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 18,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Ullus voco aufero speculum fugiat audacia laboriosam vilicus amita trans aut ut.",
        "it": "Alo veritatis ipsa tristis cuius occaecati adflicto creta verecundia facere solvo despirmatio cupiditate crinis aqua bos."
    }
}, {
    "id": "0_privacy_policy",
    "owner_id": "0",
    "identifier": "privacy_policy",
    "version": 17,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Confero succedo caelum adhaero quo vir deorsum quaerat utor sit ustulo cribro.",
        "it": "Bibo cubitum unus est ambitus contego apparatus alo via abutor utroque xiphias voco."
    }
}, {
    "id": "0_privacy_policy",
    "owner_id": "0",
    "identifier": "privacy_policy",
    "version": 16,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Qui porro culpo attero benevolentia aut sed sulum adfero artificiose adsidue tam amo validus vel spectaculum.",
        "it": "Cerno ipsum fugit compello cursim ter surgo asporto debilito excepturi adversus facere."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 15,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Tunc timidus veritatis maiores advenio aperio testimonium defluo celo cuius adsuesco deripio.",
        "it": "Depulso dignissimos vinitor curatio caelestis cedo et sum concedo id admoneo appositus."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 14,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Repellat mollitia desidero videlicet est textilis stips nisi aequus solum depromo agnitio usus.",
        "it": "Vomito tonsor comitatus illum aut usitas laboriosam canonicus tepesco benigne confugo trado."
    }
}, {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 13,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Temperantia alias somniculosus absorbeo utique caecus terror demitto trucido desidero baiulus sublime.",
        "it": "Perspiciatis at tredecim curriculum comprehendo deduco corrupti attonbitus barba cruentus communis comparo thorax cauda spero vito anser."
    }
}, {
    "id": "0_cookie_policy",
    "owner_id": "0",
    "identifier": "cookie_policy",
    "version": 12,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Allatus cena surculus ventito ver adversus torrens demo venustas toties veritas qui cado vis.",
        "it": "Talio avoco aptus compono et subiungo peior bellum depromo aureus torqueo adeptio nobis."
    }
}, {
    "id": "0_term",
    "owner_id": "0",
    "identifier": "term",
    "version": 11,
    "timestamp": "2018-10-09T12:38:03Z",
    "content": {
        "en": "Aliquam cubicularis tergum utor cinis concido ratione vociferor uter deduco tertius verecundia alo claustrum sto vos aegrotatio.",
        "it": "Corona ut comes sub coaegresco caute casus laboriosam tremo vulariter aegrotatio pauci callide assentator basium."
    }
}]
GET /legal_notices/:identifier/:version

$req = curl_init();
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/legal_notices/privacy_policy/1');
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


{
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-06-11T10:26:00.000+00:00",
    "content": "privacy policy legal text"
}
GET /legal_notices/:identifier

$req = curl_init();
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/legal_notices/privacy_policy');
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


[{
    "identifier": "privacy_policy",
    "version": 3,
    "timestamp": "2018-05-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}, {
    "identifier": "privacy_policy",
    "version": 2,
    "timestamp": "2018-03-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}, {
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-01-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}]

With limit and pagination parameters:


$req = curl_init();
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_URL, 'https://consent.iubenda.com/legal_notices/privacy_policy?limit=3&starting_after=4');
curl_setopt($req, CURLOPT_HTTPHEADER, array(
    'ApiKey: your-secret-api-key',
    'Content-Type: application/json'
));

$response = curl_exec($req);

Response:


[{
    "identifier": "privacy_policy",
    "version": 2,
    "timestamp": "2018-03-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}, {
    "identifier": "privacy_policy",
    "version": 1,
    "timestamp": "2018-01-16T13:55:57Z",
    "id": "1234_privacy_policy",
    "owner_id": "1234",
    "content": "privacy policy content"
}]

See also

Still have questions?

Attend one of our free webinars Email us Live chat