Developer Documentation

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

Workflow Setup Installation Events Manual Close Endpoint Sample Response Sample Logic Sample Files Error Messages

Sample Workflow

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

Setting Up Your Integrity Advocate App

  1. Go to https://integrityadvocate.com and either log in or register.
  2. Click "Add New Application" and fill out the simple form.
  3. Click "EDIT" next to your newly-created app.
  4. Make note of your Application Id and your API2 Key. These are all used when making a call to the Integrity Advocate API.
  5. 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 (https://www.yoursite.com) in order to have Integrity Advocate function properly.

Installing Integrity Advocate on Your Site

  1. After completing app setup, click "EDIT" next to your app and copy the code that looks similar to the following from the text box:
    1. <script src="//integrityadvocate.com/Integrity/Embed?appid=XXXXX-XXXXX-XXXXX" async></script>
  2. Paste that code on any page you wish to have proctored, ideally just before the closing </body> tag.
  3. REQUIRED: You must add a custom "Participant Identifier" for your app that will automatically use the provided variable as the participant's unique identifier. This may make it easier to integrate with your system. To do this, add the "participantid" string parameter to the embed script in #1. The sample would then look like the following if we wanted to provide a participant's unique ID of "123456":
    1. <script src="//integrityadvocate.com/Integrity/Embed?appid=XXXXX-XXXXX-XXXXX&participantid=123456" async></script>
    2. NOTE: participantid must be URL encoded.
  4. REQUIRED: You must add a custom "Participant First Name" for your app that will automatically use the provided variable as the participant's first name. If provided, this will be matched with the name on the photo ID provided by our proctors.
    1. <script src="//integrityadvocate.com/Integrity/Embed?appid=XXXXX-XXXXX-XXXXX&participantfirstname=John" async></script>
    2. NOTE: participantfirstname must be URL encoded.
  5. REQUIRED: You must add a custom "Participant Last Name" for your app that will automatically use the provided variable as the participant's Last name. If provided, this will be matched with the name on the photo ID provided by our proctors.
    1. <script src="//integrityadvocate.com/Integrity/Embed?appid=XXXXX-XXXXX-XXXXX&participantlastname=Smith" async></script>
    2. NOTE: participantlastname must be URL encoded.
  6. OPTIONAL: You may add a custom "Proctor Name" for your app for each page being proctored by adding the "proctorname" string parameter to the embed script in #1. The sample would then look like the following if we wanted to give one page the name "Custom App Name":
    1. <script src="//integrityadvocate.com/Integrity/Embed?appid=XXXXX-XXXXX-XXXXX&proctorname=Custom%20App%20Name" async></script>
    2. NOTE: proctorname must be URL encoded.
  7. OPTIONAL: You may add a custom "Camera Fail Redirect URL" for your app that is specific to the hosting page and will override any other app level redirect setting. To do this, add the "camerafailurl" string parameter to the embed script in #1. The sample would then look like the following if we wanted to provide a redirect URL to "https://www.google.ca":
    1. <script src="//integrityadvocate.com/Integrity/Embed?appid=XXXXX-XXXXX-XXXXX&camerafailurl=https%3a%2f%2fwww.google.ca" async></script>
    2. NOTE: camerafailurl must be URL encoded, as seen above.
    3. NOTE: camerafailurl must include "http://" or "https://".
  8. Your page should now be collecting user data used in proctoring, provided you have activated and purchased a package for your app.
    1. NOTE: If your app is not paid/activated, it will be in "demo mode". No data is collected in demo mode and demo sessions are not proctored.

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_FlashForced
    1. This event is raised when Integrity Advocate is forced to run using the Flash backup.
  5. IA_PrivacyPolicyReviewed
    1. This event is raised when the Participant has confirmed they have read the privacy policy.
  6. IA_UserPhotoPreview
    1. This event is raised when the Participant has taken a snapshot of themselves in the Integrity Advocate panel.
  7. IA_UserPhotoSubmit
    1. This event is raised when the Participant submits the snapshot of themselves.
  8. IA_UserPhotoAccept
    1. This event is raised when the Participant's submitted snapshot is accepted by Integrity Advocate for review.
  9. IA_PhotoID1Preview
    1. This event is raised when the Participant has taken a snapshot of their government-issued photo ID card.
  10. IA_PhotoID1Submit
    1. This event is raised when the Participant submits the snapshot of their government-issued photo ID card.
  11. IA_PhotoID1Accept
    1. This event is raised when the Participant's submitted snapshot is accepted by Integrity Advocate for review.
  12. IA_PhotoID2Preview (if applicable)
    1. This event is raised when the Participant has taken a snapshot of their government-issued photo ID card.
  13. IA_PhotoID2Submit (if applicable)
    1. This event is raised when the Participant submits the snapshot of their secondary photo ID card.
  14. IA_PhotoID2Accept (if applicable)
    1. This event is raised when the Participant's submitted snapshot is accepted by Integrity Advocate for review.
  15. IA_PhotoID3Preview (if applicable)
    1. This event is raised when the Participant has taken a snapshot of their government-issued photo ID card.
  16. IA_PhotoID3Submit (if applicable)
    1. This event is raised when the Participant submits the snapshot of their teriary photo ID card.
  17. IA_PhotoID3Accept (if applicable)
    1. This event is raised when the Participant's submitted snapshot is accepted by Integrity Advocate for review.
  18. IA_Stream
    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_Stream', function (e) {
    // Your code here
});
        

