Introduction

  {
    "action": "create|invite|find|withdraw",
    "payload": {"object_with": "instructions"}
  }

  {
    "status": "ok|fail",
    "messages": "If status is fail, then this is the error message",
    "data": [{"object": "..."}]
  }

Welcome to the Konsento API! You can use our API to access and work with consents for your organisation.

We have examples for cURL (Python coming soon). You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

The Konsento API is accessed via HTTPS and is REST:like, all requests need to be a POST and you tell the API what you would like to do by POSTing instructions. All requests should return a HTTP 200 message

The lifecycle of a consent is pretty standard, first you create an agreement for which you seek individuals consent to. Then you collect the consent from the individual and make sure to capture any evidence as proof that the individual did concent. Each agreement can have several options for the individual to consent to, for example Email and SMS marketing. Then one of two things can happen, either the consent expires or the individual withdraws their consent.

There are two great ways for you to use the API, one would be to asynchronuosly send a consent invitation to an individual were Konsento will ask the individual for their consent. The e-mails and consent page will of course contain your logo (if you upload it). This is probably the quickest way to get started.

The other way would be to completely control the consent experience from within your application. Then you will need to store some additional information about your consents. By doing this Konsento will not send out any e-mails to your individuals asking for their consent because You are responsible for that process.

Authentication

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Token super_secret_key"

Konsento uses API keys to allow access to the API. You can generate a Konsento API key at your Konsento User Profile log into Konsento and click on your email address in the top right corner. Then click on the link to generate your private API key.

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

Authorization: Token super_secret_key

You must replace super_secret_key with your personal API key.

Consents

curl https://app.konsento.io/api/consent/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "invite", 
   "payload": 
    {
     "agreement_id": 1, 
     "recipient_primary_email": "test@example.com", 
     "name_of_individual": "Your Invited User", 
     "meta_data": {"custom_field": 222} 
    }
   }'

{ 
 "status":"ok",
 "data":
  {
   "consent_id":9,
   "message":"Invitation sent"
  }
}

You can easily trigger a consent invitation via the API, this is instead of uploading or adding users via our web interface. Konsento will then send out a Consent invitation e-mail and ask the individuals for their consent on your behalf.

You can add your own logo and text to the e-mails and the consent page that the user is asked to navigate to.

HTTP Request

POST https://app.konsento.io/api/consent/

Data Parameters

Parameter	Type	Description
agreement_id	int	The agreement you want a consent for
name_of_individual	str	The name of individual you are inviting
recipient_primary_email	str	The email adress to the individual you are inviting.
recipient_secondary_email	str	optional Another email to send to, for example to a guardian
meta_data	{}	optional A objects containing your own data that we will filter against.

curl https://app.konsento.io/api/consent/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "create", 
   "payload": 
    {
     "agreement_id": 1, 
     "recipient_primary_email": "test@example.com", 
     "name_of_individual": "Your Invited User", 
     "meta_data": {"custom_field": 222},
     "options": {"1": "e-mail","16": "SMS"},
     "evidence": {"collected": "in_app", "when": "at_registration"}
    }
   }'

{ 
 "status":"ok",
 "data":
  {
   "consent_id":9,
   "message": "Created"
  }
}

Do you want to fully control the consent process? Then this endpoint is for you! Create consents and provide the evidence and we will store and manage it for you. No consent invitation will be sent out by Konsento when you create a consent this way.

HTTP Request

POST https://app.konsento.io/api/consent/

Data Parameters

Parameter	Type	Description
agreement_id	int	The agreement you want a consent for
evidence	{}	An objects containing your own consent evidence data.
meta_data	{}	optional A objects containing your own data that you can filter against.
options	{}	optional A objects containing the options in the agreement that the individual has accepted.
name_of_individual	str	optional The name of individual you are inviting
recipient_primary_email	str	optional The email adress to the individual you are inviting.
recipient_secondary_email	str	optional Another email to send to, for example to a guardian

