Searching Organizations

In this guide, we’ll go through the necessary steps to support searching for organizations via the REST API. The end result is a user experience able to support the search and display of organizations based on user input.

Overview

The organization search feature is used to return a list of supported organizations based on the full or partial name supplied by your user. Organization name and id are required fields to initiate a verification flow, so you should make sure that your user experience includes a way to fetch names and IDs from us.

One way to do so is using our API to request matching results based on a text string.

Execute a Search

To search for organizations that match a user-provided query string, perform a GET request with the following:

The orgSearchUrl, which you will retrieve from your program configuration.
Your search query, appended to your orgSearchUrl.

Example: Searching student organizations for “Harvard”

GET /rest/v2/program/{programId}/theme HTTP/1.1

A successful request returns a 200 OK response with a JSON object containing the orgSearchUrl.

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

{
    ...

    "config": {
        
        ...

        "orgSearchUrl": "https://orgsearch.sheerid.net/rest/organization/search?country=US&type=UNIVERSITY&name="
    }
}

Note: We recommend pulling the orgSearchUrl on page load to ensure that you have the most up-to-date value based on your program configuration.

Using the orgSearchUrl you obtained from your theme config, call the URL with the search term appended.

GET /rest/organization/search?country=US&type=UNIVERSITY&name=Harvard HTTP/1.1
Host: orgsearch.sheerid.net

A successful request returns a 200 OK response with an array of organizations that match the query string “Harvard” in the name key, along with their corresponding IDs.

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

[
    {
        "id": 1426,
        "name": "HARVARD UNIVERSITY (CAMBRIDGE, MA)",
        "country": "US",
        "type": "UNIVERSITY"
    },
    {
        "id": 1421,
        "name": "HARVARD - LAW SCHOOL (CAMBRIDGE, MA)",
        "country": "US",
        "type": "UNIVERSITY"
    },
    {
        "id": 1423,
        "name": "HARVARD GRADUATE SCHOOL OF EDUCATION (CAMBRIDGE, MA)",
        "country": "US",
        "type": "UNIVERSITY"
    },

    ...
]

Verify your User

In the examples above, the strings and IDs returned by your org search request should be included in the request body for the /step/collectStudentPersonalInfo POST request. For more details on verification steps, see Verification in our API reference.

Note: The organizationID submitted with each request is checked for eligibility for the program. If an ineligible organizationID is submitted, the recoverable error invalidOrganization is returned. Read more about recoverable errors in the REST API section.

Request:

POST ​/verification​/program​/{programId}​/step​/collectStudentPersonalInfo HTTP/1.1
Content-Type: application/json

{
    "firstName": "Jane",
    "lastName": "Ivy",
    "email": "[email protected]",
    "birthDate": "1999-09-30",
    "organization": {
        "name": "Harvard University",
        "id": 1426
    },
    "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
    }
}

A successful response will return a 200 OK status code and your new currentStep in the response body. If the user is succesfully verified instantly, your currentStep will be success and you can proceed to checkout with the offer code defined in your program.

If the API request was a success, but the user was not succesfully verified instantly, your current step will be docUpload and the response body will include the submissionUrl where you can submit the uploaded documentation.

Successful Instant Response

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

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

Unsuccessful Instant Response

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

{
    "currentStep": "docUpload",
    "verificationId": "5c82b0a58119982db2c28418",
    "submissionUrl": "https://services.sheerid.com/rest/v2/verification/5c82b0d68229982db2c28418/step/docUpload/693c7bdc83d04c9987008ee705690490",
    "segment": "student",
    "subSegment": null,
    "errorIds": []
}