This is an old revision of the document!

/api/applications

HEAD, GET

Retrieve a list of applications that match the set filtering criterion. As per norm, the HEAD verb is useful to just test if such an application exist (and how many).

There is a hard limit of 8192 items returned, which is capped to 256 if the expand parameter is used.

Syntax

GET /api/applications
Host: apply.example.edu
Authorization: DREAM apikey="..."

Parameters

Name		Description	Notes
`byAcademicTermID`	Required (either one)	The academic term to filter by.
`byAcademicYear`	Required (either one)	The academic year to filter by.
`byCommenceYear`	~~Deprecated~~	Year number, for example “2015”. Please use academic year or term now.
`byApplicantIDs`	Optional	List of applicant IDs. An application will match if it belongs to one of the listed applicants.	[1]
`byStatuses`	Optional	List of application statuses.	[1]
`byCreatedSince`	Optional	ISO 8601 datetime. Only show applications created after this.
`byRevisedSince`	Optional	ISO 8601 datetime. Only show applications revised after this.
`bySubmittedSince`	Optional	ISO 8601 datetime. Only show applications submitted after this.
`byCourseIDs`	Optional	List of course IDs. An application will match if it contains at least one of the listed courses.	[1]
`byCourseTypes`	Optional	List of course types. An application will match if it contains at least one course of the listed types.	[1]
`byCourseInstitutionIDs`	Optional	List of institution IDs. An application will match if it contains at least one course from the listed institutions.	[1]
`byCourseIntakeIDs`	Optional	List of intake IDs. An application will match if it contains at least one course under the listed intakes.	[1]
`byOfferTypes`	Optional	List of offer types. An application will match if it contains at least one offer of the listed types.	[1] [2]
`byOfferDecisions`	Optional	List of offer decisions.	[1] [2]
`byOfferInstitutionIDs`	Optional	List of institution IDs. An application will match if it contains at least one offer from the listed institutions.	[1]
`byFlagIDs`	Optional	List of flag IDs	[1] [3]
`limit`	Optional	How many applications to return (Allowed range is normally 1..8192, 8192 being the default). If the `expand` parameter is used, the limit is 512. If the amount of filtered records exceeds the limit, an error is returned.
`expand`	Optional	Expand the chosen relational element(s), for example `applicant,offer`	[4]

Note [1]: Lists can be either comma or space separated. All list items are combined with logical OR operators - in other words an application is considered matching if it matches to any of the values in the list.
Note [2]: This limits selection to applications that have been submitted, since offers (initially in “Unreplied” status) will be created while submitting an application. An application may contain any number of courses, but they will be turned into offers only at submission. This also applies to edits made after submission. For example an applicant may add a course after submission, but the corresponding offer will appear only after submission.
Note [3]: Currently only one flag ID can be listed. This limitation will be lifted at a later date.
Note [4]: Some elements in the returned objects are links to other API calls. Using the expand parameter, it is possible to expand this data to the actual records, saving additional API calls. The full list of possible expansions is applicant,flags,courses,offers,documents,studyplans. You can set one or multiple expansions, combining them in a comma-separated fashion to the expand parameter. Note also that using this parameter caps to limit to 512 due to performance reasons.

Response headers

Content-Type: application/json
Content-Length: 1456
X-Count: 15

Response example

{
  "16": {
      "created": "2014-06-20T08:30:19+00:00",
      "revised": "2014-06-20T08:30:19+00:00",
      "submitted": null,
      "status": "Submitted",
      "academic_term": "/api/academic-terms/321",
      "applicant": "/api/applicants/16",
      "flags": "/api/applications/16/flags",
      "courses": "/api/applications/16/courses",
      "offers": "/api/applications/16/offers",
      "exports": "/api/applications/16/exports",
      "documents": "/api/applications/16/documents",
      "studyplans": "/api/applications/16/studyplans"
  }
}