curl https://app.konsento.io/api/consent/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "withdraw", 
   "payload": 
    {
     "consent_id": 1, 
     "evidence": {"collected": "in_app", "when": "at_cancel_account"}
    }
   }'

{ 
 "status":"ok",
 "data":
  {
   "consent_id":1,
   "message": "Withdrawn"
  }
}

You can withdraw a given consent, very useful when you want to control the consent management process in your own application.

HTTP Request

POST https://app.konsento.io/api/consent/

Data Parameters

Parameter	Type	Description
consent_id	int	The consent id
evidence	{}	An objects containing your own consent evidence data.

Find Consents

curl "https://app.konsento.io/api/consent/"
  -H "Authorization: Token super_secret_key"
  -H "Content-Type: application/json" 
  -d '
    {
        "action": "find", 
        "payload": 
            {
                "agreement_id": 1,
                "created": {"gte": 1521525316 }
            }
   }'

{
 "status":"ok",
 "data":
    {"consents":
        [
            {
                "consent_id":8,
                "created":1521472789,
                "updated":1521472789,
                "status":1,
                "process":0,
                "consent_given":null,
                "consent_withdrawn":null,
                "name_of_individual":"Name of Invited User",
                "recipient_email_primary":"test@example.com",
                "recipient_email_secondary":null,
                "meta_data":{"custom_field":222},
        "options": {"1": "e-mail","16": "SMS"},
                "evidence":{},
                "agreement":{
                    "id":1,
                    "name":"Membership agreement",
                    "valid_for_days":730
                },
                "organisation":{
                    "name":"My Organisation",
                    "id":1
                }
            },
        ]
    }   
}

This endpoint retrieves consents baseds on your search query..

HTTP Request

POST https://app.konsento.io/api/consent/

Data Parameters

Parameter	Type	Description
agreement_id	int	If set all consents for specific agreement will be returned
name_of_individual	str	If set we will match the given name.
recipient_email_primary	str	If set we will match the given e-mail address.
status	int	You can filter consents based on their status.
created	{}	A objects containing 'lt', 'lte', 'gt', 'gte' of UNIX timestamps
meta_data	{}	A objects containing your own data that we will filter against.
options	[]	An array of integer, the agreement option keys that the individual has accepted.

curl "https://app.konsento.io/api/consent/"
  -H "Authorization: Token super_secret_key"
  -H "Content-Type: application/json" 
  -d '
    {
        "action": "get", 
        "payload": 
            {
                "consent_id": 10,
            }
   }'

{
 "status":"ok",
 "data":
    {
     "consent_id":10,
     "created":1521554747,
     "updated":1521554747,
     "status":2,
     "process":2,
     "consent_given":null,
     "consent_withdrawn":null,
     "name_of_individual":"No No",
     "recipient_email_primary":"test@example.com",
     "recipient_email_secondary":null,
     "meta_data":{"custom_field":222},
     "log":[
      {
        "id":21,
        "created":"2018-03-20T14:05:47.471732Z",
        "log":
         {
          "text":null,
          "actor":"test@coachhippo.com",
          "action":"consent-created",
          "status":2,
          "evidence":{"initiator":"in_app"},
          "timestamp:":1521554747.459166,
          "consent_given":"",
          "consent_withdrawn":""
         }
        }
       ],
      "agreement":{
    "id":1,
    "name":"Membership agreement",
    "valid_for_days":730
      },
      "organisation":{"name":"test","id":1}
     }
}

This endpoint retrieves a specific Consent.

HTTP Request

POST https://app.konsento.io/api/consent/

URL Parameters

Parameter	Description
consent_id	The ID of the consent to retrieve

curl https://app.konsento.io/api/consent/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "delete", 
   "payload": 
    {
     "consent_id": 1, 
     "evidence": {"collected": "in_app", "when": "at_cancel_account"}
    }
   }'

{ 
 "status":"ok",
 "data":
  {
   "consent_id":1,
  }
}

You can delete consents, what happens is that the consent receives a status of DELETED.

HTTP Request

POST https://app.konsento.io/api/consent/

Data Parameters

