API Reference

The consent Kit API uses standard REST practices. Resource-orientated URLs, returns JSON encoded responses and uses standard HTTP response codes, authentication and verbs.

Authentication

All the API endpoints for Consent Kit require authentication. We allow the following methods

OAuth2 tokens
API keys (coming soon)

Oauth2 tokens

You can use the OAuth2 token by passing it in the header

Responses

We use conventional HTTP response codes to indicate the success or failure of an API request

2xx range indicates a success
4xx range indicates an an error that there was some missing provided information
5xx range means there is something wrong on our end

Common errors

400

This only usually happens on creating objects when a validation error is caused. Usually missing a required field

401

When an invalid key or token is provided

404

A 404 is caused when a missing resource is requested. For example when the resource with the requested id does not exist

Projects

project objects represent the projects that are within your organisation.

The project object

Attributes

id
string
Unique identifier for the object
object
string
Name of the object type
created_at
timestamp
When the object was created
updated_at
timestamp
When the object was last updated
app_url
string
The URL for the project within the Consent Kit App

Response

{
  "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
  "object": "project",
  "name": "Project name",
  "created_at": "2021-01-18T10:06:30+00:00",
  "updated_at": "2021-01-18T10:06:30+00:00",
  "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
}

List all projects

Returns a list of all your organisations projects. Sorted by creation date.

Parameters

limit
optional
A limit on the number of objects returned, the default is 20
page
optional
Combined with a limit or the default to be able to paginate through all the objects, the default is 1

Returns

A list object with a data property that contains an array of up to limit projects, using the page as a starting point. Each entry in the array is a separate project object. If no more project are available, the resulting array will be empty.

This request should never return an error.

GET /v1/projects

$ curl 'https://api.consentkit.com/v1/projects' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "object": "list",
  "count": 99,
  "data": [
    {
      "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
      "object": "project",
      "name": "Project name",
      "created_at": "2021-01-18T10:06:30+00:00",
      "updated_at": "2021-01-18T10:06:30+00:00",
      "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
    },
    {...},
    {...}
  ]
}

Retrieve a project

Retrieves the details for a project. You only need to supply the unique project identifier.

Parameters

None

Returns

Returns a project object if a valid identifier was provided.

GET /v1/projects/:id

$ curl 'https://api.consentkit.com/v1/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
  "object": "project",
  "name": "Project name",
  "created_at": "2021-01-18T10:06:30+00:00",
  "updated_at": "2021-01-18T10:06:30+00:00",
  "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
}

Studies

Study objects represent the events that are within your organisation.

The event object

Attributes

id
string
Unique identifier for the object
object
string
Name of the object type. This will be "event".
created_at
timestamp
When the object was created
updated_at
timestamp
When the object was last updated
app_url
string
The URL for the event within the Consent Kit App
project
object
The project that the event is associated with.

Response

{
  "id": "evt_8SaYJK8AgbpG6FXpddJgfsVM",
  "object": "event",
  "name": "Interview with customers",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "project": {
    "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
    "object": "project",
    "name": "Project name",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
  },
  "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
}

Create a study

Create a study within a project.

Parameters

project_id
required
The unique identifier for a project
name
required
The name for the new event

Returns

Returns the event object if the create succeeded. Returns an error if create parameters are invalid

POST /v1/events

$ curl 'https://api.consentkit.com/v1/events' \
    -X POST \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN' \
    -H "Content-Type: application/json" \
    -d '{
    "project_id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
    "name": "Interview with customers"
    }'

Response

{
  "id": "evt_8SaYJK8AgbpG6FXpddJgfsVM",
  "object": "event",
  "name": "Interview with customers",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "project": {
    "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
    "object": "project",
    "name": "Project name",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
  },
  "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
}

List all events

Returns a list of all your organisations events. Sorted by creation date.

Parameters

limit
optional
A limit on the number of objects returned, the default is 20
page
optional
Combined with a limit or the default to be able to paginate through all the objects, the default is 1

Returns

A list object with a data property that contains an array of up to limit events, using the page as a starting point. Each entry in the array is a separate event object. If no more event are available, the resulting array will be empty.

This request should never return an error.

GET /v1/events

$ curl 'https://api.consentkit.com/v1/events' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "object": "list",
  "count": 99,
  "data": [
    {
      "id": "evt_8SaYJK8AgbpG6FXpddJgfsVM",
      "object": "event",
      "name": "Interview with customers",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "project": {
        "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
        "object": "project",
        "name": "Project name",
        "created_at": "2021-02-16T10:29:30+00:00",
        "updated_at": "2021-02-16T10:29:30+00:00",
        "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
      },
      "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
    },
    {...},
    {...}
  ]
}

Retrieve a event

Retrieves the details for a event. You only need to supply the unique event identifier.

Parameters

None

Returns

Returns a event object if a valid identifier was provided.

GET /v1/events/:id

$ curl 'https://api.consentkit.com/v1/events/evt_8SaYJK8AgbpG6FXpddJgfsVM' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "id": "evt_8SaYJK8AgbpG6FXpddJgfsVM",
  "object": "event",
  "name": "Interview with customers",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "project": {
    "id": "proj_rNW9MurEP8gJ3S4cY2Lu7JH8",
    "object": "project",
    "name": "Project name",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "app_url": "/projects/proj_rNW9MurEP8gJ3S4cY2Lu7JH8"
  },
  "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
}

Delete a event

Delete a study. You only need to supply the unique event identifier.

Parameters

None

Returns

Returns an object with a deleted parameter on success. If the event id does not exist, this call returns an error.

DELETE /v1/events/:id

$ curl 'https://api.consentkit.com/v1/events/evt_8SaYJK8AgbpG6FXpddJgfsVM' \
    -X DELETE \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "id": "evt_8SaYJK8AgbpG6FXpddJgfsVM",
  "object": "event",
  "deleted": true
}

Participants

Participant objects represent the participants that are within your organisation.

The participant object

Attributes

id
string
Unique identifier for the object
object
string
Name of the object type. This will be "participant"
first_name
string
The first name of the participant.
email
string
The email of the participant.
created_at
timestamp
When the object was created
updated_at
timestamp
When the object was last updated
anonymous_id
string
The id of the participant that is unique to that participant for the event. Can be used instead of PII as a human friendly identifier
app_url
string
The URL for the participant within the Consent Kit App
event
object
The event that the participant is taking part in.

Response

{
  "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
  "object": "participant",
  "first_name": "Alice",
  "email": "test@example.com",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "anonymous_id": "P1",
  "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
  "event": {
    "id": "evt_id",
    "object": "event",
    "name": "Interview with customers",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
  }
}

Create a participant

Creates a participant.

Parameters

name
required
The participants full name.
email
required
The participants email address. Used to send the consent remotely and for communications.
event_id
required
The unique identifier for the event that the participant is participating in.

Returns

Returns the participant object if the create succeeded. Returns an error if create parameters are invalid

POST /v1/participants

$ curl 'https://api.consentkit.com/v1/participants' \
    -X POST \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN' \
    -H "Content-Type: application/json" \
    -d '{
    "name": "Alice Apple",
    "email": "test@example.com",
    "event_id": "evt_8SaYJK8AgbpG6FXpddJgfsVM",
    }'

Response

{
  "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
  "object": "participant",
  "first_name": "Alice",
  "email": "test@example.com",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "anonymous_id": "P1",
  "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
  "event": {
    "id": "evt_id",
    "object": "event",
    "name": "Interview with customers",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
  }
}

List all participants

Returns a list of all your organisations participants. Sorted by creation date.

Parameters

limit
optional
A limit on the number of objects returned, the default is 20
page
optional
Combined with a limit or the default to be able to paginate through all the objects, the default is 1

Returns

A list object with a data property that contains an array of up to limit participants, using the page as a starting point. Each entry in the array is a separate participant object. If no more participant are available, the resulting array will be empty.

This request should never return an error.

GET /v1/participants

$ curl 'https://api.consentkit.com/v1/participants' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "object": "list",
  "count": 99,
  "data": [
    {
      "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
      "object": "participant",
      "first_name": "Alice",
      "email": "test@example.com",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "anonymous_id": "P1",
      "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
      "event": {
        "id": "evt_id",
        "object": "event",
        "name": "Interview with customers",
        "created_at": "2021-02-16T10:29:30+00:00",
        "updated_at": "2021-02-16T10:29:30+00:00",
        "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
      }
    },
    {...},
    {...}
  ]
}

Retrieve a participant

Retrieves the details for a participant. You only need to supply the unique participant identifier.

Parameters

None

Returns

Returns a participant object if a valid identifier was provided.

GET /v1/participants/:id

$ curl 'https://api.consentkit.com/v1/participants/par_TBuhrZgWc41kUa3gL6zxhJUq' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
  "object": "participant",
  "first_name": "Alice",
  "email": "test@example.com",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "anonymous_id": "P1",
  "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
  "event": {
    "id": "evt_id",
    "object": "event",
    "name": "Interview with customers",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
  }
}

Consents

Consent objects represent the consents that are within your organisation.

Attributes

id
string
Unique identifier for the object
object
string
Name of the object type. This will be "consent"
created_at
timestamp
When the object was created
updated_at
timestamp
When the object was last updated
consented_at
timestamp
When the consent was given or refused
status
string
If the consent was given. One of agreed or refused
permissions
array
A list of strings which are the permissions that the participant has given
participant
object
The participant the consent is attached to

Response

{
  "id": "con_LZp1rZc9mGBirpdTosvbvuo3",
  "object": "consent",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "consented_at": "2021-02-16T10:29:30+00:00",
  "status": "agreed",
  "permissions": ["I agree ...", "..."],
  "participant": {
    "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
    "object": "participant",
    "first_name": "Alice",
    "email": "test@example.com",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "anonymous_id": "P1",
    "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
    "event": {
      "id": "evt_id",
      "object": "event",
      "name": "Interview with customers",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
    }
  }
}

Returns a list of all your organisations consents. Sorted by creation date.

Parameters

limit
optional
A limit on the number of objects returned, the default is 20
page
optional
Combined with a limit or the default to be able to paginate through all the objects, the default is 1
status
optional
Filter the consents by the status. One of agreed or refused

Returns

A list object with a data property that contains an array of up to limit consents, using the page as a starting point. Each entry in the array is a separate consent object. If no more consent are available, the resulting array will be empty.

This request should never return an error.

GET /v1/consents

$ curl 'https://api.consentkit.com/v1/consents' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "object": "list",
  "count": 99,
  "data": [
    {
      "id": "con_LZp1rZc9mGBirpdTosvbvuo3",
      "object": "consent",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "consented_at": "2021-02-16T10:29:30+00:00",
      "status": "agreed",
      "permissions": ["I agree ...", "..."],
      "participant": {
        "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
        "object": "participant",
        "first_name": "Alice",
        "email": "test@example.com",
        "created_at": "2021-02-16T10:29:30+00:00",
        "updated_at": "2021-02-16T10:29:30+00:00",
        "anonymous_id": "P1",
        "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
        "event": {
          "id": "evt_id",
          "object": "event",
          "name": "Interview with customers",
          "created_at": "2021-02-16T10:29:30+00:00",
          "updated_at": "2021-02-16T10:29:30+00:00",
          "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
        }
      }
    },
    {...},
    {...}
  ]
}

Retrieves the details for a consent. You only need to supply the unique consent identifier.

Parameters

None

Returns

Returns a consent object if a valid identifier was provided.

GET /v1/consents/:id

$ curl 'https://api.consentkit.com/v1/consents/con_LZp1rZc9mGBirpdTosvbvuo3' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "id": "con_LZp1rZc9mGBirpdTosvbvuo3",
  "object": "consent",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "consented_at": "2021-02-16T10:29:30+00:00",
  "status": "agreed",
  "permissions": ["I agree ...", "..."],
  "participant": {
    "id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
    "object": "participant",
    "first_name": "Alice",
    "email": "test@example.com",
    "created_at": "2021-02-16T10:29:30+00:00",
    "updated_at": "2021-02-16T10:29:30+00:00",
    "anonymous_id": "P1",
    "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM/participants/par_TBuhrZgWc41kUa3gL6zxhJUq",
    "event": {
      "id": "evt_id",
      "object": "event",
      "name": "Interview with customers",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "app_url": "/events/evt_8SaYJK8AgbpG6FXpddJgfsVM"
    }
  }
}

Data Links

To associate data with a participant you can create a DataLink

The data-link object

Attributes

