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)