Parameter	Type	Description
consent_id	int	The consent
evidence	{}	optional An objects containing your own consent evidence data.

curl https://app.konsento.io/api/consent/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "update", 
   "payload": 
    {
     "consent_id": 10, 
     "meta_data": {"internal_id": 21313233},
     "options": {"1": "e-mail","16": "SMS"},
    }
   }'

{
 "status":"ok",
 "data":
    {
     "consent_id":10,
     "created":1521554747,
     "updated":1521554747,
     "status":2,
     "process":2,
     "consent_given":null,
     "consent_withdrawn":null,
     "name_of_individual":"No No",
     "recipient_email_primary":"test@example.com",
     "recipient_email_secondary":null,
     "meta_data":{"internal_id": 21313233},
     "options": {"1": "e-mail","16": "SMS"},
     "log":[
      {
        "id":21,
        "created":"2018-03-20T14:05:47.471732Z",
        "log":
         {
          "text":null,
          "actor":"test@coachhippo.com",
          "action":"consent-created",
          "status":2,
          "evidence":{"initiator":"in_app"},
          "timestamp:":1521554747.459166,
          "consent_given":"",
          "consent_withdrawn":""
         }
        }
       ],
      "agreement":{
        "id":1,
        "name":"Membership agreement",
        "valid_for_days":730
      },
      "organisation":{"name":"test","id":1}
     }
}

{ 
 "status":"ok",
 "data":
  {
   "consent_id":1,
  }
}

You can delete consents, what happens is that the consent receives a status of DELETED.

HTTP Request

POST https://app.konsento.io/api/consent/

Data Parameters

Parameter	Type	Description
consent_id	int	The consent
meta_data	{}	optional Meta data as a object. We will overwrite the meta_data with this new object!!
options	{}	optional The agreement options that the individual has consented to. We will overwrite the options with this new object!!
status	int	optional You can change the status of a Pending:1, ACCEPTED:2, REJECTED:4, DELETED:8
evidence	{}	optional An objects containing your own consent evidence data.

If changing status you must supply a evidence

Agreements

List all agreements

curl https://app.konsento.io/api/agreement/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "list", 
   "payload": 
    {
     "organisation_id": 1, 
    }
   }'

{  
   "status":"ok",
   "data":{  
      "agreements":[  
         {  
            "agreement_id":5,
            "name":"User Consent Public",
            "valid_for_days":730,
            "created":"2018-03-28T09:03:26.183512+00:00",
            "updated":"2018-03-28T09:03:26.183551+00:00",
            "status":1,
            "context":"Agreement",
            "organisation":{  
               "id":3,
               "name":"Demo Organisation"
            },
            "contact":"do-not-email@konsento.io",
            "details":{  
               "fetch_specific_agreement":"to_view_details"
            },
            "text": "<p>You're someone who cares about our cause! We'd like to contact you in the future with vital appeals, campaigns, information about how you can help and saving lives. Please let us know that you are happy to be contacted in the ways listed below. </p>",
            "options": {"1": "e-mail","16": "SMS"},
            "public":{  
               "enabled":"true",
               "slug":"user-consent-public"
            },
            "meta_data":{}
         }],
   }
}

You can list all your agreements, some information is excluded for brevity sake and if you want to access the full details of an agreement you will need to use the "get agreement" action.

HTTP Request

POST https://app.konsento.io/api/agreement/

Data Parameters

Parameter	Type	Description
organisation_id	int	Your organisations ID to get agreements for

Get agreement details

curl https://app.konsento.io/api/agreement/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "get", 
   "payload": 
    {
     "agreement_id": 5, 
    }
   }'