id
string
Unique identifier for the object
object
string
Name of the object type. This will be "data_link"
title
string
Name or title of the data
url
string
An accessible url to the data
reminder_on
timestamp
If set, when a reminder to delete the data will be sent
created_at
timestamp
When the object was created
updated_at
timestamp
When the object was last updated
recorded_at
timestamp
When the data was collected or created

Response

{
  "id": "link_58cfjco9KcR3EeNjvjjFnoaE",
  "object": "data_link",
  "title": "Recording 0",
  "url": "https://example.com/2/0",
  "reminder_on": "2021-05-17",
  "created_at": "2021-02-16T10:29:30+00:00",
  "updated_at": "2021-02-16T10:29:30+00:00",
  "recorded_at": "2021-02-16"
}

Create a data link

Creates a data links.

Parameters

url
required
The url where the data is. Should be accessible to people in your organisation
recorded_at
required, date
The date the data was collected or created. This works with ISO 8601 format e.g. YYYY-MM-DD
participant_id
required
The unique identifier for the participant the data is being linked to
title
optional
The title or name of the data being linked

Returns

Returns the data link object if the create succeeded. Returns an error if create parameters are invalid

POST /v1/data-links

$ curl 'https://api.consentkit.com/v1/data-links' \
    -X POST \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN' \
    -H "Content-Type: application/json" \
    -d '{
    "url": "https://example.com/2/0",
    "recorded_at": "2021-04-04",
    "participant_id": "par_TBuhrZgWc41kUa3gL6zxhJUq",
    "title": "Interview with P1"
    }'

Response

{
  "object": "list",
  "count": 99,
  "data": [
    {
      "id": "link_58cfjco9KcR3EeNjvjjFnoaE",
      "object": "data_link",
      "title": "Recording 0",
      "url": "https://example.com/2/0",
      "reminder_on": "2021-05-17",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "recorded_at": "2021-02-16"
    },
    {...},
    {...}
  ]
}

List all data links

Returns a list of all your organisations data links. Sorted by creation date.

Parameters

limit
optional
A limit on the number of objects returned, the default is 20
page
optional
Combined with a limit or the default to be able to paginate through all the objects, the default is 1

Returns

A list object with a data property that contains an array of up to limit data links, using the page as a starting point. Each entry in the array is a separate data link object. If no more data link are available, the resulting array will be empty.

This request should never return an error.

GET /v1/data-links

$ curl 'https://api.consentkit.com/v1/data-links' \
    -X GET \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "object": "list",
  "count": 99,
  "data": [
    {
      "id": "link_58cfjco9KcR3EeNjvjjFnoaE",
      "object": "data_link",
      "title": "Recording 0",
      "url": "https://example.com/2/0",
      "reminder_on": "2021-05-17",
      "created_at": "2021-02-16T10:29:30+00:00",
      "updated_at": "2021-02-16T10:29:30+00:00",
      "recorded_at": "2021-02-16"
    },
    {...},
    {...}
  ]
}

Delete a data-link

This deletes or unlinks data from a participant

Parameters

None

Returns

Returns an object with a deleted parameter on success. If the data link id does not exist, this call returns an error.

DELETE /v1/data-links/:id

$ curl 'https://api.consentkit.com/v1/data-links/link_58cfjco9KcR3EeNjvjjFnoaE' \
    -X DELETE \
    -H "Accept: application/json" \
    -H 'Authorization: Bearer TOKEN'

Response

{
  "id": "link_58cfjco9KcR3EeNjvjjFnoaE",
  "object": "data_link",
  "deleted": true
}

Consent Kit API

Consent Kit API

API Reference

Authentication

Oauth2 tokens

Responses

Common errors

400

401

404

Projects

The project object

Attributes

id

object

created_at

updated_at

app_url

List all projects

Parameters

limit

page

Returns

Retrieve a project

Parameters

Returns

Studies

The event object

Attributes

id

object

created_at

updated_at

app_url

project

Create a study

Parameters

project_id

name

Returns

List all events

Parameters

limit

page

Returns

Retrieve a event

Parameters

Returns

Delete a event

Parameters

Returns

Participants

The participant object

Attributes

id

object

first_name

email

created_at

updated_at

anonymous_id

app_url

event

Create a participant

Parameters

name

email

event_id

Returns

List all participants

Parameters

limit

page

Returns

Retrieve a participant

Parameters

Returns

Consents

The consent object

Attributes