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:

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

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

Errors

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

Scenario: Bad Request

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

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:

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:

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: