Sandbox Verification Source

In order to facilitate integration testing with the SheerID REST API, we have developed the Sandbox Verification Source. This allows developers to make API requests which behave just like production requests without incurring traffic against our verification databases.

Usage

The Sandbox Verification Source is used when verification requests are issued to the hostname services-sandbox.sheerid.com. An example URL is shown below:

https://services-sandbox.sheerid.com/rest/0.5/verification

Request Details

The Sandbox Verification Source is able to simulate a number of different verification scenarios. Most verifications require at a minimum the following 3 fields to be supplied in a request to the verify method. For more information about these fields, refer to the listFields method documentation.

  • FIRST_NAME
  • LAST_NAME
  • BIRTH_DATE

Some verifications require different or additional information such as postal code, identification number, or a discharge date.

Controlling the Verification Results

Testing Instructions for AUTHORITATIVE

Additionally, the results of the response from the Sandbox Verification Source can be controlled by passing a specific value for certain fields such as BIRTH_DATE. Refer to the tables below for lists of possible outcomes.

Here is the hierarchical order of fields in which we attempt to verify first

  1. BIRTH_DATE
  2. SSN_LAST4
  3. ID_NUMBER
  4. POSTAL_CODE

Most verifications can be controlled using the date of birth since it is the first field in the order above.

Field Value Supplied Verification Result Summary
BIRTH_DATE An odd birth year (ex: 1991-04-26) false The individual was identified, but not currently enrolled/affiliated.
BIRTH_DATE An even birth year (ex: 1992-04-26) true The individual was identified and currently enrolled/affiliated.
BIRTH_DATE Any future date (ex: 2099-04-26) null The individual was unable to be identified.

When verifying faculty and teachers for university or K12, you can use the postal code.

Field Value Supplied Verification Result Summary
POSTAL_CODE An odd postal code (ex: 97401) false The individual was identified, but not currently enrolled/affiliated.
POSTAL_CODE An even postal code (ex: 97402) true The individual was identified and currently enrolled/affiliated.
POSTAL_CODE A postal code of 0 (ex: 0) null The individual was unable to be identified.

When verifying a retired military service member, you can use the discharge date. We define a military retiree as an individual who has served a minimum of 20 years and has been discharged. To simulate this in the sandbox we assume the user joined the service on their 18th birthday and served 20 years or more.

Fields Value Supplied Verification Result Summary
BIRTH_DATE
STATUS_START_DATE
A discharge date before the user’s 38th birthday
(ex: BIRTH_DATE: 1974-04-26 and STATUS_START_DATE: 2005-04-26)
false The individual was identified, but not currently enrolled/affiliated.
BIRTH_DATE
STATUS_START_DATE
A discharge date after the user’s 38th birthday
(ex: BIRTH_DATE: 1974-04-26 and STATUS_START_DATE: 2013-04-26)
true The individual was identified and currently enrolled/affiliated.
STATUS_START_DATE Any future discharge date (ex: 2099-4-26) null The individual was unable to be identified.

When verifying non-profit, you can use the non-profit organization’s identification number.

Field Value Supplied Verification Result Summary
ID_NUMBER An odd id number (ex: 12345) false The individual was identified, but not currently enrolled/affiliated.
ID_NUMBER An even id number (ex: 12346) true The individual was identified and currently enrolled/affiliated.
ID_NUMBER A id number of 0 (ex: 0) null The individual was unable to be identified.

When verifying an Employee you will have to use the POSTAL_CODE since it is the only required field of the 4 fields mentioned above in the hierarchical order.

Field Value Supplied Verification Result Summary
POSTAL_CODE An odd postal code (ex: 97401) false The individual was identified, but not currently enrolled/affiliated.
POSTAL_CODE An even postal code (ex: 97402) true The individual was identified and currently enrolled/affiliated.
POSTAL_CODE A postal code of 0 (ex: 0) null The individual was unable to be identified.

When verifying a First Responder you can use the BIRTH_DATE however ONLY Police can simulate AUTHORITATIVE verification using BIRTH_DATE.

Field Value Supplied Verification Result Summary
BIRTH_DATE An odd birth year (ex: 1991-04-26) false The individual was identified, but not currently enrolled/affiliated.
BIRTH_DATE An even birth year (ex: 1992-04-26) true The individual was identified and currently enrolled/affiliated.
BIRTH_DATE Any future date (ex: 2099-04-26) null The individual was unable to be identified.

When verifying affiliation types that do not have an authoritative source to check against the verification will return null. To test manual verification scenarios a user can use the asset upload api method to upload documents which can be reviewed in the asset review utility in the control center and approved or rejected.

Testing Server Delay/Latency

Occasionally, SheerID authoritative sources may be experiencing delays. To simulate a delay for the verification response, perform a verification using FIRST_NAME = delay and LAST_NAME = $delayInMilliseconds, up to 10000 (10 seconds).

Example verification request with an 8 second delay:

