Documentation

Consent Solution – HTTP API Documentation

The Consent Solution HTTP API allows you to record and retrieve consent actions performed by your users, which will be referred to from now on as subjects.

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.

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.

Rate Limits

By default, you can perform a maximum of 5 requests per second and 10800 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 350kb per call. Server-side, the API will respond with 413 Request Entity Too Large if these limits are exceeded.

Consent

list consents

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

Accepted query parameters:

subject_id optional String Filter consents by subject ID
preference_key optional String Filter consents having the provided preference key
starting_after optional String (UUID) Pagination cursor. Returns consents matched after the given id
limit optional Integer Number of results returned. Default 10. Min: 1, Max: 100

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

Response:

200 OK
[
  {
    "id": "bd25e1fc-da53-4b48-8fef-0ecb6068f666",
    "timestamp": "2018-06-11T15:20:07+00:00",
    "owner": "181789",
    "source": "public",
    "subject": {
      "id": "35d1f4ba-5a52-43d8-9fee-68e356a2a9bd",
      "email": "35d1f4ba_43d8_9fee_5a52_68e356a2a9bd@example.net",
      "first_name": "Filomena",
      "last_name": "Turcotte",
      "full_name": "Filomena Turcotte"
    },
    "preferences": {
      "newsletter": true
    }
  },
  {
    "id": "9b6c3cea-3350-4528-89ad-9148db358e20",
    "timestamp": "2018-06-11T15:20:07+00:00",
    "owner": "678255",
    "source": "private",
    "subject": {
      "id": "d685ed47-bdd8-44c4-92c4-0bbf961f2577",
      "email": "0bbf961f2577_92c4_bdd8_d685ed47_44c4@example.net",
      "first_name": "Rachael",
      "last_name": "Hammes",
      "full_name": "Rachael Hammes"
    },
    "preferences": {
      "newsletter": false
    }
  },
  {
    "id": "9783a523-f35e-4133-9875-0b6aed3bce32",
    "timestamp": "2018-06-11T15:20:07+00:00",
    "owner": "837689",
    "source": "public",
    "subject": {
      "id": "b6a14232-ba1a-4a20-afed-fa93c68eb5aa",
      "email": "afed.b6a14232.fa93c68eb5aa.4a20.ba1a@example.com",
      "first_name": "Oliver",
      "last_name": "Gibson",
      "full_name": "Oliver Gibson"
    },
    "preferences": {}
  },
  {
    "id": "92297398-e1fe-4e95-8f15-35d6dcb42897",
    "timestamp": "2018-06-11T15:20:07+00:00",
    "owner": "802558",
    "source": "private",
    "subject": {
      "id": "da024bf5-e571-499b-b20d-65a41789b5a6",
      "email": "e571_499b_65a41789b5a6_da024bf5_b20d@example.net",
      "first_name": "Ike",
      "last_name": "Miller",
      "full_name": "Ike Miller"
    },
    "preferences": {
      "third_party": true,
      "newsletter": true
    }
  },
  {
    "id": "7bbde760-b859-48bf-8cd3-9b1f035c8ef5",
    "timestamp": "2018-06-11T15:20:07+00:00",
    "owner": "615811",
    "source": "private",
    "subject": {
      "id": "a429fa55-c271-43f2-9ba1-8ce3b48c1093",
      "email": "43f2.a429fa55.8ce3b48c1093.9ba1.c271@example.com",
      "first_name": "Macy",
      "last_name": "Farrell",
      "full_name": "Macy Farrell"
    },
    "preferences": {
      "third_party": true,
      "newsletter": true
    }
  },
  {
    "id": "175aa1a4-b9ee-4278-8074-aa1b1384292a",
    "timestamp": "2018-06-11T15:20:07+00:00",
    "owner": "915663",
    "source": "private",
    "subject": {
      "id": "69753d3f-4048-401e-a3b2-112047b91e67",
      "email": "a3b2.4048.69753d3f.112047b91e67.401e@example.net",
      "first_name": "Kaleigh",
      "last_name": "Schulist",
      "full_name": "Kaleigh Schulist"
    },
    "preferences": {}
  },
  {
    "id": "fe7daa65-3d58-4c75-902f-ca0664442f73",
    "timestamp": "2018-06-11T15:20:06+00:00",
    "owner": "743776",
    "source": "public",
    "subject": {
      "id": "234fde6a-34b0-4371-b0a1-bac3436e6c12",
      "email": "bac3436e6c12.b0a1.4371.234fde6a.34b0@example.org",
      "first_name": "Carson",
      "last_name": "Heidenreich",
      "full_name": "Carson Heidenreich"
    },
    "preferences": {
      "newsletter": false
    }
  }
]

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.

