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.

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. Use the login menu "Access Token" option to generate your tokens.
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, or cannot call administrative APIs. 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. Manage your access keys from the "Account Users" option in the login menu.

The access keys and tokens can be used in several ways. Using the X-Consent-Key header:

X-Consent-Key: 376837asb372bace0834e12

Using HTTP basic authentication:

Authorization: Basic base64(key:"")

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.

JSON data

ConsentGrid recognizes the RFC3339 standard for dates:

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

Streaming

ConsentGrid uses concatenated or newline-delimited JSON streams.

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

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.