Skip to main content

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

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.

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.

Events

Event 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.

Create an event

Create an event 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

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.

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.

Delete a event

Delete an event. 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.

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.

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

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.

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.

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

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.

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.

To associate data with a participant you can create a DataLink

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

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

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.

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.