Get Institution Information

GET /institutions

Enables the retrieval of institution information based upon the query parameters given. This end-point provides a way to synchronize the institution information with the source. This provides access to institution IDs, names, and FICE codes.

Resource URL

https://api.ideasystem.org/v1/institutions

Parameters

page
optional
Default: 0
Example: /v1/institutions?page=1
Used to retrieve more results. Can be incremented until the results returned are less than the max parameter.
max
optional
Default: 100
Example: /v1/institutions?max=10
The max parameter can be used to limit how many results are returned. It is recommended that this value be set as low as possible given the client needs. It is possible, but not advisable, to set the max to 0 which will return all results.
name
optional
 
Example: /v1/institutions?name=IDEA
Filters institutions based upon the name given. This will be treated as a fragment and use it to find institutions that contain the given name. For example, if given "IDEA" it would return both "The IDEA Center" and "IDEA University".
fice
optional
 
Example: /v1/institutions?fice=2233
Filter the institutions that have the matching fice code.

Response

The response will be an HTTP 200 with a JSON body. The body will include a list of institutions that match the given query. It is possible to get an HTTP 200 but 0 total_results; this will happen when the query matches no records.

If there is an issue with the backend, a HTTP 500 (Internal Server Error) is returned. If an error occurs with invalid parameters (e.g, using a String when a boolean is expected), an HTTP 400 (Bad Request) is returned.

Response Parameters (JSON Body)

max
Example: "max": 50
Shows the maximum number of responses.
page
Example: "page": 1
Shows the page number.
total_results
Example: "total_results": 143
Shows the total number of results that are provided by the given query.
data
Example: "data": { ... }
An array of institution objects will be returned in this section. The size of this array should match the total_results.
data.id
Example: "id": 1234
The unique identifier for this institution.
data.fice
Example: "fice": "003919"
The FICE for this institution. This is a unique identifier used in the Higher Education Directory (HED) provided by Higher Education Publications Inc.
data.name
Example: "name": "IDEA University"
The name of the institution.

Example

This request will get all institutions that contain "IDEA" in their name.

Request

GET /v1/institutions?name=IDEA

Response (as JSON)

HTTP 200
{
"max": 10,
"page": 0,
"total_results": 3,
"data": [
    {
        "id": 123,
        "fice": "001032",
        "name": "The IDEA Center"
    },
    {
        "id": 124,
        "fice": "001033",
        "name": "IDEA University"
    },
    {
        "id": 125,
        "fice": "001034",
        "name": "IDEA Community College"
    }]
}