{  
   "status":"ok",
   "data":{  
      "agreement_id":5,
      "name":"User Consent Public",
      "valid_for_days":730,
      "created":"2018-03-28T09:03:26.183512+00:00",
      "updated":"2018-03-28T09:03:26.183551+00:00",
      "status":1,
      "context":"Agreement",
      "organisation":{  
         "id":3,
         "name":"Demo Organisation"
      },
      "contact":"do-not-email@konsento.io",
      "details":{  
         "created_by":"test@test.com",
         "internal_note":"",
         "document":"<url to document>",
         "logo":"<url to logo>",
         "email_body":"This is the e-mail message sent out if your are using the Konsento process for collecting consents."
      },
      "text": "<p>You're someone who cares about our cause! We'd like to contact you in the future with vital appeals, campaigns, information about how you can help and saving lives. Please let us know that you are happy to be contacted in the ways listed below. </p>",
      "options": {"1": "e-mail","16": "SMS"},
      "public":{  
         "enabled":"true",
         "slug":"user-consent-public"
      },
      "meta_data":{ }
   }
}

You can view an agreements full details, uncluding the agreement text using this enpoint.

HTTP Request

POST https://app.konsento.io/api/agreement/

Data Parameters

Parameter	Type	Description
agreement_id	int	The agreement you want details for

Find Agreement

curl https://app.konsento.io/api/agreement/ 
 -H 'Authorization: Token super_secret_key' 
 -H "Content-Type: application/json" 
 -d '
  {
   "action": "find", 
   "payload": 
    {
     "context": "demo",
     "name": "User" 
    }
   }'

{  
   "status":"ok",
   "data":{  
      "agreements":[  
         {  
            "agreement_id":5,
            "name":"User Consent Public",
            "valid_for_days":730,
            "created":"2018-03-28T09:03:26.183512+00:00",
            "updated":"2018-03-28T10:29:19.100763+00:00",
            "status":1,
            "context":"Agreement,demo",
            "organisation":{  
               "id":3,
               "name":"Demo Organisation"
            },
            "contact":"do-not-email@konsento.io",
            "details":{  
               "fetch_specific_agreement":"to_view_details"
            },
            "text": "<p>You're someone who cares about our cause! We'd like to contact you in the future with vital appeals, campaigns, information about how you can help and saving lives. Please let us know that you are happy to be contacted in the ways listed below. </p>",
            "options": {"1": "e-mail","16": "SMS"},
            "public":{  
               "enabled":"true",
               "slug":"user-consent-public"
            },
            "meta_data":{ }
         },
         {...},  
      ]
   }
}

You are able to search for agreements using parameters, the API will return a list of agreements matching your query.

HTTP Request

POST https://app.konsento.io/api/agreement/

Data Parameters

Parameter	Type	Description
name	str	Name that we will search against, we do a case-insensitive containment test.
context	str, []	Case sensitive search for one (string) or more (array) contexts.
meta_data	{}	A objects containing your own data that we will filter against.

Webhooks

{
 "action":"consent",
 "payload":
  {
    "consent_id":8,
    "timestamp":1521472789,
    "activity":"consent-withdrawn",
    "meta_data":{"custom_field":222},
        "evidence": {"collected": "in_app", "when": "at_registration"}
  }
}

You can receive webhook for consent lifecycle events

Data Parameters

Parameter	Type	Description
consent_id	int	If set all consents for specific agreement will be returned
timestamp	int	UNIX timestamp
meta_data	{}	A objects containing your own data that we will filter against.
activity	str	The action, can be: consent-withdrawn, consent-given, consent-will-expire

Errors

The Konsento API should always return a HTTP 200 and within it display any encountered errors

Error Code	Meaning
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified url could not be found.
429	Too Many Requests -- You're performing too many requests. Slow down.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Introduction

Consent Lifecycle

Consent Experience

Authentication

Consents

Send consent invitation

HTTP Request

Data Parameters

Create Consent

HTTP Request

Data Parameters

Withdraw Consent

HTTP Request

Data Parameters

Find Consents

HTTP Request

Data Parameters

Get a Specific Consent

HTTP Request

URL Parameters

Delete Consent

HTTP Request

Data Parameters

Update Consent

HTTP Request

Data Parameters

Agreements

List all agreements

HTTP Request

Data Parameters

Get agreement details

HTTP Request

Data Parameters

Find Agreement

HTTP Request

Data Parameters

Webhooks

Data Parameters

Errors