Manually Closing a Session

By default, when a session ends, the Integrity Advocate system waits 10 minutes to ensure no additional data will be received for the session, then it closes the session automatically, sending it for review.

If you wish to mitigate this 10 minute period, you can manually close a session with a simple call to a URL.

URL Structure: https://integrityadvocate.com/Integrity/SessionComplete?appid<your app id>&participantid=<participant id>

URL Example: https://integrityadvocate.com/Integrity/SessionComplete?appid=XXXXX-XXXXX-XXXXX&participantid=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.
  3. 500 - Internal Server Error. There was a problem with your request. Please ensure the input variables are correct and are URL encoded.

Please note that if for some reason this call fails, the session will be automatically closed after the 10 minute period.

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.

Two sample projects (one in PHP and the other in .NET) are included at the bottom of this page. These projects show the method by which you must structure your calls to the Integrity Advocate API and should be easily convertible to other languages.

URL Structure: https://integrityadvocate.com/api2/<API Endpoint>/<method name>?<additional parameters here>

URL Example: https://integrityadvocate.com/api2/Sessions/Get?offset=0&next=25

Endpoint Methods

Sessions/Get

This method returns a JSON object that contains 3 parts:

  1. Sessions
    1. This is a JSON array of Session objects that match the parameters provided. See "Parameters" later in this document for more information on offset, next, and other parameters.
    2. The following flags may be returned from the Integrity Advocate API:
      (Please note - The Flag Id is provided in brackets next to the Flag name below)
      • (1) Participant not in camera view
      • (2) Multiple participants
      • (3) Utilised electronic device
      • (4) Other
      • (5) Clear image of ID not provided
      • (6) Clear image of participant not provided
      • (8) Information received was unclear and/or did not meet requirements
      • (9) Name on Photo ID does not match Session
      • (10) Possible unethical behavior
      • (11) Non-participation
      • (12) Utilised headphones
    3. Please see the Sample Response below for a sample (including the flags listed above) of the response provided to a valid API call.
  2. SessionCount
    1. This is the count of the total number of Sessions that match the parameters provided, ignoring paging parameters (like offset and next). See "Parameters" later in this document for more information on offset, next, and other parameters.
  3. RequestDate
    1. This is the date and time that the request was made.

