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.
The consent object
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
List all consents
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.
Retrieve a consent
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.
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
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
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.
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.