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.

To search for organizations that match a user-provided query string, perform a GET request on the /program/{programId}/organization endpoint, and include the query string in the request, e.g., "?name=UCLA".

Example: Searching student organizations for “Harvard”

GET /rest/v2/program/{programId}/organization?name=Harvard HTTP/1.1

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": 1421,
        "name": "HARVARD - LAW SCHOOL"
    },
    {
        "id": 1422,
        "name": "HARVARD GRADUATE SCHOOL OF ARTS AND SCIENCES"
    },
    {
        "id": 1423,
        "name": "HARVARD GRADUATE SCHOOL OF EDUCATION"
    },
    {
        "id": 1425,
        "name": "HARVARD SCHOOL OF PUBLIC HEALTH"
    },
    {
        "id": 1426,
        "name": "HARVARD UNIVERSITY"
    }
]
Note: In a prior version of the API, we had a separate /organization/{segment} endpoint that required you to provide the segment type in the request. Now, you need only provide the programId and we will determine the segment type automatically. For backward compatibility, we support the deprecated /organization/student etc. endpoints. If you are using these methods, please migrate to program/{programId}/organization

.

Verify your User

In the above student example, the strings and IDs returned 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.

Request:

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

{
    "firstName": "Jane",
    "lastName": "Ivy",
    "email": "jane@harvard.edu",
    "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": []
}