Skip to main content

Retrieving Consent Types

This guide explains how to retrieve all consent types from your Consent Catalog, as well as how to fetch details for a specific consent type using the provided API endpoints.

Overview​

The Consent Catalog allows you to define and manage various consent types for purposes like privacy policies, marketing preferences, and other agreements. These endpoints allow you to retrieve all consent types or get detailed information on a specific consent type.

Available Endpoints​

  1. Get All Consent Types: /open-api/v1/consent-catalog/
  2. Get a Specific Consent Type: /open-api/v1/consent-catalog/{consentCatalogId}

Endpoint​

GET /open-api/v1/consent-catalog/

Purpose​

This endpoint retrieves all consent types defined in your catalog, returning a list of consent types with details such as the type, title, description, and the latest version.

Request Structure​

URL​

GET https://api.platform.illow.io/open-api/v1/consent-catalog/

Headers​

HeaderTypeRequiredDescription
X-API-KeyStringYesAPI Key for your account

Response Structure​

The response returns a list of consent types in the following format:

[
  {
    "companyId": "string",
    "id": "string",
    "title": "string",
    "description": "string",
    "type": "string",
    "latestVersion": "string"
  }
]

Response Body Details​

  • companyId (string): The unique ID of your company.
  • id (string): The unique ID of the consent type.
  • title (string): The title of the consent type.
  • description (string): A brief description of the consent type.
  • type (string): The type of consent (e.g., "privacyPolicy").
  • latestVersion (string): The latest version number of the consent type.

Example Request​

curl -X GET https://api.platform.illow.io/open-api/v1/consent-catalog/ \
-H "X-API-Key: YOUR_API_KEY"

Example Response​

[
  {
    "companyId": "b830b5fa-9180-4cb6-9f40-4cbe4729d0ac",
    "id": "44499771-03fb-4f0c-8620-88f538385446",
    "title": "User Tracking Consent",
    "description": "Consent for tracking user activities across the site.",
    "type": "privacyPolicy",
    "latestVersion": "1"
  },
  {
    "companyId": "b830b5fa-9180-4cb6-9f40-4cbe4729d0ac",
    "id": "e57997e3-6cfc-4d63-9a4f-6a7f31b37f57",
    "title": "Marketing Preferences",
    "description": "Consent for receiving marketing communications.",
    "type": "marketing",
    "latestVersion": "1"
  }
]

Response Codes​

  • 200 OK: The list of consent types was successfully retrieved.
  • 500 Internal Server Error: An unexpected error occurred.

Best Practices​

  • Make sure your API Key is correct and valid before making the request.
  • Handle pagination if your catalog contains a large number of consent types to avoid performance issues.

Endpoint​

GET /open-api/v1/consent-catalog/{consentCatalogId}

Purpose​

This endpoint retrieves the details of a specific consent type by its unique ID. This is useful for accessing detailed information about a particular consent entry, such as the URL of the policy and its description.

Request Structure​

URL​

GET https://api.platform.illow.io/open-api/v1/consent-catalog/{consentCatalogId}

Replace {consentCatalogId} with the ID of the consent type you want to retrieve.

Headers​

HeaderTypeRequiredDescription
X-API-KeyStringYesAPI Key for your account

Response Structure​

The response for a specific consent type follows this format:

{
  "companyId": "string",
  "id": "string",
  "title": "string",
  "description": "string",
  "type": "string",
  "latestVersion": "string",
  "typeEntry": {
    "url": "string",
    "description": "string"
  }
}

Response Body Details​

This structure includes the same fields as the list of consent types with the addition of the typeEntry object, which contains:

  • url (string): The URL of the policy.
  • description (string): A description of the version entry, such as when it was last updated.

Example Request​

curl -X GET https://api.platform.illow.io/open-api/v1/consent-catalog/44499771-03fb-4f0c-8620-88f538385446 \
-H "X-API-Key: YOUR_API_KEY"

Example Response​

{
  "companyId": "b830b5fa-9180-4cb6-9f40-4cbe4729d0ac",
  "id": "44499771-03fb-4f0c-8620-88f538385446",
  "title": "User Tracking Consent",
  "description": "Consent for tracking user activities across the site.",
  "type": "privacyPolicy",
  "latestVersion": "1",
  "typeEntry": {
    "url": "https://example.com/policy/1",
    "description": "This policy was updated this day, so a new version was created."
  }
}

Response Codes​

  • 200 OK: The consent type details were successfully retrieved.
  • 200 Bad Request: The consentCatalogId provided is invalid.
  • 404 Not Found: The specified consent type was not found.
  • 500 Internal Server Error: An unexpected error occurred.

Best Practices​

  • Ensure the consentCatalogId is correct before making the request.
  • Cache the results if you frequently access the same consent type to improve performance.

Additional Resources​