Assurance API endpoint setup guide

Refer to accompanying guide here. 

For more technical information, access article here.

For access to the swagger please contact the service desk. 

Part 1 - initial request to get an access token:

Enter API key in the white text box and replace "your tenant name" in the black box with your unique tenant ID:

Tenant name is the Assurance unique identifier, which is also a tenant subdomain. Your tenant name is in your URL, for example:

yourcompany.csassurance.com, tenant name = yourcompany

This will lead to a return of a large amount of JSON containing a value for token:

Copy the response body, which is in the black box to the right of 'Code 200'. 

Open the endpoint for form creation (contracts) (see green highlighted section in the below screenshot):

Enter the API key again in the API key section (highlighted in blue).
Paste the token you copied into the authentication field (highlighted in red) and prefix with the term 'Bearer'. It should look something like this:

Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InVfS3FXenpubDcxTHk0UkhCUkl0RyJ9.eyJpc3MiOiJodHRwczovL2NvbXBsaXNwYWNlLWF1dG9tYXRpb24uYXUuYXV0aDAuY29tLyIsInN1YiI6ImEwZFRVMWJFY0JVTnJBRUJpbUJXc01YRm9UUk1rQ0loQGNsaWVudHMiLCJhdWQiOiJodHRwczovL2FwaS5jc2Fzc3VyYW5jZS5jb20iLCJpYXQiOjE2NjI5NDY2MzcsImV4cCI6MTY2MzAzMzAzNywiYXpwIjoiYTBkVFUxYkVjQlVOckFFQmltQldzTVhGb1RSTWtDSWgiLCJzY29wZSI6ImNyZWF0ZTpjb250cmFjdHMiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.ofrusruGFaygRCqO6FDAIcxnvjXdik6rGaxgFkGSbAjp_OB5Ec63W5QiXv1tWnipnpc8b4c4vs6Zyj_HY7JWokZPCzj5LOULKTCcge3coOajhCK3y-9NzR78DBLspvtSr7-CdLnYk7iYSgYFY3vn90PQ_H0j_vyQ5FsDqlffphj0buNDTXF1kV2Up2smdzAX3MyQDoCgWhwD7LYDal9x2osClxSBsBAxiILhcBnCn8qugR0vRiYmXYxsUEYTohTAo2W8DwG7HwG6dPRxE4Qm18UeUh2ueAr81mvmgRX5Io-TyT7aVrEU-jYkwwl58OqX2HZ9S4oGWqvNN6CyMlWO2A

You should now be authenticated to send Forms via the API. 

Part 2 - Composing the body of your request

Thebody field (highlighted in green) should contain a JSON object referencing:

• The ID of the template you want to use
• The name of your Assurance tenant
• The name of the register
• (optional) the email address of the form owner
• The field answers

Select the blue execute button when you have completed this information in the body. 

What is the 'template_id' 

Each Register template on your Assurance site has a template_id. To find out your template_id simply:

• Navigate to administration (cog wheel)
• Click on Registers templates
• Click on the template you want to use
• in the url address the number at the end is your template_id

What is the Assurance tenant name?

Tenant name is the Assurance unique identifier, which is also a tenant subdomain. Your tenant name is in your URL, for example:

yourcompany.csassurance.com, tenant name = yourcompany

What is the 'Name' of the register?

‘Name’ field is form/register name. The field is from the details section on your register template. Here it is Contracts Register

Who is the ‘owner’?

The owner is the person responsible, the person who should receive the notifications that a form has entered into the system. We suggest to always pass CompliSpace admin: [e-mail] as an owner.

What types of fields are supported by the API endpoint?

Thefields value is itself a JSON object, expressed as:"field_name": "field_value"

Currently available field types via the API:

• short text
• long text
• single-select
• numeric
• date (supports multiple formats e.g. 2022-05-20)
• time
• array of strings (multi-select)
• json object as a field value (single or multi-select with freeform text)

How should I represent selectable (single-select and multi-select) fields in the API?

Depending on how they're set up in the template, these fields can have different representation.

For a single-select field, the data model is simple, and should look something like this:

If there is no preset field response that matches the answer you give in your data, the API will return a validation error.

If the required option is set to be free text in the template, it gets a little more complex, and your JSON data should look more like this:

Note that the value of the field is now represented by a key-value pair (a JSON object) instead of a simple string.

Multi-select fields are similar, but with an additional factor, which is that the values are represented as an array. Your input for such a field should therefore look like this:

Once again, if you submit an answer that is not already defined in the field, you'll get a validation error.

Free text options are handled in a similar fashion as for single-select fields, i.e. as key-value pairs. Your input for such a field should look like this:

Note that the overall value of the field you're setting is now set to an array of whose elements one is also a JSON object.

If you're new to the concept of JSON objects, the standard reference is here: https://www.json.org/json-en.html

Part 3 - Example of an invalid and valid response

The API will validate what you enter, and if you give it a value not compatible with its associated field, it will give you back a descriptive error.

An invalid response has returned here Code 400: Bad Request because I've submitted a numeric value for the field called Key, which is supposed to be a string:

here is a valid request: 

Important Note:

The v1 endpoint for Assurance reports is deprecated as of 1 December 2023. While it will continue to work through the new year, we strongly encourage anyone using the Assurance API reports to adopt the v2 version of the endpoint. (Just substitute 'v2' for 'v1' in the URL - everything else is identical.) The reason for this is that the v1 endpoint can hit certain internal limits when it comes to returning large amounts of data. The v2 version does not have that restriction - although, for really large datasets, we would encourage users to adopt the cache/snapshot strategy detailed in this guide.

You will notice the following changes:

• When using the Swagger-UI frontend, the v1 endpoint is greyed out (although still usable)
• Requests to the v1 version will now return a Deprecated HTTP header in the API response.