Subscriptions protocol

Request Types

Common Objects

Identity

The Identity object describes the identity of a Data Subject.

{
  "identitySpace": "account_id",
  "identityFormat": "raw",
  "identityValue": "123"
}

Fields

namerequired?description
identitySpaceyesIdentity space code setup in Ketch
identityFormatnoFormat of the identity value (raw, md5, sha1). Default is raw.
identityValueyesValue of the identity

SubscriptionControlSetting

The SubscriptionControlSetting object describes the settings of a SubscriptionControl.

{
  "status": "granted"
}

Fields

namerequired?description
statusyesSubscriptionStatus of the control.

SubscriptionTopicSetting

The SubscriptionTopicSetting object describes the settings of a SubscriptionTopic.

{
  "status": "granted"
}

Fields

namerequired?description
statusyesSubscriptionStatus of the topic.

SubscriptionStatus

The SubscriptionStatus enum identifies the status of a SubscriptionTopic or SubscriptionControl.

valuedescription
grantedThe subscription topic/control is allowed by the user
deniedThe subscription topic/control is denied by the user

SubscriptionControl Request

A SubscriptionControl Request is initiated when a Data Subject invokes a global subscription control.

POST /endpoint HTTP/1.1
Host: www.example.com
Content-Type: application/json
Accept: application/json
Authorization: $auth

{
  "apiVersion": "subscription/v1",
  "kind": "SubscriptionControlRequest",
  "metadata": {
    "uid": "22880925-aac5-42f9-a653-cb6921d361ff",
    "tenant": "axonic"
  },
  "request": {
    "controller": "axonic",
    "property": "axonic.io",
    "environment": "production",
    "identities": [
      {
        "identitySpace": "account_id",
        "identityFormat": "raw",
        "identityValue": "123"
      }
    ],
    "controls": {
      "global_subscription": {
        "status": "denied"
      }
    },
    "submittedTimestamp": 123
  }
}

Fields

namerequired?description
apiVersionyesAPI version. Must be subscription/v1
kindyesMessage kind. Must be SubscriptionControlRequest
metadatayesMetadata object
request.controllernoCode of the Ketch controller tenant. Only supplied if the ultimate controller is different to the metadata.tenant
request.propertyyesCode of the digital property defined in Ketch
request.environmentyesCode environment defined in Ketch
request.identitiesyesArray of Identities
request.controlsyesMap of subscription control codes mapped to SubscriptionControlSetting enum.
request.submittedTimestampyesUNIX timestamp in seconds

Consent Response

A successful response SHOULD return either 202 Accepted or 204 No Content response status code.

HTTP/1.1 202 Accepted

or

HTTP/1.1 204 No Content

SubscriptionTopic Request

A SubscriptionTopic Request is initiated when a Data Subject subscribes to or unsubscribes from a subscription topic.

POST /endpoint HTTP/1.1
Host: www.example.com
Content-Type: application/json
Accept: application/json
Authorization: $auth

{
  "apiVersion": "subscription/v1",
  "kind": "SubscriptionTopicRequest",
  "metadata": {
    "uid": "22880925-aac5-42f9-a653-cb6921d361ff",
    "tenant": "axonic"
  },
  "request": {
    "controller": "axonic",
    "property": "axonic.io",
    "environment": "production",
    "identities": [
      {
        "identitySpace": "account_id",
        "identityFormat": "raw",
        "identityValue": "123"
      }
    ],
    "topics": {
      "competitions": {
        "email": {
          "status": "granted"
        },
        "sms": {
          "status": "denied"
        }
      },
      "marketing": {
        "email": {
          "status": "denied"
        },
        "sms": {
          "status": "denied"
        }
      }
    },
    "submittedTimestamp": 123
  }
}

Fields

namerequired?description
apiVersionyesAPI version. Must be subscription/v1
kindyesMessage kind. Must be SubscriptionTopicRequest
metadatayesMetadata object
request.controllernoCode of the Ketch controller tenant. Only supplied if the ultimate controller is different to the metadata.tenant
request.propertyyesCode of the digital property defined in Ketch
request.environmentyesCode environment defined in Ketch
request.identitiesyesArray of Identities
request.topicsyesMap of subscription topics codes mapped to a map of channels mapped to SubscriptionTopicSetting.
request.submittedTimestampyesUNIX timestamp in seconds

Consent Response

A successful response SHOULD return either 202 Accepted or 204 No Content response status code.

HTTP/1.1 202 Accepted

or

HTTP/1.1 204 No Content