ConsentGrid API Reference

ConsentGrid uses predictable REST APIs for all resource-related operations and several RPC-style APIs for more specialized tasks. These APIs use standard HTTP verbs and return standard HTTP response codes. All APIs use encrypted communication (HTTPS) with the clients.

Accounts

ConsentGrid™ organizes all data and configuration under accounts. When you log in to the ConsentGrid™ UI or invoke an API, you choose an account to work with. ConsentGrid™ will modify or return data from the chosen account. When you create an object such as a consent form, or a data subject in an account, that object is accessible only when you're working in that account.

Account access is controlled by administrators. When you create an account, you become the administrator for it. An account administrator can add other users to the account, and manage their access rights within the account.

An account can be a test account or a live account. A test account has usage and storage limits. It is intended for development, test or evaluation work only.

ConsentGrid™ APIs requires API authentication using API keys. However, there are APIs that accept cookie-based client authentication so you can use these APIs without revealing the API keys. These APIs use a unique path segment in the URLS. Because of this, every account has a distinct path segment.

Configure your accounts...

Authentication

ConsentGrid works with two types of users:

User
A user is associated to an individual or an organization that can log in to the administrative UI. A user can obtain an access token that has a limited life span to invoke ConsentGrid™ APIs.
API User
An API user represents a client application that can call ConsentGrid™ APIs only. An API user cannot log in to the administrative interface. The access keys for API accounts do not expire, and they must be kept a secret. If you think an access key is compromised, you can delete it and create a new key using the administration interface.

The access keys and tokens can be used in several ways:

Using HTTP basic authentication:
Authorization: Basic base64("apikey":token)
User name: the string apikey, without the quotes
Password: The api token
Bearer token:
Authorization: Bearer token
Some ConsentGrid™ APIs can be used from web applications (such as the Submit Consent Form API). Do not include access keys to invoke such APIs, refer to the specific documentation to see how these APIs are used.
Data subject sessions and cookie authentication

You can use some ConsentGrid™ APIs using cookie authentication. Use this feature, you can create Javascript applications that run on the client browser without backend involvement. You have to create a data subject session to use this feature from your back-end using the API key. This will return a token which you can use on the browser without exposing your API key. The token is specific to a data subject, and will expire after a certain time of inactivity. You can also use this token to obtain a cookie from ConsentGrid™.

Call create data subject session API to obtain a token, and optionally a cookie for your front-end to call some of the ConsentGrid™ APIs directly without authentication. See Session Cookies section for more information.

JSON data

ConsentGrid™ uses standard JSON documents. For date, date-time, and time fields, it recognizes the RFC3339 standard formats:

{
  "dateTime": "2006-01-02T15:04:05Z07:00",
  "date": "2006-01-02",
  "time": "15:04:05Z07:00"
  }

Some ConsentGrid™ APIs accept JSON documents in HTTP GET requests using the following convention:

  • Use dot-notation to address fields:
    address.state=CA&address.country=US
    {
      "address": {
         "state": "CA",
         "country": "US"
      }   
    }
  • Use repeting fields to represent arrays:
    item.id=1&item.id=2&item.id=3
    {
       "item": {
         "id": ["1", "2", "3"]
       }
    }

Depending on the use, ConsentGrid™ will use the JSON schema associated with the call to infer the actual types of values.

Bulk APIs

ConsentGrid uses concatenated or newline-delimited JSON streams.

{"id": "abc",...}{"id": "6526",...}{"id": "efa52",...}...
{"id": "abc",...}
{"id": "6526",...}
{"id": "efa52",...}
 ...

Calling APIs

Most of the ConsentGrid™ APIs are defined using the OpenAPI (Swagger) specification here. You can generate a client library to call ConsentGrid™ APIs for your backend language using this specification.

You can use tools like curl or Postman to call ConsentGrid™ APIs. Once you obtain an access key, use the API documents to find out the syntax required by the APIs.

Errors

ConsentGrid uses the following standard HTTP status codes.

200 OK
Operation completed successfully. The response body contains an entity describing the result of the operation.
204 No Content
Operation completed successfully. There is no response body.
400 Bad Request
Malformed request, or unacceptable input value. Depending on the location of the error, the body may contain a JSON document describing the exact error.
401 Unauthorized
Required access key or domain information is missing.
403 Forbidden
The access key used in the call does not have sufficient privileges.
404 Not Found
The resource needed to complete the operation was not found. The body may contain a JSON document describing the exact error.
413 Payload too large
The request is too large for processing.
415 Unsupported media type
The request body contains content that is not recognized by the API.
500 Internal server error
A generic error message not described by any of the above. Depending on the error, the body may contain a JSON document describing the exact error.

Diagnostics

When possible, ConsentGrid APIs will return error diagnostic information in the following format:

{
  "operation": "checkConsent",
  "success": false,    
  "statusCode": 404,
  "type": "notfound",
  "severity": "fatal",
  "message":  "Subject not found"
}

Versioning

Data subjects and consent records are versioned objects. The first time a versioned object is created it is assigned version number 1. Subsequent modifications to a versioned object are written with increasing version numbers. For example, when a data subject is first created, it becomes v1 of that subject. If later the data subject is modified, the new version becomes v2, and the older v1 version is still kept. The v1 version can be accessed by the additional query parameter version=1 to the get subject API.