Quick Start

Welcome to the SheerID Developer Center, where you can learn and explore the SheerID Services.

Before you get started:

What type of verification service would you like to implement for your company?

Learn what you can do on our Examples of Hosted and API Implementations page.

What you need to know before we get started:

First we need to determine the level of technical support you have at your disposal. SheerID is capable of taking on the majority of implementation work for our hosted implementation services. You provide the basic information and our SheerID TechDesign Team will create a custom hosted service for you. Download the Implementation Worksheet below to get started on all the information the implementation team will need to get started.

In most cases, SheerID suggests the Hosted JavaScript Lightbox Modal method as the Gold Standard for verification as it provides the best customer experience, the most transparent verification service, and the fastest track to pushing your special offer live. Other reasons why this is the best option, SheerID hosts the form content which means you always have first access to the latest updates to our service. Have a change to the offer? SheerID can quickly turn around any updates to the content, and easily shut the service off or pause it if the offer should expire need to change.

Account Setup

To use the developer sandbox or the full API, you need to sign up for an account.

Once you have done this, log in to the Control Center and create an API key for use in testing. NOTE: you are best off using one API key for testing and one API key for production. You may create any number of API keys without charge, so please make use of the create and disable functions as needed.

Verification Types

Several types of verification are supported. Implementations should include Asset Review verification whenever applicable, to insure that 100% of eligible audience has a verification opportunity.

AUTHORATATIVE verification is conducted against one or more data sources providing confirmation that the field data submitted matches an authoritative data source.

ASSET_REVIEW verification is conducted by document review specialists to confirm the document uploaded is a valid document type, and includes data required for verification.

VALIDATION verification is based on a match of submitted organization ID and email address domain against a configured set of valid domains for that organization ID.

EMAIL_LOOP can be used in conjunction with VALIDATION or by itself, verification is based on successful receipt and click-through of a tokenized link delivered to a specified email address.

IP_ADDRESS verification is based detecting whether the IP address that verification subject is coming from is associated with a specific (UNIVERSITY) organization ID.

SSO available for compatible UNIVERSITY organizations only, verification is based on a successful login to the school portal using school-provided user credentials.

HONOR_SYSTEM verification is always returned as successful when data field requirements are met.

General API Usage Guidelines

Authentication

All API calls must be authenticated, please see our Issuing Requests page for more details.

Rate Limiting

REST API requests are subject to rate limits. Any applicable rate limits for a given REST resource endpoint are listed on its documentation page. Please also refer to the Rate Limiting documentation for more general information.

Date Format

By default, all dates are expected in the format of YYYY-MM-DD (for example, 1996-07-23).

If you would like to set a custom date format you must provide a formatting string along with the data. This is indicated by prefixing the field name with a percent sign (%) like so:

curl -d "BIRTH_DATE=July 23, 96" -d "%BIRTH_DATE=MMMM d, yy" … $VERIFICATION_URL

The formatting string follows the conventions of java.text.SimpleDateFormat

Error Codes and Conditions

API responses come primarily through HTTP status codes, though sometimes there is additional information in the response. Below are the error codes you can expect to receive and their general meanings. Individual REST endpoints may also have more specific documentation about expected error conditions. For an overview of how HTTP status codes are used to relay errors (with some examples), see our REST HTTP Errors page.

Code Meaning Suggestions
200, 204
Call completed successfully.
400 The request you have submitted is not valid Check the documentation and ensure you are supplying all required parameters. Ensure that data supplied is valid. Refer to returned error message(s) for more detailed information.
401 The access credentials provided were not valid Check the access token provided.
403 You do not have access to this resource Check that you have been granted access to the resource you are attempting to access.
404 You are trying to reach an endpoint that does not exist Check the documentation and your spelling. For URLs that represent an object, check that the ID of an object you are trying to access is valid.
405 You are trying to reach an endpoint that does not allow the method attempted. Look up the method you are using in the documentation and check which HTTP method you are using.
500 Our server experienced a problem and was unable to meaningfully respond Please contact SheerID for more information.

Backwards Compatibility

API stability and reliability are key goals for SheerID. As a matter of principle and development practice, we take pains to ensure backwards compatibility for our established public REST APIs. Backwards compatibility implies that we will not make changes to existing endpoints, methods, parameters or JSON structures explicitly published and made available to customers. We understand that API development is costly, and our goal is to avoid changes that would require customers integrated with our APIs from having to make updates to existing integrations.

However, in accordance with software industry norms, and in order to continue to evolve our platform and deliver increasing value to our customers, we reserve the right to augment these established APIs with additional endpoints, methods, parameters, and JSON elements. The best practice to ensure stability of your integration is to code defensively so that your integration can tolerate the presence of unexpected properties or objects that are not available at the time of implementation.

An example configuration for the Jackson JSON library is as follows, which would annotate the class to which the JSON is being mapped:

@JsonIgnoreProperties(ignoreUnknown = true)

Admin Console

Once your implementation is live, you can access it through the production services login. From the Services.SheerID admin area you will be able to run a verification report, use the search tool to look up specific verification requests, manage your users by adding or deleting who has access, and much more. Click below to access the live production admin console.

To request training on the capabilities of our admin console, please contact our Client Services department.

Sandbox Testing

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.

Additionally, we have developed automatic document review, which allows developers to test their review process without having to include a manual approval or rejection of every test.

API Project Planning Checklist

To ensure best practices are taken into consideration from the outset of your implementation of the SheerID API services platform, a best practices planning checklist has been provided for your convenience. The PDF can be accessed below.

The SheerID Professional Services team is available for any questions you may have at any point during implementation. To contact them directly, please use the contact form.