Skip to main content

Consent Masters API

Consent Masters APIs designate catalog data products as authoritative consent datasets, map source-system consent values to privacy notice processing purposes, generate subject lookup SQL, and check purpose compatibility during access requests.

info

All endpoints are mounted under /api/v1.0. Paths below omit that global prefix.

Endpoints​

MethodEndpointDescription
GET/spaces/{slug}/consent-mastersList consent masters in a space.
POST/spaces/{slug}/consent-masters/{product_id}Designate or update a product as a consent master.
GET/spaces/{slug}/consent-masters/{product_id}Read one consent master.
DELETE/spaces/{slug}/consent-masters/{product_id}Revoke a consent master designation.
GET/spaces/{slug}/consent-masters/{product_id}/lookup-sqlGenerate subject lookup SQL for a consent master.
GET/spaces/{slug}/consent/purpose-compatibilityCheck an intended purpose against a product's authorized purpose.
GET/organizations/{org_slug}/consent-mastersList consent masters across accessible spaces in an organization.

Space endpoints require access to the target space. Organization listing requires access to the organization and returns only consent masters from spaces visible to the caller.

Data Model​

Column Mapping​

{
  "subject_id_column": "customer_id",
  "consent_type_column": "consent_code",
  "notice_version_column": "notice_version"
}
FieldRequiredDescription
subject_id_columnYesColumn holding the data-subject identifier.
consent_type_columnYesColumn holding the raw consent type, topic, or purpose code.
notice_version_columnNoColumn holding the accepted privacy notice version.

Purpose Mapping​

{
  "purpose_id": "processing-purpose-uuid",
  "purpose_value": "marketing_opt_in"
}

purpose_id references a processing purpose from a privacy notice in the space. purpose_value is the literal value found in the consent type column.

GET /spaces/acme/consent-masters

Response:

[
  {
    "product_id": "product-uuid",
    "product_name": "Customer Consent Ledger",
    "is_consent_master": true,
    "column_mapping": {
      "subject_id_column": "customer_id",
      "consent_type_column": "consent_code",
      "notice_version_column": "notice_version"
    },
    "purpose_mappings": [
      {
        "id": "mapping-uuid",
        "purpose_id": "purpose-uuid",
        "purpose_value": "marketing_opt_in",
        "purpose_name": "Marketing Analytics",
        "purpose_description": "Personalized marketing measurement",
        "created_at": "2026-06-29T10:00:00Z"
      }
    ]
  }
]

Archived products are excluded.

Organization Listing​

GET /organizations/acme/consent-masters

Organization responses use the same shape as space responses and add source space metadata:

{
  "product_id": "product-uuid",
  "product_slug": "customer-consent-ledger",
  "product_name": "Customer Consent Ledger",
  "space_id": "space-uuid",
  "space_name": "Customer Data",
  "space_slug": "customer-data",
  "is_consent_master": true,
  "column_mapping": {
    "subject_id_column": "customer_id",
    "consent_type_column": "consent_code",
    "notice_version_column": null
  },
  "purpose_mappings": []
}

Designate Or Update​

POST /spaces/acme/consent-masters/{product_id}
{
  "column_mapping": {
    "subject_id_column": "customer_id",
    "consent_type_column": "consent_code",
    "notice_version_column": "notice_version"
  },
  "purpose_mappings": [
    {
      "purpose_id": "purpose-uuid",
      "purpose_value": "marketing_opt_in"
    },
    {
      "purpose_id": "purpose-uuid-2",
      "purpose_value": "research_panel"
    }
  ]
}

The endpoint sets is_consent_master to true, stores the column mapping on the data product, and replaces existing purpose mappings with the submitted list.

Response shape matches the consent master list item. The endpoint returns 404 when the product does not exist in the requested space.

GET /spaces/acme/consent-masters/{product_id}

Returns the consent master response for one product. Returns 404 when the product is not in the space, is archived, or is not designated as a consent master.

Revoke Designation​

DELETE /spaces/acme/consent-masters/{product_id}

Response:

{
  "message": "Consent master designation revoked"
}

Revocation clears the consent-master flag, removes the stored column mapping, and deletes purpose mappings for the product. It does not delete the product or the source consent records.

Lookup SQL​

GET /spaces/acme/consent-masters/{product_id}/lookup-sql

Response:

{
  "sql": "SELECT customer_id, consent_code, notice_version\nFROM warehouse.privacy.customer_consent\nWHERE customer_id = '<SUBJECT_ID>';",
  "description": "Look up all consent records for a specific data subject in the 'Customer Consent Ledger' Consent Master dataset. Replace <SUBJECT_ID> with the actual identifier."
}

The generated SQL uses the product's hosting location when available. If the product has no hosting location, the table reference falls back to <your_warehouse>.{product_name}. Treat the SQL as a template and adapt it to the destination warehouse before execution.

Purpose Compatibility​

GET /spaces/acme/consent/purpose-compatibility?product_id=product-uuid&intended_purpose=Marketing%20Analytics

Response:

{
  "is_compatible": true,
  "intended_purpose": "Marketing Analytics",
  "authorized_purpose": "Marketing Analytics",
  "lawful_basis": "Consent",
  "recommendation": "Purpose compatible: 'Marketing Analytics' matches the authorized purpose."
}

The current compatibility check is a case-insensitive exact match between intended_purpose and the product's authorized processing purpose. If the product has no authorized purpose, the endpoint returns is_compatible: true with a recommendation that the check was bypassed.

Errors​

StatusMeaning
400Invalid payload or missing required query parameter.
401Missing or expired authentication.
403Caller cannot access the target space or organization.
404Product, organization, or consent master not found.