Articles in this section

Using the API

Avatar
Support
  • Updated
Follow

On this page

Introduction

This API is intended for integration purposes to facilitate automated workflows between the system and other applications.  

Security

To enable your applications to communicate with the API you will need to acquire an API key. Please use the Admin portal Settings screen to achieve this.

System Documentation

The detail below is also available via https://api.brilliantassessments.com/help. Swagger is also available there to test the APIs. 

Restrictions

Throttling limits the maximum number of requests that will be processed from one IP address in any period to minimize the effect of hacking attempts, and to encourage efficient code from users accessing the API

Those maximums are:

  • per Second: 1,
  • per Minute: 10,
  • per Hour: 200,
  • per Day: 1500,
  • per Week: 3000

If you have any concerns with those maximums, please contact support@brilliantassessments.com.

Access to the API is only available for paid subscriptions (i.e. it is not available during the free trial).

Assessment Response

Provides endpoints for assessment response

API Description
Get Test An endpoint to test connectivity to API
GET Assessment Response Gets a single assessment response for given assessment response ID
Get Changes Performs a search for ANY assessment responses that have been completed after a given date. If no date is supplied, all completed assessments are returned

Get Changes for an Assessment

 

 Performs a search for assessment responses that have been completed for a given assessment after a given date. If no date is supplied, all completed assessments are returned, but we strongly recommend specifying a recent date to keep within transaction throttling limits. 
Get all responses for an Assessment Performs a search for assessment responses regardless of status (i.e. whether or not they have been completed) for a given assessment. This is only suitable for small datasets.
Post Create Response Assessment Response against a known assessment/survey. The contact details can either be set by specifying a ContactId or if unknown, the contact details.

URL: https://api.brilliantassessments.com

e.g. https://api.brilliantassessments.com/api/assessmentresponse/test

The API uses your APIKey to determine your tenancy. 

GET api/assessmentresponse/test

End point to test connectivity to API

Request Information

URL Parameters

None.

Body Parameters

None.

Response Information

Resource Description

'Test succeeded' string

string

Response Formats

application/json, text/json

Sample:

"sample string 1"

application/xml, text/xml

Sample:

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">sample string 1</string>

 

GET api/assessmentresponse/getassessmentresponse/{assessmentResponseId}

Gets a single assessment response for given assessment response ID

Request Information

URI Parameters

Name Description Type Additional information
assessmentResponseId   integer Required

Body Parameters

None.

Response Information

Resource Description

GetAssessmentResponseResult

Name Description Type Additional information
ResponseId   integer None.
BusinessName   string None.
Email   string None.
FirstName   string None.
LastName   string None.
CompletionDate   date None.
Address1   string None.
Address2   string None.
City   string None.
Postcode   string None.
Country   string None.
Longitude   decimal number None.
Latitude   decimal number None.
HasImage   boolean None.
AdvisorName   string None.
OrganisationLevel1   string None.
OrganisationLevel2   string None.
OrganisationLevel3   string None.
OrganisationLevel4   string None.
OrganisationLevel5   string None.
ReportIdentifier   string None.
GroupName   string None.
CustomerType   string None.
StatusId   integer None.
Status   string None.
Rating (Collection)      
  RatingId   integer None.
  Rating   string None.
  Score   integer None.
  RatingText   string None.
  RatingColour   string None.
  SegmentationId   integer None.
  SegmentationName   string None.
  HasImage   true/false None.
SementationRatings (collection)      
  RatingId   integer None.
  Rating   string None.
  Score   integer None.
  RatingText   string None.
  RatingColour   string None.
  SegmentationId   integer None.
  SegmentationName   string None.
  HasImage   true/false None.
SectionRatings (Collection)      
  SectionId   integer None.
  SectionName   string None.
  SectionNo   integer None.
  RatingId   integer None.
  Rating   string None.
  Score   integer None.
  RatingText   string None.
  RatingColour   string None.
  SegmentationId   integer None.
  SegmentationName   string None.
  HasImage   true/false None.
SectionId   integer None.
  SectionName   string None.
  SectionNo   integer None.
  RatingId   integer None.
  Rating   string None.
  Score   integer None.
  RatingText   string None.
  RatingColour   string None.
  SegmentationId   integer None.
  SegmentationName   string None.
  HasImage   true/false None.
