REST API
For advanced implementations, you may use our REST API directly and bypass the JavaScript library as an API client. This section will introduce you to the basics of our REST API, including how to handle responses, errors, and to move successfully from step to step. See our REST API reference for details.
Basics
The SheerID API is organized around REST.
Base URL
The base URL for the SheerID REST API is https://services.sheerid.com/rest/v2/.
The current version is 2.0.0.
Authentication
Certain endpoints require a Bearer Token for authentication. Retrieve your API access token from MySheerID under Settings »» Access Tokens. You will also find your Account ID, which you will need in certain conversion tracking operations.
GET /rest/v2/info HTTP/1.1
Content-Type: application/json
Authorization: Bearer {YOUR_ACCESS_TOKEN}
Retrieve Theme
If you would like to use the CSS and messaging that you configured at MySheerID, then you must first fetch the
program theme. To do this, make a GET request to the /program/{programId}/theme endpoint:
GET /rest/v2/program/<YOUR_PROGRAM_ID>/theme HTTP/1.1
Host: services.sheerid.com
Content-Type: application/json
See Program Theme for more information about what is contained in the program theme object, and Get Program Theme for the detailed API reference.
Retrieve Verification Segment
Now we need to begin a verification. This will retrieve what kind of segment you will be verifying against (Student, Active Military, Inactive Military, Teacher, etc.).
To retrieve the initial step for your flow, make the following POST request:
POST /rest/v2/verification HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>
{
"programId": "<YOUR_PROGRAM_ID>"
}
Response:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "collectStudentPersonalInfo", // The step in the verification flow the current verification is on
"submissionUrl": "https://services.sheerid.com/rest/v2/verification/111111111111111111111111/step/collectStudentPersonalInfo", // The URL to use to complete the current step
"errorIds": [],
"segment": "student",
"subSegment": null
}
At this point a verification has begun and can be referenced with the verificationId, in the example case 111111111111111111111111. This ID will be used for all
future interactions with this verification ID.
Verify a User
Now that we have our step (in our demo case we are verifying a student, so our step is collectStudentPersonalInfo), we can submit a verification subject to verify.
We will be submitting a student for verification, so we will need to fill out this structure:
{
"firstName": "",
"lastName": "",
"birthDate": "YYYY-MM-DD",
"email": "",
"organization": {
"id": 0,
"name": ""
}
}
Schemas for all verification subjects can be found here.
Once all data has been collected, make a POST call to the URL collected in the previous step’s submissionUrl response with the data, e.g.
{
"firstName": "Randy",
"lastName": "Random",
"birthDate": "YYYY-MM-DD",
"email": "[email protected]",
"organization": {
"id": 1,
"name": "Organization name"
}
}
This example will cause an instant success response because it uses any name in the First Name field. The only string that wouldn’t work in this example is REJECTED.
Using REJECTED as the value for firstName would yield an unsuccessful verification and take you to the docUpload step.
To see comprehensive testing rules, see the Test Program knowledge base article.
Success
If the verification was successful, then you will receive a response like this:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "success", // The step in the verification flow the current verification is on
"rewardCode": "REWARD", // The reward code that was configured in the self service tool
"errorIds": [],
"segment": "student", // The current segment we are verifying
"subSegment": null // The current subsegment we are verifying if applicable
}
After providing the rewardCode to your user to be used in your system, you’re done!
Document Upload & Review
If the verification was unsuccessful, then you will need to collect documentation to prove the user is part of the verification segment, and submit it to SheerID. In this situation, the document upload response will be returned after submitting the personal info of the user.
For example:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "docUpload", // The step in the verification flow that the current verification is on
"submissionUrl": "https://services.sheerid.com/rest/v2/verification/111111111111111111111111/step/docUpload", // The URL to use to complete the current step
"errorIds": [],
"segment": "student", // The audience segment targeted in your program
"subSegment": null // The audience subsegment, if applicable
}
docUpload step required including them in body of a multipart-form-data request, and included a doc upload token. That way of uploading documents is deprecated. Be sure to follow the steps described below when uploading documents to SheerID.
After collecting the documents to be uploaded, initiate the process by making a POST request to the submissionUrl provided in the doc upload response. The request should include a Content-Type header of application/json. The body of the request should be a JSON payload that includes the names, sizes, and MIME types of the files being uploaded. See the Doc Upload API documentation for details.
Example request:
POST /rest/v2/verification/<YOUR_VERIFICATION_ID>/step/docUpload HTTP/1.1
Content-Type: application/json
Content-Length: 207
[
{
"fileName": "foo.jpg",
"mimeType": "image/jpeg",
"fileSize": 1111
},
{
"fileName": "bar.png",
"mimeType": "image/png",
"fileSize": 2222
}
]
The response will contain a documents array that includes an object for each document referenced in the request, in the same order. Each object in that array will include an upload URL for that document.
The response will also contain a submission URL, to be used after all files have been uploaded.
Example response:
{
"verificationId": "5c70719d2145e32d7d37af8e",
"currentStep": "docUpload",
"errorIds": [],
"segment": "student",
"subSegment": null,
"locale": "en_US",
"country": "US",
"documents": [
{
"documentId": "1234",
"status": "PENDING",
"mimeType": "image/jpeg",
"fileSize": 1111,
"uploadUrl": "https://upload.example.com/1111",
"errors": []
},
{
"documentId": "1234",
"status": "PENDING",
"mimeType": "image/png",
"fileSize": 2222,
"uploadUrl": "https://upload.example.com/2222",
"errors": []
}
],
"submissionUrl": "https://services.sheerid.com/rest/v2/verification/5c70719d2145e32d7d37af8e/step/completeDocUpload "
}
For each file to be uploaded, send a PUT request to the uploadUrl for that file, with the contents of the file itself as the request body.
Be sure to include a Content-Type header that matches the mimeType, and a Content-Length header that matches the fileSize.
Confirm that a 200 status is returned for each uploaded file.
Note: If you would like to simulate receiving different responses for document uploads using a testMode Program, please see the special files listed here.
Once all files have been uploaded and a 200 response has been returned for each, send a POST request to the submissionUrl found in the response described above, with an empty request body.
Pending
If documents have been successfully uploaded to SheerID for review, then you will receive a response that looks like this:
{
"verificationId": "62bf6bd5e61aee18c9783b10",
"currentStep": "pending",
"errorIds": [],
"segment": "teacher",
"subSegment": null,
"locale": "en-US",
"country": "US",
"statusUrl": "https://services.sheerid.com/rest/v2/verification/62bf6bd5e61aee18c9783b10",
"awaitingStep": "docUpload",
"maxReviewTime": "20_MIN",
"estimatedReviewTime": "A_FEW_MINUTES",
"lastResponse": {
"documents": [],
"verificationId": "62bf6bd5e61aee18c9783b10",
"currentStep": "docUpload",
"errorIds": [],
"segment": "teacher",
"subSegment": null,
"locale": "en-US",
"country": "US",
"submissionUrl": "https://services.sheerid.com/rest/v2/verification/62bf6bd5e61aee18c9783b10/step/docUpload",
"rejectionReasons": [],
"maxReviewTime": "20_MIN",
"estimatedReviewTime": "A_FEW_MINUTES"
}
}
The statusUrl can be used to retrieve the current status of the verification. This endpoint can be polled to watch for changes to the verification state.
If the document review is still in progress, then you will continue to get the pending response.
If the document review is completed and marked successful (the document proved the user was associated with the segment), then you will receive the success response.
If the document review is completed and marked rejected (the document did not prove the user was associated with the segment), then you will receive the docUpload response, which indicates
that the user may attempt to verify by uploading additional documents (repeating the process above). There is a limited number of times that documents can be uploaded for a verification.
Getting Current Status
The current status of a verification can be retrieved at any time by making a GET request to https://services.sheerid.com/rest/v2/verification/{verificationId}. The
response from this endpoint will match the responses you get a various points through the flow (success, docUpload, pending, error, etc.). This endpoint can be
used to continue a verification that was halted at any point.
Program Theme
The program theme object contains all theme and messaging information that was configured for a program in the self-service tool at MySheerID. The theme includes a full CSS stylesheet that can be included when rendering the form (as long as CSS selectors match), and any messaging that should be used throughout the verification process, including field labels, success messages, etc.
Internationalization (i18n)
The program theme contains an intl property which is a structured JSON object containing translated messaging to use when rendering the forms to collect the data
necessary for the verification flow. This object will also include custom messaging that was configured in the self-service tool.
ErrorId
The errorId property under the intl property can be used to find error messaging to display to users when a given error is thrown. Any time a response has an
errorIds property, it means an error occurred and appropriate messaging should be looked up here in the program theme based on the error ID that was returned.
Custom CSS
The customCss property on the program theme contains a CSS stylesheet as it was configured in the self-service tool. This is heavily reliant on certain selectors
existing on the page, so it may or may not be useful when not using the JavaScript library.
Errors
Any response while interacting with the API could be an error response. There are two types of possible errors: recoverable and non-recoverable.
Recoverable Errors
A recoverable error will include the step the verification was on before the error occurred. So if you were attempting to submit a student subject for the collectStudentPersonalInfo step, you could receive this response:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "collectStudentPersonalInfo", // The step in the verification flow the current verification is on
"errorIds": [
// The errors that occurred when attempting the step
],
"segment": "student", // The current segment you are verifying
"subSegment": null, // The current subsegment you are verifying if applicable
"submissionUrl": "https://submission-url.com" // The URL to submit the person data to
}
The errorIds will indicate what went wrong, but since the currentStep is not error it means the issue could be corrected. These errors occur when bad data was
supplied, e.g. an invalid birth date, invalid email, invalid organization, etc.
Messages
Recoverable errors can be caused by invalid entries from the user, so the messaging that should be shown can be found in the program theme.
of the response that was returned. The messaging found in the errorId section of the messages should be appropriate to show users.
Example
When submitting a student subject for the collectStudentPersonalInfo if you sent this request:
{
"firstName": "First",
"lastName": "Last",
"birthDate": "1-1-1",
"email": "notValidEmail,com",
"organization": {
"id": 1,
"name": "Organization name"
}
}
You would receive the following errorIds:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "collectStudentPersonalInfo", // The step in the verification flow the current verification is on
"errorIds": [
"invalidBirthDate",
"invalidEmail"
],
"segment": "student",
"subSegment": null
}
This lets you know that you need to perform the collectStudentPersonalInfo step again, and you should find the invalidBirthDate and invalidEmail messages in the
program theme to find the message to display to the user.
Non Recoverable Errors
A non recoverable error will have error as the currentStep and will provide both a list of errorIds as well as a systemErrorMessage that can be used to determine
what caused the failure to assist with debugging. An example error response would look like this:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "error", // The step in the verification flow the current verification is on
"errorIds": [
// The errors that occurred when attempting the step
],
"systemErrorMessage": "Debugging message", // A description of the cause for the error to aid with debugging
"segment": "student", // The current segment we are verifying
"subSegment": null, // The current subsegment we are verifying if applicable
"submissionUrl": "https://submission-url.com" // The URL to submit the person data to
}
These errors occur when programs or verifications are not found, when internal SheerID errors occur, or when a step can not be completed for a non-user related reason.
Messages
The supplied errorIds can be used to look up the user facing messages in the program theme just like for recoverable errors, however
these can potentially be much more generic messages and difficult to understand. So to provide feedback for the integrator, the systemErrorMessage property can be used
to understand what went wrong. These messages are NOT intended to be displayed to users, they are only for the integrators benefit.
Example
When submitting a student subject for the collectStudentPersonalInfo step, if you sent this request:
{
"firstName": "First",
"lastName": "Last",
"birthDate": "1-1-1",
"email": "notValidEmail,com",
"invalidKey": "something"
}
You would receive the following error response:
{
"verificationId": "111111111111111111111111", // Verification ID that should be used for all future calls
"currentStep": "error", // The step in the verification flow the current verification is on
"errorIds": [
"invalidRequest"
],
"systemErrorMessage": "Unexpected property 'invalidKey', expected one of: firstName, lastName, birthDate, email, universityId, metadata"
}
This lets you know you need to change the structure of your student subject request. Look
up the invalidRequest error in the program theme to find the message to show to the user. The systemErrorMessage tells you that you need to remove the invalidKey property
and only use the provided allowed keys.
Make sure you have your program ID before starting.
Retrieve your programId from your Program tab in MySheerID.