Endpoint Parameters

  1. offset (int)
    1. This parameter is used in conjunction with the next parameter for paging through Session data. The maximum number of sessions that Integrity Advocate's API will return is 100. In order to retrieve Sessions 101 to 200, you would need to use "offset=100&next=100". DEFAULT: 0
  2. next (int)
    1. This parameter is used in conjunction with the offset parameter for paging through Session data. The maximum number of sessions that Integrity Advocate's API will return is 100. In order to retrieve Sessions 101 to 200, you would need to use "offset=100&next=100". DEFAULT: 100
  3. sessionstart (string)
    1. This parameter allows you to retrieve only sessions that have started since the provided date. The format for this parameter is yyyy-MM-d HH:mm:ss.fff. This parameter must be URL encoded.
  4. sessionend (string)
    1. This parameter allows you to retrieve only sessions that have started before the provided date. This can be used with the sessionstart parameter to retrieve Sessions between a range of dates. The format for this parameter is yyyy-MM-d HH:mm:ss.fff. This parameter must be URL encoded.
  5. sessionmodified (string)
    1. This parameter allows you to retrieve all sessions that have been modified (started, reviewed, flags added or removed) since the sessionmodified date. The format for this parameter is yyyy-MM-d HH:mm:ss.fff. Server date is in MST. Current server time is 2018-12-10 20:43:20.128. This parameter must be URL encoded.
  6. participantidentifier (string)
    1. This parameter allows you to specify a participant that you wish to retrieve Session information about. This is the participantid field that was provided via the embedded script querystring during the participant's session. This parameter must be URL encoded.

Sample Response

{
    "Sessions":[
    {
        "ProctorName":"Your App Name",
        "ParticipantIdentifier":"[[Participant Identifier from host system]]",
        "StartDate":"2014-11-3 06:48:32.322",
        "EndDate":"2014-11-3 07:01:23.111",
        "DismissedFaceNotFoundWarningCount": 0,
        "Status":"In Progress",
        "UserPhotoURL": "https://integrityadvocate.com/Home/GetImage?id=XXXXXX",
        "IPAddresses":[
            "23.45.67.891"
        ],
        "Browsers":[
            "MSIE 9"
        ],
        "CaptureURLs":[
            "http://www.yourdomain.com/yourpath?yourquerystring"
        ],
        "FlagData": []
    },
    {
        "ProctorName":"Your App Name",
        "ParticipantIdentifier":"[[Participant Identifier from host system]]",
        "StartDate":"2014-11-3 07:39:42.320",
        "EndDate":"2014-11-3 08:01:26.407",
        "DismissedFaceNotFoundWarningCount": 7,
        "Status":"Invalid",
        "UserPhotoURL": "https://integrityadvocate.com/Home/GetImage?id=XXXXXX",
        "IPAddresses":[
            "123.45.67.891"
        ],
        "Browsers":[
            "MSIE 9"
        ],
        "CaptureURLs":[
            "http://www.yourdomain.com/yourpath?yourquerystring"
        ],
        "FlagData": [{
            "FlagId": 5,
            "FlagName": "Clear image of ID not provided",
            "FlagDetails": "No photo identification was provided by the participant.",
            "ImageUrl": "https://integrityadvocate.com/Home/GetImage?id=XXXXXX"
            }, {
            "FlagId": 1,
            "FlagName": "Participant not in camera view",
            "FlagDetails": "Participant left computer immediately after ID verification.",
            "ImageUrl": "https://integrityadvocate.com/Home/GetImage?id=XXXXXX"
        }]
    },
    {
        "ProctorName":"Your App Name",
        "ParticipantIdentifier":"[[Participant Identifier from host system]]",
        "StartDate":"2014-11-3 10:32:14.358",
        "EndDate":"2014-11-3 11:02:29.187",
        "DismissedFaceNotFoundWarningCount": 14,
        "Status":"Valid",
        "UserPhotoURL": "https://integrityadvocate.com/Home/GetImage?id=XXXXXX",
        "IPAddresses":[
            "98.76.54.321"
        ],
        "Browsers":[
            "Chrome 38"
        ],
        "CaptureURLs":[
            "http://www.yourdomain.com/yourpath?yourquerystring"
        ],
        "FlagData": []
    }
    ],
    "SessionCount":15,
    "RequestDate":"2014-11-18 14:57:27.850"
}
        