SubSectionRatings (collection)      
  SubSectionId   integer None.
  SubSectionNo   integer None.
  SubSectionName   string None.
  RatingId   integer None.
  Rating   string None.
  Score   integer None.
  RatingText   string None.
  RatingColour   string None.
  SegmentationId   integer None.
  SegmentationName   string None.
  HasImage   true/false None.
Answers (Collection)      
  AvailibleAnswerId   integer None.
  AssessmentAnswerId   integer None.
  AnswerType   string None.
  QuestionId   integer None.
  QuestionPath   string None.
  QuestionText   string None.
  QuestionShortName   string None.
  QuestionPotentialPoints   integer None.
  AnswerText   string None.
  AnswerShortName   string None.
  AnswerScore   integer None.
  SegmentationId   integer None.
  SegmentationName   string None.
  FeatureName   string None.
  ReportText   string None.
  ReportText2   string None.
  ReportText3   string None.
Classifiers (Collection)      
  Key   string None.
  Value   string None.
ReportDetails((Collection)      
  Text   string None.
  Name   string None.
  ID   string None
  ReportURL   string Nine.

Response Formats

application/json, text/json

Sample:

{
  "ResponseId": 1,
  "BusinessName": "sample string 2",
  "Email": "sample string 3",
  "FirstName": "sample string 4",
  "LastName": "sample string 5",
  "CompletionDate": "2019-06-12T09:44:33.2001416+12:00",
  "Address1": "sample string 6",
  "Address2": "sample string 7",
  "City": "sample string 8",
  "Postcode": "sample string 9",
  "Country": "sample string 10",
  "Longitude": 11.1,
  "Latitude": 12.1,
  "HasImage": true,
  "AdvisorName": "sample string 14",
  "OrganisationLevel1": "sample string 15",
  "OrganisationLevel2": "sample string 16",
  "OrganisationLevel3": "sample string 17",
  "OrganisationLevel4": "sample string 18",
  "OrganisationLevel5": "sample string 19",
  "ReportIdentifier": "sample string 20",
  "GroupName": "sample string 21",
  "CustomerType": "sample string 22",
  "StatusId": 23,
  "Status": "sample string 24",
"Rating": {
    "RatingId": 1,
    "Rating": "sample string 1",
    "Score": 1.1,
    "RatingText": "sample string 2",
    "RatingColour": "sample string 3",
    "SegmentationId": 4,
    "SegmentationName": "sample string 5",
    "HasImage": true
  },
  "SementationRatings": [
    {
      "RatingId": 1,
      "Rating": "sample string 1",
      "Score": 1.1,
      "RatingText": "sample string 2",
      "RatingColour": "sample string 3",
      "SegmentationId": 4,
      "SegmentationName": "sample string 5",
      "HasImage": true
    },
    {
      "RatingId": 1,
      "Rating": "sample string 1",
      "Score": 1.1,
      "RatingText": "sample string 2",
      "RatingColour": "sample string 3",
      "SegmentationId": 4,
      "SegmentationName": "sample string 5",
      "HasImage": true
    }
  ],
  "SectionRatings": [
    {
      "SectionId": 1,
      "SectionName": "sample string 2",
      "SectionNo": 1,
      "RatingId": 1,
      "Rating": "sample string 3",
      "Score": 1.1,
      "RatingText": "sample string 4",
      "RatingColour": "sample string 5",
      "SegmentationId": 6,
      "SegmentationName": "sample string 7",
      "HasImage": true
    },
    {
      "SectionId": 1,
      "SectionName": "sample string 2",
      "SectionNo": 1,
      "RatingId": 1,
      "Rating": "sample string 3",
      "Score": 1.1,
      "RatingText": "sample string 4",
      "RatingColour": "sample string 5",
      "SegmentationId": 6,
      "SegmentationName": "sample string 7",
      "HasImage": true
    }
  ],
  "SubSectionRatings": [
    {
      "SubSectionId": 1,
      "SubSectionNo": 1,
      "SubSectionName": "sample string 2",
      "RatingId": 1,
      "Rating": "sample string 3",
      "Score": 1.1,
      "RatingText": "sample string 4",
      "RatingColour": "sample string 5",
      "SegmentationId": 6,
      "SegmentationName": "sample string 7",
      "HasImage": true
    },
    {
      "SubSectionId": 1,
      "SubSectionNo": 1,
      "SubSectionName": "sample string 2",
      "RatingId": 1,
      "Rating": "sample string 3",
      "Score": 1.1,
      "RatingText": "sample string 4",
      "RatingColour": "sample string 5",
      "SegmentationId": 6,
      "SegmentationName": "sample string 7",
      "HasImage": true
    }
  ],
  "Answers": [
    {
      "AvailibleAnswerId": 1,
      "AssessmentAnswerId": 2,
      "AnswerType": "sample string 3",
      "QuestionId": 4,
      "QuestionPath": "sample string 5",
      "QuestionText": "sample string 6",
      "QuestionShortName": "sample string 7",
      "QuestionPotentialPoints": 1.0,
      "AnswerText": "sample string 8",
      "AnswerShortName": "sample string 9",
      "AnswerScore": 1.0,
      "SegmentationId": 1,
      "SegmentationName": "sample string 10",
      "FeatureName": "sample string 11",
      "ReportText": "sample string 12",
      "ReportText2": "sample string 13",
      "ReportText3": "sample string 14"
    },
    {
      "AvailibleAnswerId": 1,
      "AssessmentAnswerId": 2,
      "AnswerType": "sample string 3",
      "QuestionId": 4,
      "QuestionPath": "sample string 5",
      "QuestionText": "sample string 6",
      "QuestionShortName": "sample string 7",
      "QuestionPotentialPoints": 1.0,
      "AnswerText": "sample string 8",
      "AnswerShortName": "sample string 9",
      "AnswerScore": 1.0,
      "SegmentationId": 1,
      "SegmentationName": "sample string 10",
      "FeatureName": "sample string 11",
      "ReportText": "sample string 12",
      "ReportText2": "sample string 13",
      "ReportText3": "sample string 14"
    }
  ],
"Classifiers": [
   {
      "Key": "sample string 1",
      "Value": "sample string 2", 
    }
 ],
 "ReportDetails": [
    {
      "Text": "string",
      "Name": "string",
      "Id": "string",
      "ReportUrl": "string"
    }
  ]

}

application/xml, text/xml

Sample:

<GetAssessmentResponseResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/BrilliantAssessments.Services.AssessmentIntegration.Models">
  <Address1>sample string 6</Address1>
  <Address2>sample string 7</Address2>
  <AdvisorName>sample string 14</AdvisorName>
  <Answers>
    <AssessmentAnswerModel>
      <AnswerScore>1</AnswerScore>
      <AnswerShortName>sample string 9</AnswerShortName>
      <AnswerText>sample string 8</AnswerText>
      <AnswerType>sample string 3</AnswerType>
      <AssessmentAnswerId>2</AssessmentAnswerId>
      <AvailibleAnswerId>1</AvailibleAnswerId>
      <FeatureName>sample string 11</FeatureName>
      <QuestionId>4</QuestionId>
      <QuestionPath>sample string 5</QuestionPath>
      <QuestionPotentialPoints>1</QuestionPotentialPoints>
      <QuestionShortName>sample string 7</QuestionShortName>
      <QuestionText>sample string 6</QuestionText>
      <ReportText>sample string 12</ReportText>
      <ReportText2>sample string 13</ReportText2>
      <ReportText3>sample string 14</ReportText3>
      <SegmentationId>1</SegmentationId>
      <SegmentationName>sample string 10</SegmentationName>
    </AssessmentAnswerModel>
    <AssessmentAnswerModel>
      <AnswerScore>1</AnswerScore>
      <AnswerShortName>sample string 9</AnswerShortName>
      <AnswerText>sample string 8</AnswerText>
      <AnswerType>sample string 3</AnswerType>
      <AssessmentAnswerId>2</AssessmentAnswerId>
      <AvailibleAnswerId>1</AvailibleAnswerId>
      <FeatureName>sample string 11</FeatureName>
      <QuestionId>4</QuestionId>
      <QuestionPath>sample string 5</QuestionPath>
      <QuestionPotentialPoints>1</QuestionPotentialPoints>
      <QuestionShortName>sample string 7</QuestionShortName>
      <QuestionText>sample string 6</QuestionText>
      <ReportText>sample string 12</ReportText>
      <ReportText2>sample string 13</ReportText2>
      <ReportText3>sample string 14</ReportText3>
      <SegmentationId>1</SegmentationId>
      <SegmentationName>sample string 10</SegmentationName>
    </AssessmentAnswerModel>
  </Answers>
  <BusinessName>sample string 2</BusinessName>
  <City>sample string 8</City>
  <CompletionDate>2019-06-12T09:44:33.2001416+12:00</CompletionDate>
  <Country>sample string 10</Country>
  <CustomerType>sample string 22</CustomerType>
  <Email>sample string 3</Email>
  <FirstName>sample string 4</FirstName>
  <GroupName>sample string 21</GroupName>
  <HasImage>true</HasImage>
  <LastName>sample string 5</LastName>
  <Latitude>12.1</Latitude>
  <Longitude>11.1</Longitude>
  <OrganisationLevel1>sample string 15</OrganisationLevel1>
  <OrganisationLevel2>sample string 16</OrganisationLevel2>
  <OrganisationLevel3>sample string 17</OrganisationLevel3>
  <OrganisationLevel4>sample string 18</OrganisationLevel4>
  <OrganisationLevel5>sample string 19</OrganisationLevel5>
  <Postcode>sample string 9</Postcode>
  <Rating>
    <HasImage>true</HasImage>
    <Rating>sample string 1</Rating>
    <RatingColour>sample string 3</RatingColour>
    <RatingId>1</RatingId>
    <RatingText>sample string 2</RatingText>
    <Score>1.1</Score>
    <SegmentationId>4</SegmentationId>
    <SegmentationName>sample string 5</SegmentationName>
  </Rating>
  <ReportIdentifier>sample string 20</ReportIdentifier>
  <ResponseId>1</ResponseId>
  <SectionRatings>
    <AssessmentSectionRatingScoreModel>
      <HasImage>true</HasImage>
      <Rating>sample string 3</Rating>
      <RatingColour>sample string 5</RatingColour>
      <RatingId>1</RatingId>
      <RatingText>sample string 4</RatingText>
      <Score>1.1</Score>
      <SegmentationId>6</SegmentationId>
      <SegmentationName>sample string 7</SegmentationName>
      <SectionId>1</SectionId>
      <SectionName>sample string 2</SectionName>
      <SectionNo>1</SectionNo>
    </AssessmentSectionRatingScoreModel>
    <AssessmentSectionRatingScoreModel>
      <HasImage>true</HasImage>
      <Rating>sample string 3</Rating>
      <RatingColour>sample string 5</RatingColour>
      <RatingId>1</RatingId>
      <RatingText>sample string 4</RatingText>
      <Score>1.1</Score>
      <SegmentationId>6</SegmentationId>
      <SegmentationName>sample string 7</SegmentationName>
      <SectionId>1</SectionId>
      <SectionName>sample string 2</SectionName>
      <SectionNo>1</SectionNo>
    </AssessmentSectionRatingScoreModel>
  </SectionRatings>
  <SementationRatings>
    <AssessmentRatingScoreModel>
      <HasImage>true</HasImage>
      <Rating>sample string 1</Rating>
      <RatingColour>sample string 3</RatingColour>
      <RatingId>1</RatingId>
      <RatingText>sample string 2</RatingText>
      <Score>1.1</Score>
      <SegmentationId>4</SegmentationId>
      <SegmentationName>sample string 5</SegmentationName>
    </AssessmentRatingScoreModel>
    <AssessmentRatingScoreModel>
      <HasImage>true</HasImage>
      <Rating>sample string 1</Rating>
      <RatingColour>sample string 3</RatingColour>
      <RatingId>1</RatingId>
      <RatingText>sample string 2</RatingText>
      <Score>1.1</Score>
      <SegmentationId>4</SegmentationId>
      <SegmentationName>sample string 5</SegmentationName>
    </AssessmentRatingScoreModel>
  </SementationRatings>
  <StatusId>23</StatusId>
  <SubSectionRatings>
    <AssessmentSubSectionRatingScoreModel>
      <HasImage>true</HasImage>
      <Rating>sample string 3</Rating>
      <RatingColour>sample string 5</RatingColour>
      <RatingId>1</RatingId>
      <RatingText>sample string 4</RatingText>
      <Score>1.1</Score>
      <SegmentationId>6</SegmentationId>
      <SegmentationName>sample string 7</SegmentationName>
      <SubSectionId>1</SubSectionId>
      <SubSectionName>sample string 2</SubSectionName>
      <SubSectionNo>1</SubSectionNo>
    </AssessmentSubSectionRatingScoreModel>
    <AssessmentSubSectionRatingScoreModel>
      <HasImage>true</HasImage>
      <Rating>sample string 3</Rating>
      <RatingColour>sample string 5</RatingColour>
      <RatingId>1</RatingId>
      <RatingText>sample string 4</RatingText>
      <Score>1.1</Score>
      <SegmentationId>6</SegmentationId>
      <SegmentationName>sample string 7</SegmentationName>
      <SubSectionId>1</SubSectionId>
      <SubSectionName>sample string 2</SubSectionName>
      <SubSectionNo>1</SubSectionNo>
    </AssessmentSubSectionRatingScoreModel>
  </SubSectionRatings>
</GetAssessmentResponseResult>
 

GET api/assessmentresponse/getchanges/{requestDate}

Performs a search for ANY assessment responses that have been completed after a given date. If no date is supplied, all completed assessments are returned

Request Information

URI Parameters

Name Description Type Additional information
requestDate Optional change date search start. Accepts date in MM-DD-YYYY and YYYY-MM-DD formats date None.

Body Parameters

None.

Response Information

Resource Description

List of assessment IDs

ChangesResponse

Name Description Type Additional information
ResponseIds   Collection of integer None.

Response Formats

application/json, text/json

Sample:

{
  "ResponseIds": [
    1,
    2
  ]
}

application/xml, text/xml

Sample:

<ChangesResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/BrilliantAssessments.Services.AssessmentIntegration.Models">
  <ResponseIds xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:int>1</d2p1:int>
    <d2p1:int>2</d2p1:int>
  </ResponseIds>
</ChangesResponse>
 

GET api/assessmentresponse/getassessmentresponsechanges/{assessmentId}/{requestDate}

Performs search for assessment responses that have been completed for a given assessment after given date. If no date is supplied, all completed assessments are returned

Request Information

URI Parameters

Name Description Type Additional information
assessmentId Required, External ID of assessment string Required
requestDate Optional change date search start. Accepts date in MM-DD-YYYY and YYYY-MM-DD formats date None.

Body Parameters

None.

Response Information

Resource Description

List of response IDs

ChangesResponse

Name Description Type Additional information
ResponseIds   Collection of integer None.

Response Formats

application/json, text/json

Sample:

{
  "ResponseIds": [
    1,
    2
  ]
}

application/xml, text/xml

Sample:

<ChangesResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/BrilliantAssessments.Services.AssessmentIntegration.Models">
  <ResponseIds xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:int>1</d2p1:int>
    <d2p1:int>2</d2p1:int>
  </ResponseIds>
</ChangesResponse>

 

GET api/assessmentresponse/getassessmentresponses/{assessmentId}

Performs search for all assessment responses regardless of their Status

Request Information

URI Parameters

Name Description Type Additional information
assessmentId Required, External ID of assessment string Required

Body Parameters

None.

Response Information

Resource Description

List of response IDs

ChangesResponse

Name Description Type Additional information
ResponseIds   Collection of integer None.

Response Formats

application/json, text/json

Sample:

{
  "ResponseIds": [
    1,
    2
  ]
}

application/xml, text/xml

Sample:

<ChangesResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/BrilliantAssessments.Services.AssessmentIntegration.Models">
  <ResponseIds xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:int>1</d2p1:int>
    <d2p1:int>2</d2p1:int>
  </ResponseIds>
</ChangesResponse>

 

POST api/assessmentresponse/createassessmentresponse

Create an Assessment Response against a known assessment/survey. The contact details can either be set by specifying a ContactId or if unknown, the contact details.

The response returns the ResponseID and the ResponseURL.  You can either redirect the user to that URL, or, by setting up a Welcome email, you can have the system send them an email with the unique link for them.

Request Information

URI Parameters

None.

Body Parameters

 

CreateAssessmentResponseRequest

Name Description Type Additional information
ExternalId   string Required
ReportIdentifier   string None.
GroupName   string None.
BccEmail   string None.
ContactId   string None.
BusinessName   string None.
FirstName   string Required
LastName   string Required
Email   string Required
CustomerType   string None.
OrganisationL1   string None.
OrganisationL2   string None.
OrganisationL3   string None.
OrganisationL4   string None.
OrganisationL5   string None.
Classifiers (Collection)      
  Key   string The Classifier Name
  Value   String Value
ReturnOKOnValidationFailure   Bit True/False
ReturnAction   Number 1 = Redirect (goes to specified URL on completion instead of showing the completion screen) 2= Add button (display a button alongside the report print button(s) with the text specified below - and linked to the URL). 
ReturnURL   String full URL
Button Text   String Only applicable if Return Action = 2

Response Information

Resource Description

CreateAssessmentResponseResult

Name Description Type Additional information
Message   string None.
ResponseID   Number The response ID Assigned
ResponseURL   string The unique response URL for the response

 

Related articles

Comments

0 comments

Please sign in to leave a comment.