Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
api:api_applications [2015/02/12 16:45]
Lauri Elevant [Response example]
api:api_applications [2021/01/21 12:51] (current)
Line 5: Line 5:
 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).  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 16384 items returned, which is capped to 512 if the ''expand'' parameter is used.
 ==== Syntax ==== ==== Syntax ====
  
Line 14: Line 15:
  
 ^ Name ^  ^ Description ^ Notes ^ ^ Name ^  ^ Description ^ Notes ^
-| ''byCommenceYear'' | **Required** | Year number, for example "2015"Default: current calendar year number | |+| ''byAcademicTermID'' | **Required** \\ (either one) | The [[api:api_academic-terms|academic term]] to filter by.  | | 
 +| ''byAcademicYear'' | ::: | The [[api:api_academic-years|academic year]] to filter by. | | 
 +| ''byAcademicYears'' | ::: | The [[api:api_academic-years|academic years]] to filter by. | | 
 +| ''byCommenceYear'' | <del>Deprecated</del> | Year number, for example "2015"Please use academic year or term now. | |
 | ''byApplicantIDs'' | Optional | List of [[api:api_applicants|applicant IDs]]. An application will match if it belongs to one of the listed applicants. | [1] | | ''byApplicantIDs'' | Optional | List of [[api:api_applicants|applicant IDs]]. An application will match if it belongs to one of the listed applicants. | [1] |
 | ''byStatuses'' | Optional | List of [[api:api_applications_statuses|application statuses]]. | [1] | | ''byStatuses'' | Optional | List of [[api:api_applications_statuses|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 [[api:api_courses|course IDs]]. An application will match if it contains at least one of the listed courses. | [1] | | ''byCourseIDs'' | Optional | List of [[api:api_courses|course IDs]]. An application will match if it contains at least one of the listed courses. | [1] |
 | ''byCourseTypes'' | Optional | List of [[api:api_classificators|course types]]. An application will match if it contains at least one course of the listed types. | [1] | | ''byCourseTypes'' | Optional | List of [[api:api_classificators|course types]]. An application will match if it contains at least one course of the listed types. | [1] |
Line 25: Line 32:
 | ''byOfferInstitutionIDs'' | Optional | List of [[api:api_institutions|institution IDs]]. An application will match if it contains at least one offer from the listed institutions. | [1] | | ''byOfferInstitutionIDs'' | Optional | List of [[api:api_institutions|institution IDs]]. An application will match if it contains at least one offer from the listed institutions. | [1] |
 | ''byFlagIDs'' | Optional | List of [[api:api_applications_flags|flag IDs]] | [1] [3] | | ''byFlagIDs'' | Optional | List of [[api:api_applications_flags|flag IDs]] | [1] [3] |
 +| ''limit'' | Optional | How many applications to return (Allowed range is normally 1..16384, 16384 being the default). If the ''expand'' parameter is used, the limit is 512. | |
 +| ''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 [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 [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 [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 ==== ==== Response headers ====
  
Line 45: Line 54:
         "submitted": null,         "submitted": null,
         "status": "Submitted",         "status": "Submitted",
-        "commence_year": "2013",+        "academic_term": "/api/academic-terms/321",
         "applicant": "/api/applicants/16",         "applicant": "/api/applicants/16",
         "flags": "/api/applications/16/flags",         "flags": "/api/applications/16/flags",