API Walkthrough

In this guide, you’ll go through the necessary steps to perform a verification using our REST API. After completing this tutorial, you should have a grasp on the fundamental concepts involved in a SheerID API integration.

Overview

We will use the example of a verification flow for a US student in this tutorial, beginning with a /verification/ POST request, which will return a verificationId along with the submissionUrl, which you will use in subsequent requests until the verification is complete.

Terminology

Before you begin, let’s get familiar with the attributes you will encounter in this process.

API Token: Certain requests use a Bearer Token for authentication. Static API tokens can be managed within MySheerID by clicking on your user icon and choosing Access Tokens:

Note: Only users with the API Access role can generate or view tokens. Please check with your account admin if you cannot view tokens in MySheerID. For more on user roles and permissions see this article in our product documentation.

We also support OAuth2 with dynamically generated tokens. For more information, see API Tokens

programId: Retrieve your programId from your Program tab in MySheerID.

verificationId
Unique identifier for the ongoing verification.

submissionUrl
The URL where you will submit the required information for the the next step in the verification, e.g., docUpload.

currentStep
The current step in the verification.

errorIds
If applicable, an array of error IDs indicating a problem with the verification.

segment
The primary segment of the program, e.g., student, military. This value does not vary but is returned for convenience.

subSegment
The subsegment for the current verification, e.g., activeDuty is a possible subsegment in a military verification. This varies by the choice a user makes during a verification, but will always be one of the available subSegments configured for your program.

statusUrl
The URL to poll to determine the result of the document review.

For details on the endpoints and parameters found in this walktrough, see our REST API Reference.

Initiate Verification

Begin a verification process for a student by performing a POST request passing your programId to SheerID.

A successful response will return a 200 OK status and provide you with the following information to help you continue the verification:

"currentStep": "collectStudentPersonalInfo": The verification is successful and now it is time to present the user with a form asking for their details.
verificationId: You will need this identifier to see this verification through to completion.
submissionUrl: You will use this URL in the next step after you collect the user’s data. Note that the submissionUrl value that was returned includes the verificationId.

Request:

POST /rest/v2/verification HTTP/1.1
Host: services.sheerid.com
Content-Type: application/json

{
	"programId": "5c0c514b2cd3bc121b4ac71b"
}

Response:

HTTP/1.1 200 OK
Content-type: application/json

{
    "verificationId": "5c884a8fc7e5d8109070bf3f",
    "currentStep": "collectStudentPersonalInfo",
    "submissionUrl": "https://services.sheerid.com/rest/v2/verification/5c884a8fc7e5d8109070bf3f/step/collectStudentPersonalInfo",
    "errorIds": [],
    "segment": "student",
    "subSegment": null
}

Submission Request

With the submissionUrl from the verification response, you may now submit the user data for verification.

In this step we will test the two possible immediate outcomes when submitting student personal info: a successful instant verification and an unsuccessful instant verification. In the case of a successful instant, your currentStep will be success and you will be free to proceeed to checkout, providing the user with the offer code. With an unsuccessful instant, hope is not lost, you just need to proceed to the docUpload step.

Note: You would normally gather this information from a web form, either rendered via our JavaScript library or by a form of your making, but for this tutorial we are walking through steps manually.

Successful Instant Verification

In this first example, you will submit test user data to simulate a successful instant verification. Use any name in the firstName field to simulate success.

See Test Program for details on simulating outcomes in development mode.

Example Request 1: Successful Instant:

POST /rest/v2/verification/{verificationID}/step/collectStudentPersonalInfo HTTP/1.1
Host: services.sheerid.com
Content-Type: application/json

{
	"firstName": "Jane",
	"lastName": "Ivy",
	"birthDate": "1990-01-01",
	"email": "[email protected]",
	"organization": {
		"id": 4597,
		"name": "ALBANY LAW SCHOOL"
	}
}

Response:

HTTP/1.1 200 OK
Content-type: application/json

{
    "currentStep": "success",
    "verificationId": "5c8c19ffdac79a594a5a1320",
    "rewardCode": "YOUR_OFFER_CODE",
    "errorIds": [],
    "segment": "student",
    "subSegment": null
}

Unsuccessful Instant Verification

In this example, you will submit test user data to simulate an usuccessful instant verification. Use REJECTED as the firstName to simulate this outcome. You will then proceed to the docUpload step.

See Test Program for details on simulating outcomes in development mode.

Example Request 2: Unsuccessful Instant:

POST /rest/v2/verification/{verificationID}/step/collectStudentPersonalInfo HTTP/1.1
Host: services.sheerid.com
Content-Type: application/json

{
	"firstName": "REJECTED",
	"lastName": "Ivy",
	"birthDate": "1990-01-01",
	"email": "[email protected]",
	"organization": {
		"id": 4597,
		"name": "ALBANY LAW SCHOOL"
	}
}

Response:

HTTP/1.1 200 OK
Content-type: application/json

{
    "currentStep": "docUpload",
    "verificationId": "<YOUR_VERIFICATION_ID>",
    "submissionUrl": "https://services.sheerid.com/rest/v2/verification/<YOUR_VERIFICATION_ID>/step/docUpload",
    "segment": "student",
    "subSegment": null,
    "errorIds": []
}

Note: Consumers may need multiple attempts to provide the necessary documents to be verified. You must provide 3 document upload attempts per verification. SheerID will verify adherence to this guideline before your program can be launched in production.

Doc Upload

Request:

POST /rest/v2/verification/5c88710bb107283f54d84904/step/docUpload HTTP/1.1
Host: services.sheerid.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="filename"; filename="/Users/sheerId/Desktop/test-file.png


------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response:

HTTP/1.1 200 OK
Content-type: application/json

{
    "currentStep": "pending",
    "verificationId": "5c886b92b107283f54d84854",
    "statusUrl": "https://preview.sheerid.com/rest/v2/verification/5c886b92b107283f54d84854",
    "errorIds": [],
    "segment": "student",
    "subSegment": null
}

Get Verification Details

Now that your verification is in the pending step, you may want to check the status.

Request:

GET /rest/v2/verification/5c886b92b107283f54d84854/details HTTP/1.1
Host: services.sheerid.com
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Response:

HTTP/1.1 200 OK
Content-type: application/json

{
    "programId": "5c0d45f251cc4d31b7a222ca",
    "created": 1552444306323,
    "updated": 1552444363224,
    "lastResponse": {
        "currentStep": "pending",
        "verificationId": "5c886b92b107283f54d84854",
        "statusUrl": "https://preview.sheerid.com/rest/v2/verification/5c886b92b107283f54d84854",
        "errorIds": [],
        "segment": "student",
        "subSegment": null
    },
    "personInfo": {
        "firstName": "Joe",
        "lastName": "Ivie",
        "email": "[email protected]",
        "birthDate": "1990-01-01",
        "metadata": null,
        "organization": {
            "id": 4597,
            "name": "ALBANY LAW SCHOOL"
        }
    },
    "docUploadRejectionCount": 0
}