UPDATE: We have recently updated the API to version 2. If you have a legacy app, you can access the legacy API documentation here: https://integrityadvocate.com/Home/DevelopersAPI1

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. 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.
  4. OPTIONAL: You may 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.
  5. 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://".
  6. OPTIONAL: You may 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.
  7. OPTIONAL: You may 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.
  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.

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/headphones
      • (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
    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.

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. 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. This parameter must be URL encoded.
  5. participantidentifier (string)
    1. This parameter allows you to specify a participant that you wish to retrieve Session information about. This is usually an email address. This parameter must be URL encoded.

Sample Response

{
    "Sessions":[
    {
        "ProctorName":"Your App Name",
        "ParticipantIdentifier":"participant@youremail.com",
        "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@youremail.com",
        "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":"anotherparticipant@someemail.com",
        "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"
}
        

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.

Basic Standard Full
Service ID Verification Only ID Verification & Biometric-Assisted Proctoring* ID Verification & Full Proctoring
Normal Application Online forms and non-critical/non-regulatory training & testing Critical/regulatory online training & testing Critical/regulatory online training & testing
Per-participant Fee $3.50 $5.00 $10.00
First 60 Minutes** N/A Included Included
Subsequent 30 minute blocks** N/A $0.50 per participant $0.50 per participant
Storage*** Included Included Included
* Biometric-Assisted proctoring uses facial recognition and optical character recognition algorithms to automate the proctoring process. Human reviewers are involved only when established confidence levels have not been achieved.

** As individual completion times will vary the time selected is based on average completion times.

*** Media capturing a user's image and any rules violations are kept for a minimum of of two years. Media of government issued ID shown and rule compliant participation are deleted within 24 hours of an invigilator's review.