Institutions

API version
Select a version to change the base URI
in syntax and code examples. Learn about versions
:

Represents a list of institutions set up for the DreamApply instance.

URI
/api/v9/institutions

API request	Return Type	Verb	Description
`/api/v9/institutions`	C	,	List institutions using filters set as parameters
`/api/v9/institutions/ID`	R	,	Get more detailed information about a specific institution
`/api/v9/institutions/ID/departments`	C	,	List departments under the given institution
`/api/v9/institutions/ID/departments/ID`	R	,	Show information about a given institution department

List institutions

List institutions using the filters set as parameters.

In most use cases there will only be one institution in the system. However, in exchange management setups as well as collaborative systems there may be a larger number of institutions.

Syntax
GET /api/v9/institutions
Host: apply.example.edu
Authorization: DREAM apikey="..."

Parameters

Parameter	Required/Optional	Description	Notes
`byStatuses`	Optional	List of statuses, currently limited to: `Online`, `Draft`	[1]
`byModes`	Optional	`Internal` (DA user) or `External` (not users of DA, partner etc.)	[1]
`byCountries`	Optional	List of ISO 3166-1 alpha-2 country codes	[1]

Notes

Note [1]: Lists can be either comma or space separated. All list items are combined with logical OR operators — in other words an institution is considered matching if it matches to any of the values in the list.

Example request

Request
curl
curl \
  -X GET \
  -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" \
  "https://apply.example.edu/api/v9/institutions?byStatuses=Online"

Response headers

Header	Value	Description
`Content-Type`	`application/json`	Media type of the resource
`Content-Length`	`1234`	Size of the response body in bytes
`X-Count`	`3`	Number of registered institutions

Response codes

Response code	Description
`200 OK`	The list of institutions was successfully returned

Example response

Response
{
  "1": {
    "id": 1,
    "status": "Online",
    "name": "School of Engineering and Technology",
    "country": "BE",
    "location": "Antwerp",
    "www": "https://engtech.edu",
    "erasmus": "BE ANTWERP08",
    "address": "15 De Keyserlei\r\n2000 Antwerp",
    "vat": "BE0471123456",
    "iban": "BE68 5390 0754 7034",
    "registration": null,
    "departments": "/api/v9/institutions/1/departments"
  },
  "2": {
    "id": 2,
    "status": "Online",
    "name": "School of Chemistry",
    "country": "BE",
    "location": "Antwerp",
    "www": "https://dreamapply.com/",
    "erasmus": null,
    "address": "15 De Keyserlei\r\n2000 Antwerp",
    "vat": null,
    "iban": null,
    "registration": null,
    "departments": "/api/v9/institutions/2/departments"
  },
  "3": {
    "id": 3,
    "status": "Online",
    "name": "School of Applied Science",
    "country": "BE",
    "location": "Antwerp",
    "www": "https://dreamapply.com/",
    "erasmus": null,
    "address": "15 De Keyserlei\r\n2000 Antwerp",
    "vat": null,
    "iban": null,
    "registration": null,
    "departments": "/api/v9/institutions/3/departments"
  }
}

Applications

Institution