CREATE consent

POST https://consent.iubenda.com/consent
{
  "subject": {
    "id": "J02eZvKYlo2ClwuJ1",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "verified": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": "123"
    },
    {
      "identifier": "terms",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof form"
    }
  ],
  "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": "J02eZvKYlo2ClwuJ1"
}

The consents method accepts the following fields. All fields are optional, but some are auto-filled if not provided.

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, terms or a custom identifier
  version auto-filled with latest 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

GET consent

GET https://consent.iubenda.com/consent/:id
200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "owner": "1234",
  "subject": {
    "id": "J02eZvKYlo2ClwuJ1",
    "email": "subject@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe"
    "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"
    }
  ]
}


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 |

Subjects

CREATE subject

POST https://consent.iubenda.com/subjects
{
  "id": "J02eZvKYlo2ClwuJ1",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "verified": false
}

This method will post a new subject.
This method 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
// Coming soon
custom_attributes optional Object A set of key-value pairs containing custom attributes

The response is the following:

200 OK
{
  "id": "J02eZvKYlo2ClwuJ1",
  "timestamp": "2018-05-04T14:52:26Z"
}

GET subject

GET https://consent.iubenda.com/subjects/:id
200 OK
{
  "id": "J02eZvKYlo2ClwuJ1",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "verified": false,
  "timestamp": "2018-05-04T14:52:26Z"
  "preferences": {
    "privacy_policy": {
      "value": true,
      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"
    },
    "newsletter": {
      "value": true,
      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"
    }
  }
}

Update subject

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

This call will update an existing subject.

The response is the following:

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

Legal Notices

Create a Legal Notice

POST /legal_notices
{
    "identifier": "privacy_policy",
    "content": "privacy policy content",
    "timestamp": "2018-05-16T13:55:57Z"
}

With multi-language content

POST /legal_notices
{
    "identifier": "privacy_policy",
    "content": {
        "en": "privacy policy content",
        "it": "contenuto della privacy policy"
    },
    "timestamp": "2018-05-16T13:55:57Z"
}

Response:

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

Create multiple Legal Notices

POST /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
    }

]

Get a Legal Notice version

GET /legal_notices/:identifier/:version

Response:

# GET /legal_notices/privacy_policy/1
# 200 OK
{
    "identifier": "privacy_policy",
    "content": "legal text",
    "timestamp": "2018-05-16T13:55:57Z",
    "version": 1
}

Get all legal notice versions

GET /legal_notices/:identifier

Accepted query parameters:

Name Value Description
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 paramater takes an existing Legal Notice version and returns objects in reverse order.

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

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.

Documentation (cURL | PHP)

API

Accepted Content Types: application/json or x-www-form-urlencoded.

Authentication

Each request must pass a private API key via the ApiKey header.
Public API keys are accepted only on POST /public/consent endpoint.

Consent

List Consents

GET /consent

Examples: cURL | PHP

# 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",
      "verified": false
    },
    "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
    }
  }
]
Accepted query parameters:
Name Value Description
subject_id optional String Filter by Subject ID. Default null
preference_key optional String Filter for consents in which the key exists. Default null
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. Default 10. Min: 1, Max: 100

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

Get a Consent

GET /consent/:id

Examples: cURL | PHP

# 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": "terms_and_conditions",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof_1 form"
    },
    {
      "content": "proof_2",
      "form": "proof_2 form"
    }
  ]
}

Create a Consent

POST /consent
{
  "subject": {
    "id": "testsubject",
    "email": "subject@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "verified": false
  },
  "legal_notices": [
    {
      "identifier": "privacy_policy",
      "version": "123"
    },
    {
      "identifier": "terms_and_conditions",
      "version": "123"
    }
  ],
  "proofs": [
    {
      "content": "proof_1",
      "form": "proof_1 form",
    },
    {
      "content": "proof_2",
      "form": "proof_2 form"
    }
  ],
  "preferences": {
    "newsletter": false,
    "privacy_policy": true
  }
}

Examples: cURL | PHP

# 200 OK
{
  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",
  "timestamp": "2018-05-04T14:52:26Z",
  "subject_id": "testsubject"
}

Subjects

Get a Subject

GET /subjects/:id

