Developer Documentation

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

Workflow Setup Installation Events Manual Close Endpoint Sample Response 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.

Please note: We strongly recommend that this code is called when the Participant completely finishes their training to inform Integrity Advocate that the training is done and processing can occur.

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.

A sample project in PHP is included at the bottom of this page. This project shows the method by which you must structure your calls to the Integrity Advocate API and is easily convertible to other languages.

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

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

Endpoint Methods

Participants/Get

This endpoint method is used to retrieve information about a specific Participant or a list of Participants, depending on the parameters provided in the call.

This method returns a JSON object that contains 2 parts:

  1. Participants
    1. This is a JSON array of Participant objects that match the parameters provided.
    2. Parameters:
      • offset (integer) - This parameter is used in conjunction with the next parameter for paging through Participant data. The maximum number of Participants that Integrity Advocate's API will return in a single call is 50. In order to retrieve Participants 51 to 100, you would need to use "offset=50&next=50". DEFAULT: 0
      • next (integer) - This parameter is used in conjunction with the offset parameter for paging through Participant data. The maximum number of Participants that Integrity Advocate's API will return is 50. In order to retrieve Participants 51 to 100, you would need to use "offset=50&next=50". DEFAULT: 50
      • participantidentifier (string) - This parameter allows you to specify a single participant for whom you wish to retrieve results data. This is the participantid field that was provided via the embedded script querystring during the participant's session. This parameter must be URL encoded.
      • lastmodified (datetime) - This parameter allows you to retrieve a list of all Participants that have been modified (started, reviewed, flags added or removed) since the lastmodified date. The format for this parameter is yyyy-MM-d HH:mm:ss.fff. Server date is in MST. Current server time is 2019-06-15 23:58:11.974. This parameter must be URL encoded.
    3. Response fields:
      • ReviewStatus (string) - This field is the Participant's status. Possible values:
        • In Progress - Still in progress or awaiting review.
        • Valid - Review is valid.
        • Invalid (ID) - Review is invalid due to an issue with the participant's ID card. The IDResubmitUrl variable (detailed below) contains a link that allows the user to submit their ID card again without having to repeat the training.
        • Invalid (Rules) - Review is invalid due to a rules violation.
      • ParticipantIdentifier (string) - This field is the unique identifier provided by your system when the Participant was engaged in the activity, for use in linking the Integrity Advocate data back to the appropriate enrollment in your system.
      • FirstName (string) - This field is the Participant's first name, as provided by your system to Integrity Advocate.
      • LastName (string) - This field is the Participant's last name, as provided by your system to Integrity Advocate.
      • Email (string) - This field is the Participant's email address, as provided by your system to Integrity Advocate (if applicable).
      • Application (string) - This field is the name of your app in Integrity Advocate.
      • Created (datetime) - This field is the date and time the Participant was created in the Integrity Advocate system.
      • Completed (datetime) - This field is the date and time the Participant completed the activity.
      • SessionCount (integer) - This field is the number of sessions it took the user to complete the activity.
      • FlagCount (integer) - This field is the number of flags (issues or problems) that have been applied to the Participant's session(s). 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
      • UserPhotoUrl (string) - This is a url to the main photo of the Participant captured during the activity.
      • IDResubmitUrl (string) - This is a url to a page where the Participant can re-submit their photo identification if there is a problem with their previous submission. Only populated when the ReviewStatus "Invalid (ID)" is returned.
      • Flags (JSON array) - This is an array of flag objects, detailing any issues with the data collected while the Participant was completing the activity. Flag fields include:
        • FlagId (integer) - The unique ID of the flag (flag Ids listed above)
        • FlagName (string) - The name of the flag.
        • FlagDetails (string) - A message from the human reviewers as to what the problem is and how the participant may resolve it.
        • ImageUrl (string) - The url to a frame from the video displaying the issue.
    4. Please see the Sample Response below for a sample (including the flags listed above) of the response provided to a valid API call.
  2. ParticipantCount
    1. This is the count of the total number of Participants that match the parameters provided, ignoring paging parameters (like offset and next). This parameter is used in conjunction with the next and offset parameters for paging through Participant data.

Sample Response

{  
   "Participants":[  
      {  
         "ReviewStatus":"Valid",
         "ParticipantIdentifier":"1234567",
         "FirstName":"Scott",
         "LastName":"Summers",
         "Email":"ssummers@email.com",
         "Application":"Your app name",
         "Created":"2018-07-04T15:02:29.403",
         "Completed":"2018-07-04T15:44:51.107",
         "SessionCount":1,
         "FlagCount":0,
         "UserPhotoUrl":"//integrityadvocate.com/Capture/GetCapture?v=XXXXXXXXXXXXXXXX",
         "IDResubmitUrl":null,
         "Flags":[]
      },
      {  
         "ReviewStatus":"Invalid (ID)",
         "ParticipantIdentifier":"1234568",
         "FirstName":"Jean",
         "LastName":"Grey",
         "Email":"jgrey@email.com",
         "Application":"Your app name",
         "Created":"2018-07-05T09:43:18.803",
         "Completed":"2018-07-20T08:31:57.65",
         "SessionCount":1,
         "FlagCount":1,
         "UserPhotoUrl":"//integrityadvocate.com/Capture/GetCapture?v=XXXXXXXXXXXXXXXX",
         "IDResubmitUrl":"https://integrityadvocate.com/Integrity/ResubmitLanding?v=XXXXXXXXXXXXXXXX",
         "Flags":[  
            {  
               "FlagId":9,
               "FlagName":"Name on Photo ID does not match Session",
               "FlagDetails":"Participant's name in the session is Madeline Pryor. Name on session is Jean Grey. Please enter your name exactly as it appears on your ID.",
               "ImageUrl":"//integrityadvocate.com/Capture/GetCapture?v=XXXXXXXXXXXXXXXX"
            }
         ]
      },
      {  
         "ReviewStatus":"Invalid (Rules)",
         "ParticipantIdentifier":"1234569",
         "FirstName":"Warren",
         "LastName":"Worthington",
         "Email":"wworthington@email.com",
         "Application":"Your app name",
         "Created":"2019-04-11T10:44:45.547",
         "Completed":"2019-04-14T17:05:57.87",
         "SessionCount":1,
         "FlagCount":2,
         "UserPhotoUrl":"//integrityadvocate.com/Capture/GetCapture?v=XXXXXXXXXXXXXXXX",
         "IDResubmitUrl":null,
         "Flags":[  
            {  
               "FlagId":4,
               "FlagName":"Other",
               "FlagDetails":"Camera is frozen for approx 13 minutes",
               "ImageUrl":"//integrityadvocate.com/Capture/GetCapture?v=XXXXXXXXXXXXXXXX"
            },
            {  
               "FlagId":2,
               "FlagName":"Multiple participants",
               "FlagDetails":"Additional participant is helping original participant for approx 11 minutes",
               "ImageUrl":"//integrityadvocate.com/Capture/GetCapture?v=XXXXXXXXXXXXXXXX"
            }
         ]
      }
      ...
   ],
   "ParticipantCount":36
}
        

Sample Files

Sample PHP Project: https://integrityadvocate.com/Samples/IntegrityAPI_PHP.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