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 API Key, your Client Signature, and your Client Secret. 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?apikey=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?apikey=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?apikey=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?apikey=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?apikey=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?apikey=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

URL Structure: https://integrityadvocate.com/api/<your api key>/<your client signature>/<your client secret>/<method name>?<additional parameters here>

URL Example: https://integrityadvocate.com/api/XXXXX-XXXXX-XXXXX/xxXXxxXxXXXxXXxxxx/XXXXXXXXXX/GetSessions?offset=0&next=25

Methods

GetSessions

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/IntegrityAdvocate_PHP.zip

Sample .NET Class: https://integrityadvocate.com/Samples/IntegrityAdvocate_DOTNET.zip

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.