Examples: cURL | PHP

# 200 OK
{
  "id": "testsubject",
  "owner_id": "1",
  "email": "subject@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "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 a Subject

POST /subjects
{
  "id": "testsubject",
  "email": "subject@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "verified": false
}

Examples: cURL | PHP

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

Update a Subject

PUT|PATCH /subjects/:id
{
  "first_name": "Mary",
  "verified": true
}

Examples: cURL | PHP

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

Legal Notices

Create a Legal Notice

POST /legal_notices
{
  "identifier": "privacy_policy",
  "content": "privacy policy content",
  "timestamp": "2018-05-16T13:55:57Z"
}

Examples: cURL | PHP

with multi-language content
POST /legal_notices
{
  "identifier": "privacy_policy",
  "content": {
    "en": "privacy policy content",
    "it": "contenuto della privacy policy"
  },
  "timestamp": "2018-05-16T13:55:57Z"
}
# 200 OK
{
  "identifier": "privacy_policy",
  "timestamp": "2018-05-16T13:55:57Z",
  "version": 1
}

Create multiple Legal Notices

POST /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"
  }
]
# 200 OK
[
  {
    "identifier": "privacy_policy",
    "timestamp": "2018-05-16T13:55:57Z",
    "version": 1
  },
  {
    "identifier": "cookie_policy",
    "timestamp": "2018-05-16T13:55:57Z",
    "version": 1
  }
]

Get a Legal Notice version

GET /legal_notices/:identifier/:version

Examples: cURL | PHP

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

Get all Legal Notice versions

GET /legal_notices/:identifier

Examples: cURL | PHP

Accepted query parameters:
Name Value Description
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 paramater takes an existing Legal Notice version and returns objects in reverse order.

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

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.

Examples

cURL



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" }] }'



response

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

$ 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":"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","verified":false},"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}}]

$ 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-06-06T09:48:44.000+00:00","owner":"123","source":"public","subject":{"id":"J02eZvKYlo2ClwuJ1","email":"subject@example.com"},"preferences":{"newsletter":"true"},"legal_notices":[{"identifier":"privacy_policy","version":"latest"}],"proofs":[{"form":"proof_form","content":"proof_content"}]}



subject

$ 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"}

$ 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"}

$ 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"}



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"}

$ 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"}

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



response

[{"identifier":"privacy_policy","version":1,"timestamp":"2018-06-06T15:56:10.000+00:00"}]


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-06-06T15:56:10.000+00:00"},{"identifier":"privacy_policy","version":1,"timestamp":"2018-06-06T15:56:10.000+00:00"}]


PHP



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
    )
);

$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"}

$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":"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","verified":false},"preferences":{"newsletter":false}}]

$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":"7abe5f70-22e4-4181-878c-9f931034fab5","timestamp":"2018-06-08T08:25:30.000+00:00","owner":"123","source":"private","subject":{"id":"J02eZvKYlo2ClwuJ1","email":"subject@example.com"},"preferences":{"newsletter":true,"privacy_policy":true},"legal_notices":[{"identifier":"newsletter","version":"1.0"},{"identifier":"privacy_policy","version":"1.0"}],"proofs":[{"form":"proof_form","content":"proof_content"}]}



subject

$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"}

$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":"df39c1bf-5f27-4c3a-bf94-64360cc7e4f8","owner_id":"123","email":"subject@example.com","first_name":"John","last_name":"Doe","full_name":null,"preferences":null,"verified":false,"timestamp":"2018-06-11T08:57:13+00:00"}

$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"}



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"}

$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"}

$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":5,"timestamp":"2018-06-11T10:35:17.000+00:00"},{"identifier":"privacy_policy","version":4,"timestamp":"2018-06-11T10:35:16.000+00:00"},{"identifier":"privacy_policy","version":3,"timestamp":"2018-06-11T10:35:15.000+00:00"},{"identifier":"privacy_policy","version":2,"timestamp":"2018-06-11T10:35:13.000+00:00"},{"identifier":"privacy_policy","version":1,"timestamp":"2018-06-11T10:26:00.000+00:00"}]


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":3,"timestamp":"2018-06-11T10:35:15.000+00:00"},{"identifier":"privacy_policy","version":2,"timestamp":"2018-06-11T10:35:13.000+00:00"},{"identifier":"privacy_policy","version":1,"timestamp":"2018-06-11T10:26:00.000+00:00"}]

Still have questions?

Visit our support forum Email us