Sample Programming Logic

Below are some samples for programming logic, independent of code language.

Automated Update

The following implementation would allow a host system to automatically poll the Integrity Advocate API (via a Windows service or chron job, etc), using the resulting response data to update records as appropriate.

  1. Retrieve updated session data from the Integrity Advocate API.
    1. Recommended call: https://integrityadvocate.com/api2/Sessions/Get?offset=0&next=100&sessionmodified=2018-08-8%2012%3A23.45.123
    2. The "sessionmodified" parameter is provided a URL encoded date string in the appropriate format. In this example, it should be from two minutes ago. We recommend storing a "LastPolled" variable somewhere on your system and using that datetime to populate this parameter. Please consult the Endpoint Parameters documentation for more information on the sessionmodified parameter.
    3. The above API call would return the top 100 sessions that have been started, reviewed, or had flags added or removed since 2018-08-8 12:23.45.123 MST. A loop should be used to obtain all of the available results, using the "offset" and "next" parameters with the "SessionCount" variable returned in the JSON data.
  2. Set the "LastPolled" variable to the current datetime (in MST).
    1. This is referred to in 1b., above.
  3. Loop through each session in the returned data set.
    1. The session data is a JSON object. For more information on the structure of the session data object, please review the Sample Response section of this document.
    2. As participants can complete proctored training in more than one session, a participant may show up more than once in the response data. You may also receive session data for training that is not fully complete.
    3. You may wish to check the completion of the host activity and skip any sessions from participants that are not complete in your system.
  4. (If ID verification only) Update the validity data on your system, using the ParticipantIdentifier variable to identify the appropriate completed activity records.
    1. If the session has a Status of "In Progress", the session has been started and is currently under way OR is awaiting review. Do nothing with this session.
    2. If the session has a Status of "Valid", update its activity status in your system to valid.
    3. If the session has a Status of "Invalid", update its activity status in your system to invalid. Send an email to the participant informing them of the invalid status. Include the flag data (with the image data) provided in the JSON response. Also include a link to a page on your system that will allow the user to resubmit their ID for verification without having to redo the activity. NOTE: Only allow for reset if the session is flagged with Flags with FlagIDs 5, 6, 8, or 9.
  5. (If ID verification + proctoring) Check for activity completion.
    1. Check that the activity has been completed and is ready for a determination of validity.
  6. (If ID verification + proctoring) Retrieve all session data for current loop participant.
    1. Recommended call: https://integrityadvocate.com/api2/Sessions/Get?offset=0&next=100&participantidentifier=[[participantidfromloop]]
    2. The above call will return a maximum of 100 records. A loop should be used to obtain all of the available results, using the "offset" and "next" parameters with the "SessionCount" variable returned in the JSON data.
  7. (If ID verification + proctoring) Use all participant specific session data to determine validity.
    1. Loop through each session, checking validity.
    2. If any session Status is "In Progress" there is still a session that is in review. Skip this participant.
    3. If any session Status is "Invalid" and has flags with the FlagIDs 1, 2, 3, 4, 10, or 11, update activity validity on your system as invalid.
    4. If any session Status is "Invalid" and has flags with the FlagIDs 5, 6, 8, or 9 AND no other valid sessions, update session as invalid, but send participant the link to a page on your system that will allow them to present their photo ID again without completing the activity again. See Allowing the Participant to Re-submit Identification for more details.
    5. If any session Status is "Invalid" and has flags with the FlagIDs 5 or 8, AND has other valid sessions, for the activity completion, update the activity validity on your system as valid.
    6. If there are no sessions with a Status of "Invalid", update the activity validity on your system as valid.

