Management APIData Layer

Data Layer

The organisation data layer is the tenant-wide data governance schema. It declares which fields are PII and how they are handled, which fields are standardised, and optional schema validation rules. The rules apply to every event in the organisation before per-integration transformations run. In the management UI it is edited on the Data Governance page, which uses these endpoints.

Data Layer Object

{
  "id": "5d0c7a4e-2b1f-4f5a-9e3d-8c7b6a5f4e3d",
  "org_id": "0b8e2f4a-6c1d-4e9b-a7f3-2d5c8e1b9a6f",
  "schema": {
    "policy": "warn",
    "properties": {
      "properties.email": { "type": "email", "pii": true, "action": "hash", "transform": "lowercase" },
      "properties.phone": { "type": "phone", "pii": true, "action": "hash", "transform": "e164_phone" },
      "properties.coupon": { "transform": "uppercase" }
    },
    "events": {
      "purchase": {
        "event_type": "track",
        "required": ["transaction_id", "value"],
        "properties": {
          "currency": { "type": "string", "enum": ["GBP", "EUR", "USD"] }
        }
      }
    }
  },
  "mappings": {},
  "defaults": {},
  "version": 1,
  "created_at": "2026-02-20T14:00:00Z",
  "updated_at": "2026-02-20T14:00:00Z"
}
FieldTypeDescription
schemaobjectThe governance schema (see below)
mappingsobjectReserved for future use. Stored and returned unchanged
defaultsobjectReserved for future use. Stored and returned unchanged
versioninteger0 when the organisation has not saved a data layer yet

When no data layer has been saved, GET returns empty schema, mappings and defaults objects.

Schema

Field rules (schema.properties)

Each key is a dotted path into the event as it appears in JSON (for example properties.email or context.page.url). Each value can set:

KeyTypeDescription
piibooleanMarks the field as PII. Viewing surfaces such as the Event Debugger redact it even when action is none
actionstringWhat happens to the value before any integration sees it: hash (SHA-256), mask, strip (remove) or none
typestringExpected type, used for validation. email, phone and ip_address also tell mask how to mask the value
enumstring[]Allowed values, used for validation
transformstringStandardisation applied before the PII action: lowercase, uppercase, titlecase, trim, e164_phone or rename
target_fieldstringDestination path for rename (defaults to the same field)

A field produces a PII rule when pii is true or action is hash, mask or strip, and a standardisation rule when transform is set.

Event rules (schema.events)

Keyed by event name. Each entry can list required properties and properties with type / enum checks. Bare names (such as transaction_id) are read from the event’s properties; dotted names are read from the event root. event_type is informational.

schema.required at the root lists properties required on every event.

Validation policy (schema.policy)

ValueBehaviour when an event breaks a validation rule
strictThe event is rejected, sent to the dead-letter queue and not delivered
warn or unsetThe violation is logged and the event continues

Validation only runs when the schema declares at least one required, type or enum rule.

The data layer has no settings for sessions, bot filtering, custom JavaScript or event routing. Sessions are set per pipeline in the Collector tab (assigned by Datafly.js in the browser or by Signal on your collection domain, with a configurable inactivity timeout); bot filtering is configured per pipeline; event filtering and transformations are configured on the pipeline and its integrations.

Get Data Layer

GET /v1/admin/org/data-layer

Retrieve the organisation’s data layer.

Request:

curl -X GET http://localhost:8084/v1/admin/org/data-layer \
  -H "Authorization: Bearer {access_token}"

Response: The data layer object shown above.

Required role: org_admin.

Update Data Layer

PUT /v1/admin/org/data-layer

Replace the organisation’s data layer. Send schema and, optionally, mappings and defaults. Each must be valid JSON; an omitted field is stored as an empty object.

Request:

{
  "schema": {
    "policy": "warn",
    "properties": {
      "properties.email": { "type": "email", "pii": true, "action": "hash", "transform": "lowercase" }
    }
  }
}

Response: The updated data layer object.

Required role: org_admin.

⚠️

The saved schema replaces the previous one and applies to all events across all pipelines in the organisation. Try changes with the test endpoint below before saving.

Test Data Layer

POST /v1/admin/org/data-layer/test

Run a sample event through a candidate schema without saving anything. Standardisation rules are applied first, then PII rules, then validation, in the same order as the event processor.

Request:

{
  "schema": {
    "properties": {
      "properties.email": { "type": "email", "pii": true, "action": "hash", "transform": "lowercase" }
    }
  },
  "sample_event": {
    "type": "track",
    "event": "sign_up",
    "properties": { "email": " Jane@Example.com " }
  }
}

Response:

{
  "success": true,
  "input": { "type": "track", "event": "sign_up", "properties": { "email": " Jane@Example.com " } },
  "output": { "type": "track", "event": "sign_up", "properties": { "email": "<sha256 hex>" } },
  "validation_errors": [],
  "applied": {
    "standardise_rules": [{ "source_field": "properties.email", "target_field": "properties.email", "transform": "lowercase" }],
    "pii_fields": [{ "field": "properties.email", "classification": "email", "action": "hash", "pii": true }]
  }
}

Required role: org_admin.

TransformationsDead Letter Queue