$ curl -H "Authorization: Bearer $TOKEN" -d _affiliationTypes=FACULTY -d organizationType=UNIVERSITY -d FIRST_NAME=Delay -d LAST_NAME=8000 -d BIRTH_DATE=1999-12-01 -d [email protected] -d organizationId=191982 https://services-sandbox.sheerid.com/rest/0.5/verification

Testing Recoverable Errors and Unsupported Instant Verification Scenarios

SheerID authoritative sources may return multiple results for a verification request based on the fields submitted for verification. Additionally, authoritative sources may be unavailable or we may not have authoritative coverage for the specific affiliation attempting to be verified.

To simulate these error scenarios for the verification response, perform a verification using FIRST_NAME = error and LAST_NAME = $errorCode.

Error codes that can be tested in this fashion:

Code Description
0 Unknown error
39 Awaiting documentation upload
40 More information is needed to uniquely match an individual
41 Data source is unable to satisfy request
49 Data source is temporarily unavailable

Example verification request with a data source temporarily unavailable error:

$ curl -H "Authorization: Bearer $TOKEN" -d _affiliationTypes=FACULTY -d organizationType=UNIVERSITY -d FIRST_NAME=Error -d LAST_NAME=49 -d BIRTH_DATE=1999-12-01 -d [email protected] -d organizationId=191982 https://services-sandbox.sheerid.com/rest/0.5/verification

To see the full list of API error codes click here.

Testing Instructions for SSO

First, you will need to pick an Organization that has an SSO provider configured. You should be able to find this in Organization Management (tag: HEI-SSO). These organizations can also be listed via REST API (see the following example URL):

https://services-sandbox.sheerid.com/rest/0.5/organization?type=UNIVERSITY&tag=HEI-SSO&country=GB

Use the following curl command as an example to test SSO verification using the sandbox.

$ curl -H "Authorization: Bearer $TOKEN" -d _affiliationTypes=FACULTY -d organizationType=UNIVERSITY -d FIRST_NAME=Sam -d LAST_NAME=Doe -d BIRTH_DATE=1999-12-01 -d EMAIL=$(uuidgen)@example.com -d organizationId=191982 https://services-sandbox.sheerid.com/rest/0.5/verification

Next, we will use the following curl command to check to make sure the result = null for the verification by using the requestId from the previous curl response.

$ curl -H "Authorization: Bearer $TOKEN" https://services-sandbox.sheerid.com/rest/0.5/verification/${requestId}

Next, in a browser navigate to the following url using the requestId that was returned in the response from the command above.

https://services-sandbox.sheerid.com/rest/0.5/verification/sso/${requestId}

The page that opens up will have instructions on how to log in etc. If you run the previous curl command again you will notice that the status=’PENDING’ and the result=null. This page uses cookies to store the SSO session token so if you wish to do multiple verifications you will need to clear cookies between tests or use the incognito browser.

If you log in with valid credentials (provided on the login page) that match the affiliation type(s) being verified (see table below), you will see the following message ‘Verification Complete’. Now if you re-run the previous curl command you will notice that the status=’COMPLETE’ and the result=’true’

If you log in with valid credentials (provided on the login page) that do not match the affiliation type(s) being verified (see table below), you will see the following message ‘Verification Complete’. Now if you re-run the previous curl command you will notice that the status=’COMPLETE’ and the result=’false’

Username Affiliations
myself Teacher, Student
alterego Student
superego Teacher

Testing Instructions for EMAIL LOOP

In the Organization Management you will notice that each organization has an email domain whitelist. These domains can be used to validate that the user actually has an email address with the whitelist.

An email is sent to the user with a link with a verification code that will need to be clicked. If the user clicks the link and the verification code is correct then they have been validated by the EMAIL_LOOP source.

Testing Instructions for IP ADDRESS

IP_ADDRESS is similar validated in a similar fashion. In the Organization Management you will notice that there is an IP List. Every request has a metadata where the IP Address is stored.

If the user’s IP Address is in the org list then they will get validated by the IP_ADDRESS source.

Testing Instructions for High Assurance Teacher Verification

In order to test the High Assurance Teacher Verification you must set the assuranceLevel=HIGH

Field Value Supplied Verification Result Summary
POSTAL_CODE An even postal code (ex: 97404) true The individual was identified and currently enrolled/affiliated.
POSTAL_CODE An odd postal code (ex: 97401) false The individual was identified, but did not have a complete match on the necessary data.
POSTAL_CODE A postal code of 0 (ex: 0) null The individual was unable to be identified.

If the result = false you can use the following FIRST_NAME to test the different verification errors:

Result Code First Name Verification Error(s)
false FOO FIRST NAME NOT VERIFIED, LAST NAME NOT VERIFIED
false BAR EMAIL.domain NOT VERIFIED
false ANY NAME EMAIL NOT VERIFIED, EMAIL.domain NOT VERIFIED

Testing Instructions for VALIDATION

In the Organization Management you will notice that each organization has an email domain whitelist. These domains can be used to validate that the user actually has an email address with the whitelist. When performing a VALIDATION request, the result will be true when the provided email is consistent with a configured whitelist domain for the organization involved, and null when the email address provided does not reflect a configured whitelist domain.