Administrator Review

The following implementation would allow a host system to integrate in real-time with Integrity Advocate. This would permit administrators to review the session validity from within the host system and to override it, if necessary. This should be done on the same page where the admin reviews the results for the participant's activity.

  1. Retrieve all session data for the participant.
    1. Recommended call: https://integrityadvocate.com/api2/Sessions/Get?offset=0&next=100&participantidentifier=[[participantid]]
    2. The "participantidentifier" parameter should be provided the same participantid originally provided to the Integrity Advocate system when the participant began the activity.
    3. The above API call would return a maximum of 100 records. A loop should be used to obtain all of the available results, using the "offset" and "next" parameters with the "SessionCount" variable returned in the JSON data.
  2. Display all session data for admin review.
    1. This should include the user photo, session status, and any flags (including captured images and comments from the reviewers) that were added to the session by reviewers.
    2. The session data is a JSON object. For more information on the structure of the session data object, please review the Sample Response section of this document.
  3. Provide admin with ability to override the Integrity Advocate ruling.
    1. Sometimes there are issues that have reasonable explanations. In those cases the admin will need the ability to override the Integrity Advocate ruling on your system. Some sort of interface must be provided for this.

Allowing the Participant to Re-submit Identification

In some cases, the participant will have submitted identification that is invalid due to poor image quality, presenting a photocopy of the identification, etc. In some of those cases (listed in the Automated Update section above), the participant will need a way to re-submit their identification without having to re-do the training.

This page should simply load the Integrity Advocate proctoring JavaScript and provide the participantid originally provided when the participant first started the activity. The content of the page is unimportant, other than to thank the participant for re-submitting their identification.

PHP and .NET Sample Files

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

Sample .NET Project: https://integrityadvocate.com/Samples/IntegrityAPI_CSharp.zip

Error Messages and Codes

X00001: Please note: You are using an insecure browser. As of January 12, 2016, Microsoft stopped providing security updates for any version of Internet Explorer under version 11.

Integrity Advocate takes the security of your personal information seriously and only supports secure, modern web browsers. Please upgrade to Internet Explorer 11 or use Chrome or Firefox.

This error is returned when a participant is using an older, insecure web browser (such as Internet Explorer before version 11). The participant should upgrade or switch to a newer browser. Integrity Advocate recommends Firefox or Chrome for the best experience.

X00002: We have detected that you are using Safari 8.0.2. There are known issues with that version of Safari that may prevent you from interacting with the software used in Integrity Advocate. Please update Safari.

This error is returned when a participant is using this specific version of Safari (8.0.2). The participant should upgrade their Safari or switch to Chrome or Firefox. Integrity Advocate recommends Firefox or Chrome for the best experience.

X00003: There appears to be a problem with the installation and integration of Integrity Advocate on this site.

This error is returned from activated (paid) apps when the embedded <script> tag does not include a participantid and participantfirstname and participantlastname. See "Installing Integrity Advocate on Your Site" above for more details on installation.

X00004: Error accessing webcam.

This error (which can be worded differently) is returned when there is an issue accessing the participant's webcam. This can occur if the participant does not have a webcam or if the webcam is in use by another application.

X00005: We have detected that you are using an outdated version of Safari on an iPhone/iPad. For security reasons you must use at least Safari 11 on iOS 11.

This error is returned when the participant is using less than Safari version 11 on an iPhone/iPad not running iOS 11. The participant must update to at least Safari 11 on iOS 11 to use Integrity Advocate on their iPhone/iPad device.

PLEASE NOTE: This is our most recent API documentation (v2). If you have a legacy app (if you are unsure, you do not have a legacy app), you can access the legacy API documentation here: https://integrityadvocate.com/Home/DevelopersAPI1