Developer Documentation

All the information required to set up your own Integrity Advocate apps

Workflow Setup Installation Events End Session Endpoint Sample Response Sample Code Moodle Plugin

Sample Workflow

We have available a sample workflow, detailing the way Integrity Advocate works with your site.

Setting Up Your Integrity Advocate App

  1. Obtain an App Id and API Key from your Integrity Advocate integrations specialist.
  2. If you do not have an Integrity Advocate integrations specialist, book an appointment to speak with one.
  3. Please note: Integrity Advocate uses the most up-to-date browser security and as such requires a secure connection in order to transmit data. The host site must run a security certificate SSL (https://www.yoursite.com) in order to have Integrity Advocate function properly.

Installing Integrity Advocate on Your Site

  1. After your Integrity Advocate integrations specialist has set up your app, they will have provided you with an App Id, API Key, and an installation URL that looks something like the following:
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX" async></script>
  2. Place that code on any page you wish to have proctored, ideally just before the closing </body> tag.
  3. REQUIRED: participantidentifier: This should uniquely identify the participant in your system.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&participantidentifier=123456" async></script>
    2. NOTE: participantidentifier must be URL encoded.
  4. REQUIRED: courseid: The id of the course or activity the participant is completing.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&courseid=name%40email.com" async></script>
    2. NOTE: participantemail must be URL encoded.
  5. REQUIRED: participantfirstname: The participant's first name. This will be matched with the name on the participant's photo ID by our reviewers.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&participantfirstname=John" async></script>
    2. NOTE: participantfirstname must be URL encoded.
  6. REQUIRED: participantlastname: The participant's surname. This will be matched with the name on the participant's photo ID by our reviewers.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&participantlastname=Smith" async></script>
    2. NOTE: participantlastname must be URL encoded.
  7. REQUIRED: participantemail: The participant's email address. This is used to notify the participant of the status of their session(s).
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&participantemail=name%40email.com" async></script>
    2. NOTE: participantemail must be URL encoded.
  8. OPTIONAL activityid: A course is typically made up of one or more activities (quizzes, etc). For every activity a participant participates in, you can provide an activity ID for further tracking.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&activityid=123456" async></script>
    2. NOTE: activityid must be URL encoded.
  9. OPTIONAL externaluserid: This ID can be any string variable from your system, to allow for easier searching via the API.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&externaluserid=123456" async></script>
    2. NOTE: externaluserid must be URL encoded.
  10. OPTIONAL reviewcallback: Upon review of a Participant's session, this URL will receive a POST with the body containing a payload of the Participant details.
    1. <script src="https://ca.integrityadvocateserver.com/participants/integrity?appid=XXXXX-XXXXX-XXXXX&reviewcallback=https%3A%2F%2Fwww.yourdomain.com%2Fpathtoprocessparticipant" async></script>
    2. NOTE: reviewcallback must be URL encoded.
    3. Webhook reviewcallback requires HMAC authentication signature
    4. Sample Code

Sample Payload for "reviewcallback" Parameter

{
    "Course_Id": "ZZZZ",
    "Created": "1586808802",
    "Email": "jean.grey@xaviersschoolforthegifted.org",
    "FirstName": "Jean",
    "LastName": "Grey",
    "Modified": "1586813617",
    "Override_Date": "-1",
    "Override_LMSUser_FirstName": null,
    "Override_LMSUser_LastName": null,
    "Override_LMSUser_Id": null,
    "Override_Reason": null,
    "Override_Status": null,
    "Participant_Photo": "data:image/jpeg;base64,DATAURI",
    "ParticipantIdentifier": "XXXXXXXXXXXXX",
    "ResubmitUrl": "https://www.integrityadvocateserver.com/Participants/ResubmitIDLanding?v=XXXXXXXXXXXXXXXXXXXXXXYYYYYYYYYYYYYYYYYYYYYYYZZZZZZZZZZZZZZZZZZZZZ",
    "Status": "Invalid (ID)",
    "Sessions": [
        {
            "Activity_Id": "AAAAAAAA",
            "Click_IAmHere_Count": 0,
            "End": "1586809246",
            "Exit_Fullscreen_Count": 0,
            "Id": "XXXXXXXXXXXXXXXXXXXX",
            "Participant_Photo": "data:image/jpeg;base64,DATAURI",
            "Start": "1586808802",
            "Status": "Invalid (ID)",
            "Flags": [
                {
                    "CaptureData": "data:image/jpeg;base64,DATAURI",
                    "CaptureDate": "1586808852",
                    "Comment": "Name on account is \"Madelyne Pryor\". Name on photo ID is \"Jean Grey\". Please ensure the name on your ID matches the name on your account.",
                    "Created": "1586813603",
                    "Id": "34ee9b1a-5d42-4446-8616-096540e03830",
                    "FlagType_Id": 7,
                    "FlagType_Name": "Name on ID does not match account name"
                }
            ]
        }
    ]
}
        

Events

As the Participant goes through the Integrity Advocate process, several JavaScript events are raised. Your activity can monitor for these events, performing actions (such as enabling access to content only after the user photo and photo ID have been submitted). The events are as follows in sequence of when they are raised:

  1. IA_Loaded
    1. This event is raised when the Integrity Advocate proctoring panel has fully loaded, before the Participant is prompted for their photos.
  2. IA_CameraLive
    1. This event is raised when the Participant has successfully granted access to their camera and the feed has started.
  3. IA_CameraError
    1. This event is raised when there is an error encountered while attempting to access the Participant's camera.
  4. IA_PrivacyPolicyReviewed
    1. This event is raised when the Participant has confirmed they have read the privacy policy.
  5. IA_UserPhotoPreview
    1. This event is raised when the Participant has taken a snapshot of themselves in the Integrity Advocate panel.
  6. IA_UserPhotoSubmit
    1. This event is raised when the Participant submits the snapshot of themselves.
  7. IA_UserPhotoAccept
    1. This event is raised when the Participant's submitted snapshot is accepted by Integrity Advocate for review.
  8. IA_PhotoID1Preview
    1. This event is raised when the Participant has taken a snapshot of their government-issued photo ID card.
  9. IA_PhotoID1Submit
    1. This event is raised when the Participant submits the snapshot of their government-issued photo ID card.
  10. IA_PhotoID1Accept
    1. This event is raised when the Participant's submitted snapshot is accepted by Integrity Advocate for review.
    2. If you are using an ID verification only app, this will be the point the participant begins the activity.
  11. IA_Stream
    1. This event is raised when Integrity Advocate begins monitoring the Participant's activity.
  12. IA_Ready
    1. This event is raised when the Participant has completed all Integrity Advocate tasks and is ready to start the activity.

The above events can be monitored using the following code (jQuery):

$(document).bind('IA_Ready', function (e) {
    // Your code here
});

Ending a Session

REQUIRED: There are two ways to end a session and send it for review:

  1. JavaScript: Call "window.IntegrityAdvocate.endSession()"
  2. Call the End Session endpoint URL:
    • URL Structure: https://ca.integrityadvocateserver.com/participants/endsession?appid&courseid=course id<your app id>&participantidentifier=<participant identifier>
    • URL Example: https://ca.integrityadvocateserver.com/participants/endsession?appid=XXXXX-XXXXX-XXXXX&courseid=123&participantidentifier=123456

    You will receive different HTTP Status Codes in the response:

    1. 200 - OK. The session has been successfully closed.
    2. 404 - Not Found. The requested app, participant, or session could not be found. 404 will also be returned in the case that the participant's session has already been closed.
    3. 500 - Internal Server Error. There was a problem with your request. Please ensure the input variables are correct and are URL encoded.

Making a Call to the Integrity Advocate API

The Integrity Advocate API uses HMAC Authentication to authorize requests sent to the API. Each call made to the Integrity Advocate API must include specific information in the request header.

Integrity Advocate has three code samples for making a connection to our API:

  1. ASP.NET Core 3.1 MVC C#
  2. PHP
  3. Postman

The samples can be found in Sample Code, below.

API Endpoint Methods

GET api/course/{courseid}/participants

Retrieve a list of participants for a specific course.

Parameters:

  • nexttoken (string) - Pagination token, returned with the results of your API call (more details in "Response Variables" below).
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/1234/participants?nexttoken=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • limit (integer) - Specify the number of results to return per page.
    • Default value: 10
    • Maximum value: 10
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?limit=6
  • backwardsearch (boolean) - Determine if search is performed forward or backward.
    • Default value: false
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?backwardsearch=true


Please note that you can only use one of the following parameter sets per call.

  • lastmodified (timestamp) - Retrieve a list of all course Participants that have been modified (started, reviewed, flags added or removed) since the lastmodified date.
    • Unix epoch timestamp.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?lastmodified=1589397321

OR

  • lastname (string) - Retrieve a list of all Participants for the specified course with the provided last name.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?lastname=Smith&firstname=John
  • firstname (string) - Retrieve a list of all Participants for the specified course with the provided last name and first name.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?lastname=Smith&firstname=John

OR

  • status (string) - Retrieve a list of all Participants for the specified course with the specified status.
    • Must be URL encoded.
    • InProgress
    • Invalid (ID)
    • Invalid (Rules)
    • Valid
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?status=Valid

OR

  • email (string) - Retrieve a list of all Participants for the specified course matching the provided email address.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?email=johnsmith%40email.com

OR

  • externaluserid (string) - Retrieve a list of all Participants for the specified course matching the externaluserid parameter provided by the host system when the participant completed the activity.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participants?externaluserid=johnsmith%40email.com

Sample Response

{
    "IsFirstPage": true,
    "BackwardSearch": false,
    "NextToken": "{\"Modified\":\"1587670298\",\"App_Id\":\"XXXXXXXXXXXXXXX\",\"App_Id+ParticipantIdentifier+Course_Id\":\"XXXXXXXXXXXXXXX+ZZZZZZZ+CCCC\"}",
    "Participants": [
        {
            "Course_Id": "590",
            "Created": "1586963235",
            "Email": "scottsummers@email.com",
            "FirstName": "Scott",
            "LastName": "Summers",
            "Modified": "1587055818",
            "Override_Date": "-1",
            "Override_LMSUser_FirstName": null,
            "Override_LMSUser_LastName": null,
            "Override_Reason": null,
            "Override_Status": null,
            "Participant_Photo": "data:image/jpeg;base64,DATA URI",
            "ParticipantIdentifier": "XXXXXXXXX",
            "ResubmitUrl": "https://www.integrityadvocateserver.com/Participants/ResubmitIDLanding?v=QUERYSTRINGVARIABLE",
            "Status": "Valid",
            "Token": "{\"App_Id\":\"XXXXXXXXXXXXXXX\",\"Modified\":\"1587055818\",\"App_Id+ParticipantIdentifier+Course_Id\":\"XXXXXXXXXXXXXXX+ZZZZZZZ+CCCC\"}",
            "SortValue": "1587055818"
        },
        ...
    ]
}
        

GET api/participant

Retrieve the full details for a single participant, including all sessions, flags, and captured images.

Parameters:

  • participantidentifier (string - required) - The participantidentifier provided by your system when the participant completed the activity.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/participant?participantidentifier=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • courseid (string - required) - The courseid provided by your system when the participant completed the activity.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/participant?courseid=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Sample Response

{
    "Course_Id": "ZZZZ",
    "Created": "1586808802",
    "Email": "jean.grey@xaviersschoolforthegifted.org",
    "FirstName": "Jean",
    "LastName": "Grey",
    "Modified": "1586813617",
    "Override_Date": "-1",
    "Override_LMSUser_FirstName": null,
    "Override_LMSUser_LastName": null,
    "Override_LMSUser_Id": null,
    "Override_Reason": null,
    "Override_Status": null,
    "Participant_Photo": "data:image/jpeg;base64,DATAURI",
    "ParticipantIdentifier": "XXXXXXXXXXXXX",
    "ResubmitUrl": "https://www.integrityadvocateserver.com/Participants/ResubmitIDLanding?v=XXXXXXXXXXXXXXXXXXXXXXYYYYYYYYYYYYYYYYYYYYYYYZZZZZZZZZZZZZZZZZZZZZ",
    "Status": "Invalid (ID)",
    "Sessions": [
        {
            "Activity_Id": "AAAAAAAA",
            "Click_IAmHere_Count": 0,
            "End": "1586809246",
            "Exit_Fullscreen_Count": 0,
            "Id": "XXXXXXXXXXXXXXXXXXXX",
            "Participant_Photo": "data:image/jpeg;base64,DATAURI",
            "Start": "1586808802",
            "Status": "Invalid (ID)",
            "Flags": [
                {
                    "CaptureData": "data:image/jpeg;base64,DATAURI",
                    "CaptureDate": "1586808852",
                    "Comment": "Name on account is \"Madelyne Pryor\". Name on photo ID is \"Jean Grey\". Please ensure the name on your ID matches the name on your account.",
                    "Created": "1586813603",
                    "Id": "34ee9b1a-5d42-4446-8616-096540e03830",
                    "FlagType_Id": 7,
                    "FlagType_Name": "Name on ID does not match account name"
                }
            ]
        }
    ]
}
        

PATCH api/participant/{participantidentifier-courseid}

In some cases it may be necessary to override the Integrity Advocate ruling for a participant. The PATCH endpoint allows for the easy updating of this information. PATCH is used in the same way as a POST or PUT method.

Body Parameters:

  • Override_Date (string - required) - A Unix timestamp describing the current datetime.
  • Override_Status (string - required) - The status you wish to override the Integrity Advocate ruling.
    • Invalid
    • Valid
  • Override_Reason (string - required) - The reason for the override.
  • Override_LMSUser_FirstName (string - required) - The first name of the user on the host system that is performing the override.
  • Override_LMSUser_LastName (string - required) - The Last name of the user on the host system that is performing the override.
  • Override_LMSUser_Id (string - required) - The Id of the user on the host system that is performing the override.

Response

On a successful PATCH, the updated object will be returned.

GET api/course/{courseid}/participantsessions

Retrieve a list of participant sessions for a specific course.

Parameters:

  • nexttoken (string) - Pagination token, returned with the results of your API call (more details in "Response Variables" below).
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/1234/participantsessions?nexttoken=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • limit (integer) - Specify the number of results to return per page.
    • Default value: 10
    • Maximum value: 10
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?limit=6
  • backwardsearch (boolean) - Determine if search is performed forward or backward.
    • Default value: false
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?backwardsearch=true
  • activityid (string) - Retrieve a list of all ParticipantSessions for the specified course matching the specified activityid.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?activityid=PPPPPPPPPP


Please note that you can only use one of the following parameter sets per call.

  • lastname (string) - Retrieve a list of all ParticipantSessions for the specified course with the provided last name.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?lastname=Smith&firstname=John
  • firstname (string) - Retrieve a list of all ParticipantSessions for the specified course with the provided last name and first name.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?lastname=Smith&firstname=John

OR

  • status (string) - Retrieve a list of all ParticipantSessions for the specified course with the specified status.
    • Must be URL encoded.
    • InProgress
    • Invalid (ID)
    • Invalid (Rules)
    • Valid
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?status=Valid

OR

  • participantidentifier (string) - Retrieve a list of all ParticipantSessions for the specified course matching the specified activityid.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/course/{courseid}/participantsessions?participantidentifier=PPPPPPPPPP

Sample Response

{
    "IsFirstPage": true,
    "BackwardSearch": false,
    "NextToken": "{\"Id\":\"XXXXXXXXXXXXXXXX\",\"SearchFilter_Name\":\"drake+robert+XXXXXXXXXXXXXXXXXX\",\"SearchFilter_App_Id-Course_Id-Activity_Id\":\"XXXXXXXXXXXXXXXXXX+YYYY+ZZZZZZZZZZZ\"}",
    "ParticipantSessions": [
        {
            "Activity_Id": "35555491",
            "Course_Id": "590",
            "Email": "robert.drake@xaviersschoolforthegifted.org",
            "FirstName": "Robert",
            "LastName": "Drake",
            "Start": "1586988635",
            "End": "1586988765",
            "Participant_Photo": "data:image/jpeg;base64,DATAURI",
            "Status": "Valid",
            "Token": "{\"Id\":\"XXXXXXXXXXXXXXXX\",\"SearchFilter_Name\":\"drake+robert+XXXXXXXXXXXXXXXXXX\",\"SearchFilter_App_Id-Course_Id-Activity_Id\":\"XXXXXXXXXXXXXXXXXX+YYYY+ZZZZZZZZZZZ\"}",
            "SortValue": "drake+robert+XXXXXXXXXXXXXXXXXX"
        },
	...
    ]
}
        

PATCH api/participantsessions

In some cases it may be necessary to override the Integrity Advocate ruling for a specific participant session or sessions for a single activity. The PATCH endpoint allows for the easy updating of this information. PATCH is used in the same way as a POST or PUT method.

URL Parameters:

All of the following URL parameters must be provided with this PATCH call.

  • courseid (string) - Specifies the courseid provided to Integrity Advocate.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/participantsessions?courseid=PPPPPPPPPP
  • activityid (string) - Specifies the activityid provided to Integrity Advocate.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/participantsessions?activityid=ZZZZZZZZZZZZZZZZ
  • participantidentifier (string) - Specifies the participantidentifier provided to Integrity Advocate.
    • Must be URL encoded.
    • Example: https://ca.integrityadvocateserver.com/api/participantsessions?participantidentifier=YYYYYYYYYYY

Body Parameters:

  • Override_Date (string - required) - A Unix timestamp describing the current datetime.
  • Override_Status (string - required) - The status you wish to override the Integrity Advocate ruling.
    • Invalid
    • Valid
  • Override_Reason (string - required) - The reason for the override.
  • Override_LMSUser_FirstName (string - required) - The first name of the user on the host system that is performing the override.
  • Override_LMSUser_LastName (string - required) - The Last name of the user on the host system that is performing the override.
  • Override_LMSUser_Id (string - required) - The Id of the user on the host system that is performing the override.

Response

On a successful PATCH, HTTP Status 200 will be returned.

Sample Code

Sample C# .NET Core 3.1 Project: https://integrityadvocate.com/Samples/IntegrityAdvocateAPI_CSharp_05062020.zip

Sample C# .NET Core 3.1 Project (reviewcallback): https://integrityadvocate.com/Samples/IntegrityAdvocateWebhook_CSharp_06152020.zip

Sample PHP Project: https://integrityadvocate.com/Samples/IntegrityAdvocateAPI_PHP_05062020.zip

Sample Postman Pre-request Script:

Paste the following into the Pre-request Script area of Postman

var uuid = require('uuid');
var moment = require("moment")

var AppId = "YOUR APP ID";
var APIKey = "YOUR API KEY";
var uri = pm.request.url.toString();
var requestURI = uri.toLowerCase();
if (uri.indexOf("?") > -1) {
    requestURI = encodeURIComponent(uri.substr(0, uri.indexOf("?"))).toLowerCase();
}
var requestMethod = pm.request.method;
var requestTimeStamp = moment(new Date().toUTCString()).valueOf() / 1000;
var nonce = uuid.v4();
var signatureRawData = AppId + requestMethod + requestURI + requestTimeStamp + nonce;
var signature = CryptoJS.enc.Utf8.parse(signatureRawData);
var secretByteArray = CryptoJS.enc.Base64.parse(APIKey);
var signatureBytes = CryptoJS.HmacSHA256(signature, secretByteArray);
var requestSignatureBase64String = CryptoJS.enc.Base64.stringify(signatureBytes);
var hmacKey = "amx " + AppId + ":" + requestSignatureBase64String + ":" + nonce + ":" + requestTimeStamp;
postman.setEnvironmentVariable("hmacKey", hmacKey);
        

You would then use the environment variable "hmacKey" in the Headers for your request as the value for "Authorization".

Moodle Plugin

Use the link below to download the most recent version of our Moodle plugin.

https://bitbucket.org/mwebv/moodle-block_integrityadvocate/downloads/moodle-block_integrityadvocate.zip