Verification Scenarios

The following is a list of common scenarios that integrators should keep in mind when testing applications of the SheerID verification API.

Successful Verification

Scenario: Instant Success

Issuing a valid verification request with a set of fields that represents an individual with a currently active affiliation results in a successful verification response, indicated by a VerificationResponse with its result property equal to true.

Next Step: Enable access to the protected content or offer.

 

Scenario: Document Upload Success

This scenario consists of the following steps:

  1. Attempt and fail to instantly verify (see: Instant False, Instant Inconclusive, or Instant Verification Not Supported)
  2. User uploads a document using Asset Upload API. This document can be submitted directly to SheerID as described in the Direct Asset Upload documentation.
  3. Uploaded document is reviewed by our team of document review specialists
  4. Upon receiving a notification of the verification response being updated (or by periodically polling), the integrator performs an Inquire request to fetch the updated VerificationResponse

A successful response will be indicated by a VerificationResponse with its result property equal to true.

Next Step: Enable access to the protected content or offer.

Failed Verification

 

Scenario: Instant False

Issuing a valid verification request with a set of fields that represents an individual with a currently inactive affiliation results in a unsuccessful verification response, indicated by a VerificationResponse with its result property equal to false.
This scenario differs from Instant Inconclusive because in this case, we are able to uniquely match an individual based on the data provided, but have conclusively determined that she does not currently have the desired affiliation status.

Next Step: Integrator may choose to allow the user to proceed with a document upload or end the verification process with a message or alternative offer.

 

Scenario: Instant Inconclusive

Issuing a valid verification request with a set of fields that is unable to be matched in any of our authoritative affiliation data sources results in an inconclusive verification response, indicated by a VerificationResponse with its result property equal to null, and an empty errors array.
Reasons for an inability to match may include:

  • User entered incorrect/incomplete information, for example use of a nickname versus a full name
  • Data entry issues (typos)
  • Data coverage or data correctness issue within the data source itself

Next Step: Integrator should allow the user to proceed with a document upload to prove their affiliation.

Errors

Note: Refer to the General Developer Guidelines for a discussion of our REST API error conventions.

Scenario: Instant Failure and Document Upload Failure

This scenario has the same steps as described above in Document Upload Success. In this case, a failure response will be indicated by a VerificationResponse with its result property equal to false or null, and an errors array containing one or more errors that describe the reasons the document was rejected.

Next Step: Integrator may choose to display the error messages to the user and prompt for another document upload or end the verification process with a message or alternative offer.

Scenario: Bad Request

Integrators will encounter a 400 Bad Request HTTP status code and no VerificationResponse payload in the following instances:

  • All required parameters are not supplied
  • Person is too young (we can only verify individuals older than 13 years)
  • Data format validation failure – email address, date format, etc.
  • Verification type is limited to AUTHORITATIVE, but no such data source exists to verify the specified organization or affiliation (Error code: 3)

This type of error can generally be prevented by doing a reasonable amount of validation on the user inputs prior to sending a request to SheerID.

Next Step: Notify the end-user and/or fix the data and re-submit a valid request.

Scenario: Recoverable Error

Issuing a valid verification request with a set of fields that is unable to be uniquely matched for a specific, recoverable reason will result in an inconclusive verification response, indicated by a VerificationResponse with its result property equal to null, and an errors array which contains one or more Error objects containing a recoverable error code.
Recoverable errors include:

  • Unable to match a single individual (Error code: 40)
  • Attempting to use organization name instead of organization ID, but name is ambiguous (Error code: 10)

Next Step: Integrator should use the Update Verification method to re-submit the verification request, providing additional information to resolve the issue.

 

Scenario: Instant Verification Not Supported

Issuing a valid verification request with a set of fields that is unable to be instantly verified using any of our data sources will result in an inconclusive verification response, indicated by a VerificationResponse with its result property equal to null, and an errors array which contains one or more Error objects containing a error code that indicates instant verification is not available.
Conditions where instant verification may not be available (either temporarily or permanently) include:

  • Data source is temporarily unavailable (Error code: 49)
  • The data provided puts the individual into a segment which cannot be verified by the data source(s) used for that affiliation type, (for example, a military veteran who served prior to 1985) (Error code: 41)
  • No instant data source exists to to verify this affiliation type, document review is the only way to perform a verification (Error code: 39)

Next Step: Integrator should allow the user to proceed with a document upload to continue the verification process.

References

Other developer documents that may be helpful during the integration and testing process: