NAV Navbar
shell

Introduction

Welcome to the Metomic API documentation!

You can use this API to manage and query the agreements of your users for the policies you publish.

Any policies you create using this API are consumable by the Metomic JS client library.

Identifiers

Many of the entities mentioned in this document refer to a slug.

A slug is just a human readable id. You can create a policy with any id you like, but We believe it's much easier when policies have understandable ids.

We encourage this by using the term slug in preference to id when readability is important.

Policy Versioning

Each policy in Metomic has a slug and a version. Whenever a user is presented with, or consents to a policy, they interact with a particular version of that policy.

This allows Metomic to keep track of the changes to policies, and know when to ask users for re-consent for policy updates that may affect them.

Version syntax

We use semver syntax to represent policy versions, and [slug]@[version] syntax to denote a particular policy with a particular verson.

For example, the identifier cookies@1.2.0 refers to the policy with slug cookie which has version 1.2.0.

We also support the special syntax [slug]@latest to refer to the latest version of a policy (regardless of whether or not it is published).

Published vs Draft policies

Policies can of course be edited. When an edit is made to a policy, a new draft version of that policy is created.

At any subsequent point in time, a draft policy can be published. Publishing a policy may necessitate re-consent from users, depending on the policy configuration.

Authentication

To send an authorised request, use this code:

curl "api_endpoint_here"
    -H "Authorization: YOUR_API_KEY"
    # ... the rest of your request

Make sure to replace YOUR_API_KEY with your API key.

Metomic uses API keys to allow access to the API. You can register a new Metomic API key in the developer section of your Metomic dashboard.

Metomic expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

Policies

Get All Policies

curl "https://api.metomic.io/policies"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"

The above command returns all policies, keyed by their slug:

{
    "shopping-suggestions": {
        "slug": "shopping-suggestions",
        "icon": "messages",
        "title": "Shopping suggestions",
        "short": "recommended goods based on previous purchases",
        "description": "As we learn a little about you, we're able to suggest relevant products that we think you might like.",
        "allow_anonymous": true,
        "version": "0.2.0",
        "draft_version": null,
        "created_at": 1537800711273,
        "versioned_at": 1537800795418,
        "published_at": 1537800795424,
        "clauses": [
            {
                "title": "age",
                "slug": "age",
                "description": "this helps us know whether our suggestions are age appropriate"
            },
            {
                "title": "eye color",
                "slug": "eye-color",
                "description": "this helps us simplify our algorithm"
            }
        ]
    },
    "recommendations":{
        ...
    },
    "cookies":{
        ...
    },
    ...
}

This endpoint retrieves all published policies.

HTTP Request

GET https://api.metomic.io/policies

Get a specific Policy

curl "https://metomic.io/policies/:policyId[@version]"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"

The above command returns a policy:

{
    "slug": "shopping-suggestions",
    "icon": "messages",
    "title": "Shopping suggestions",
    "short": "recommended goods based on previous purchases",
    "description": "As we learn a little about you, we're able to suggest relevant products that we think you might like.",
    "allow_anonymous": false,
    "version": "0.2.0",
    "draft_version": null,
    "created_at": 1537800711273,
    "versioned_at": 1537800795418,
    "published_at": 1537800795424,
    "clauses": [
        {
            "title": "age",
            "slug": "age",
            "description": "this helps us know whether our suggestions are age appropriate"
        },
        {
            "title": "eye color",
            "slug": "eye-color",
            "description": "this helps us simplify our algorithm"
        }
    ]
}

This endpoint retrieves a specific policy.

HTTP Request

GET https://metomic.io/policies/:slug

URL Parameters

Parameter Description
slug The identifier of the policy to retrieve
version The version of the policy to retrieve

Create / Update a Policy

curl -X POST "https://metomic.io/policies/:policyId[?publish=true]"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"
    -d @body.json:
{
    "slug": "shopping-suggestions",
    "icon": "messages",
    "title": "Shopping suggestions",
    "short": "recommended goods based on previous purchases",
    "description": "As we learn a little about you, we're able to suggest relevant products that we think you might like.",
    "allow_anonymous": false,
    "clauses": [
        {
            "title": "age",
            "slug": "age",
            "description": "this helps us know whether our suggestions are age appropriate"
        },
        {
            "title": "eye color",
            "slug": "eye-color",
            "description": "this helps us simplify our algorithm"
        }
    ]
}

The above command returns the created or updated policy:

{
    "slug": "shopping-suggestions",
    "version": "0.0.1",
    "icon": "messages",
    "title": "Shopping suggestions",
    "short": "recommended goods based on previous purchases",
    "description": "As we learn a little about you, we're able to suggest relevant products that we think you might like.",
    "allow_anonymous": false,
    "clauses": [
        {
            "title": "age",
            "slug": "age",
            "description": "this helps us know whether our suggestions are age appropriate"
        },
        {
            "title": "eye color",
            "slug": "eye-color",
            "description": "this helps us simplify our algorithm"
        }
    ],
    "draft_version": "0.0.1",
    "created_at": 1537800711273,
    "versioned_at": 1537800711273,
    "published_at": null,
}

This endpoint creates or updates a policy, and optionally publishes it

HTTP Request

POST https://metomic.io/policies/:slug

Query Parameters

Parameter | Description publish | When publish has value "true", the created policy will also be published

URL Parameters

Parameter Description
slug The identifier of the policy to retrieve
version The version of the policy to retrieve

Publish a policy

curl -X PUT "https://metomic.io/policies/:policyId/published_version"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"
    -d @body.json:

The above command returns the published policy:

{
    "slug": "shopping-suggestions",
    "version": "1.0.0",
    "icon": "messages",
    "title": "Shopping suggestions",
    "short": "recommended goods based on previous purchases",
    "description": "As we learn a little about you, we're able to suggest relevant products that we think you might like.",
    "allow_anonymous": false,
    "clauses": [
        {
            "title": "age",
            "slug": "age",
            "description": "this helps us know whether our suggestions are age appropriate"
        },
        {
            "title": "eye color",
            "slug": "eye-color",
            "description": "this helps us simplify our algorithm"
        }
    ],
    "draft_version": null,
    "created_at": 1537800711273,
    "versioned_at": 1537800711273,
    "published_at": 15378238374562,
}

This endpoint publishes the latest draft version of a policy

HTTP Request

PUT https://metomic.io/policies/:slug/published_version

URL Parameters

Parameter Description
slug The identifier of the policy to publish

Consumer agreements

The Metomic client library makes requests to the API to accept and reject consent for policies on behalf of a user.

The API then exposes the agreements made by a particular user to your systems.

Consumer Authentication

In order for the client-side Metomic script to make authenticated requests on behalf of the consumer, it needs a token (requested by your backend) which proves the user's identity.

This token should be passed along to the client after they have authenticate with your own systems.

Create consumer authentication token

curl -X POST "https://metomic.io/consumer/:known_user_id/token[?ttl=<seconds>]"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"

The above command creates a secure access token for a user of your product claiming to have an id of :known_user_id

{
        "metomic_access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6InlvdXItY2xpZW50LWlkIiwiY29uc3VtZXJJZCI6InNvbWUtdXNlci1pZCIsImlzcyI6Im1ldG9taWMiLCJleHAiOjE1Mzc4NDg0NTIsImlhdCI6MTUzNzg0ODQwMn0.kcBg-kXnZXX3-oXEhrOPy2BRxHUBYi2A4927Wtmb5GE"
}

This endpoint creates an access token that can be provided to the Metomic JS library to authenticate your user.

HTTP Request

POST https://metomic.io/consumer/:known_user_id/token[?ttl=<seconds>]

URL Parameters

Parameter Description
known_user_id The id that you have for this user

Query Parameters

Parameter Description Default
ttl The number of seconds for which this token should remain valid 1 hour

Get a user policy agreement

curl -X GET "https://metomic.io/consumer/:known_user_id/agreements/:policy_slug"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"

The above command returns an agreement for the specified policy

{
    "slug": "shopping-suggestions",
    "version": "1.3.0",
    "status": "rejected",
    "timestamp": 1537800711273
}

This endpoint retrieves the agreement status of a particular policy for a particular user

HTTP Request

GET https://metomic.io/consumer/:known_user_id/agreements/:policy_slug

URL Parameters

Parameter Description
known_user_id The id that you have for this user
policy_slug The identifier of the policy for which to return an agreement status

Responses

Status Description
200 The user has provided an explicit consent/reject intent for this policy
404 The user has never interacted with this policy

Get all policy agreements for user

curl -X GET "https://metomic.io/consumer/:known_user_id/agreements"
    -H "Authorization: YOUR_API_KEY"
    -H "Content-Type: application/json"

The above command returns all agreements for the specified user

{
    "shopping-suggestions":{
        "slug": "shopping-suggestions",
        "version": "1.3.0",
        "status": "rejected",
        "timestamp": 1537800711273
    },
    "contact":{
        "slug": "contact",
        "version": "1.0.0",
        "status": "accepted",
        "timestamp": 1537800711273
    },
    ...
}

This endpoint retrieves all the policy agreements that a user has provided.

HTTP Request

GET https://metomic.io/consumer/:known_user_id/agreements

URL Parameters

Parameter Description
known_user_id The id that you have for this user