Differences

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

--- api:manual [2019/02/25 12:41] – Links to scoresheet calls Anton
+++ api:manual [2025/06/09 13:45] (current) – Lauri
@@ Line 38: / Line 38: @@
 That's it! We derive most of the security mechanism from the use of HTTPS, most notably confidentiality (of the API key as well as the data sent and received), integrity (data cannot be altered while "in transit") and mitigation against man-in-the-middle and re-play attacks.
+Here is a quick way to make your first API request:
+  curl -v -X GET -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" https://apply.uni.edu/api/institutions
+On the request above, ''apply.uni.edu'' is the domain for your DreamApply installation. It may also be in the form of "your-uni.dreamapply.com" if you have not yet configured the domain in DreamApply settings. Tip - you can add ''| python -m json.tool'' to the end of the command if you expect to receive JSON data (not all API queries return JSON) to prettify the output.
 ===== Versioning =====
 The API version number will only incremented if backwards-incompatible changes have been introduced or in case if the semantics or data structure has been sufficiently changed to warrant a new version number. If, for example, some new data have been made available (a new field in the application, perhaps) the version number is not necessarily incremented as long as a client not aware of the changes is not disrupted. Backwards compatibility remains a high priority, but if it has to be broken, the previous API version will remain available (but not indefinitely).
-By default, the latest version of the API is used for all requests. If you would like to use a specific API version for your queries, use the following syntax:
+Please also review the changelog below for changes in each API version.
+Currently supported API versions:
+^ Version  ^ Status  ^
+| 1 | Deprecated  |
+| 2 | Deprecated  |
+| 3 | Supported (default *) |
+| 4 | Supported |
+| 5 | Supported |
+| 6 | Supported (latest, recommended) |
+* By default, version 3 of the API is used for all requests.
+If you would like to use a specific API version for your queries, use the following syntax:
-  GET /api/v2/applicants/123/photo
+  GET /api/v3/applicants/123/photo
 If the version number is omitted, the latest version of the API is used:
@@ Line 51: / Line 69: @@
   GET /api/applicants/123/photo
-Implications of using the latest version. Simply put, it means that if a certain query is no longer available in the latest version of the API, you will receive an error. The version number literally means the **version of the API, not version of a particular API query**. For example, if ''GET /api/something'' is removed (in favour of something else, perhaps) then all subsequent requests will return an error. To use such a legacy query, you would need to specify the last version of the API where the query still existed, like so: ''GET /api/v9/something''. Similarly, any queries that were not yet available in a certain specified version, will return an error.
+Implications of using the latest version. Simply put, it means that if a certain query is no longer available in the latest version of the API, you will receive an error. The version number literally means the **version of the API, not version of a particular API query**. For example, if ''GET /api/something'' is removed (in favour of something else, perhaps) then all subsequent requests will return an error. To use such a legacy query, you would need to specify the last version of the API where the query still existed, like so: ''GET /api/v2/something''. Similarly, any queries that were not yet available in a certain specified version, will return an error.
 **So summarise, we would recommend always prefixing all of your queries with the current API version.** This guarantees a stable interface. You may always increment the version number to "unlock" new features or go back to a previous version if you prefer. But do not expect the API to do anything "magical". The version number you specify defines the interface. If you fail to do so, you are on the "bleeding edge". This might be good for testing, but before you go live, please stabilise the interface on your part.
@@ Line 116: / Line 134: @@
 | [[api:/api/applicants/ID/emails|/api/applicants/ID/emails]] | C | GET HEAD | Get a list of emails that are sent to an applicant |
 | [[api:/api/applicants/ID/emails/ID|/api/applicants/ID/emails/ID]] | A | GET HEAD | Get information about a specific emails sent to an applicant |
+| [[api:/api/applicants/ID/emails/ID/attachments|/api/applicants/ID/emails/ID/attachments]] | C | GET HEAD | Get a list of attachments of an email |
+| [[api:/api/applicants/ID/emails/ID/attachments/ID|/api/applicants/ID/emails/ID/attachments/ID]] | A | GET HEAD | Download a specific attachment (binary data) |
 | [[api:/api/applicants/ID/trackers|/api/applicants/ID/trackers]] | C | GET HEAD | Get a list of tracker associations |
 | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | GET HEAD | Get information about a specific tracker set on an applicant |
 | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | PUT | Set a tracker code to the applicant in question |
 | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | DELETE | Remove the tracker code from the applicant in question |
-| [[api:/api/applicants/ID/documents|/api/applicants/ID/documents]] | C | GET HEAD | Get a list of documents for the applicant in question |
-| [[api:/api/applicants/ID/documents/ID|/api/applicants/ID/documents/ID]] | R | GET HEAD | Get a specific applicant document (binary data) |
-| [[api:/api/applicants/ID/studyplans|/api/applicants/ID/studyplans]] | C | GET HEAD | Get a list of study plans created by this applicant |
-| [[api:/api/applicants/ID/studyplans/ID|/api/applicants/ID/studyplans/ID]] | R | GET HEAD | Get a specific study plan created by this applicant |
 | [[api:/api/applicants/ID/invoices|/api/applicants/ID/invoices]] | C | GET HEAD | List invoices for this applicant |
 | [[api:/api/applicants/ID/invoices/ID|/api/applicants/ID/invoices/ID]] | R | GET HEAD | Get information about an applicant invoice  |
@@ Line 130: / Line 146: @@
 | [[api:/api/applicants/ID/applications|/api/applicants/ID/applications]] | C | GET HEAD | List applications for this applicant |
 | [[api:/api/applicants/ID/applications/ID|/api/applicants/ID/applications/ID]] | R | GET HEAD | Get information about an applicant application |
+| [[api:/api/applicants/ID/reference|/api/applicants/ID/reference]] | R | GET HEAD | Get the reference code for this applicant |
+| [[api:/api/applicants/ID/reference|/api/applicants/ID/reference]] | R | PUT | Store a new reference code for this applicant |
+| [[api:/api/applicants/ID/matriculation|/api/applicants/ID/matriculation]] | R | GET HEAD | Get the matriculation number for this applicant |
+| [[api:/api/applicants/ID/matriculation|/api/applicants/ID/matriculation]] | R | PUT | Store a new matriculation number for this applicant |
 | [[api:/api/applicants/consents|/api/applicants/consents]] | C | GET HEAD | Get a list of all consents |
 | [[api:/api/applicants/consents/ID|/api/applicants/consents/ID]] | R | GET HEAD | Get information about a specific consent |
@@ Line 136: / Line 156: @@
 | [[api:/api/applicants/trackers/ID|/api/applicants/trackers/ID]] | R | GET HEAD | Get information about a specific tracker |
 | [[api:/api/applicants/trackers/ID|/api/applicants/trackers/ID]] | R | DELETE | Delete a tracker, removing it from all applicants |
+| [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]] | R | GET HEAD | Get the notes on the applicant |
+| [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]] | R | POST | Create a new applicant note |
+| [[api:/api/applicants/ID/notes/ID|/api/applicants/ID/notes/ID]] | R | GET HEAD | Get information about a specific applicant note |
+| [[api:/api/applicants/ID/notes/ID|/api/applicants/ID/notes/ID]] | R | PUT | Update a specific applicant note |
 | [[api:/api/applications|/api/applications]] | C | GET HEAD | Get a list of applications that match the set filtering criterion  |
 | [[api:/api/applications/ID|/api/applications/ID]] | R | GET HEAD | Get the application contents (data input by the application).  |
@@ Line 148: / Line 172: @@
 | [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]] | R | GET HEAD | Get the offer type of a specific application offer |
 | [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]] | R | PUT | Set the offer type of the application offer in question |
+| [[api:/api/applications/ID/offers/ID/subject|/api/applications/ID/offers/ID/subject]] | R | GET HEAD | Get the subject line of a specific application offer |
+| [[api:/api/applications/ID/offers/ID/subject|/api/applications/ID/offers/ID/subject]] | R | PUT | Set the subject line of the application offer in question |
+| [[api:/api/applications/ID/offers/ID/comments|/api/applications/ID/offers/ID/comments]] | R | GET HEAD | Get the offer letter text/comments of a specific application offer |
+| [[api:/api/applications/ID/offers/ID/comments|/api/applications/ID/offers/ID/comments]] | R | PUT | Set the offer letter text/comments of the application offer in question |
+| [[api:/api/applications/ID/offers/ID/attachments|/api/applications/ID/offers/ID/attachments]] | R | GET HEAD | Get the offer attachments |
+| [[api:/api/applications/ID/offers/ID/attachments/ID|/api/applications/ID/offers/ID/attachments/ID]] | R | GET HEAD | Get an offer attachment |
+| [[api:/api/applications/ID/offers/ID/attachments/ID/download|/api/applications/ID/offers/ID/attachments/ID/download]] | R | GET HEAD | Get an offer attachment (the binary blob) |
+| [[api:/api/applications/ID/offers/ID/letters|/api/applications/ID/offers/ID/letters]] | R | GET HEAD | Get the offer letters |
+| [[api:/api/applications/ID/offers/ID/letters/ID|/api/applications/ID/offers/ID/letters/ID]] | R | GET HEAD | Get an offer letter |
+| [[api:/api/applications/ID/offers/ID/confirm|/api/applications/ID/offers/ID/confirm]] | R | POST | Confirm an offer |
+| [[api:/api/applications/ID/offers/ID/decision|/api/applications/ID/offers/ID/decision]] | R | GET HEAD | Get the decision of a specific application offer |
+| [[api:/api/applications/ID/offers/ID/decision|/api/applications/ID/offers/ID/decision]] | R | PUT | Set the decision of the application offer in question |
+| [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]] | R | GET HEAD | Get the notes on the offer |
+| [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]] | R | POST | Create a new offer note |
+| [[api:/api/applications/ID/offers/ID/notes/ID|/api/applications/ID/offers/ID/notes/ID]] | R | GET HEAD | Get information about a specific offer note |
+| [[api:/api/applications/ID/offers/ID/notes/ID|/api/applications/ID/offers/ID/notes/ID]] | R | PUT | Update a specific offer note |
 | [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | GET HEAD | Get the extra score of a specific application offer |
 | [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | PUT | Set the extra score of the application offer in question |
@@ Line 155: / Line 195: @@
 | [[api:/api/applications/ID/tasks/ID/status|/api/applications/ID/tasks/ID/status]] | R | GET HEAD | Get the status of a specific application task |
 | [[api:/api/applications/ID/tasks/ID/status|/api/applications/ID/tasks/ID/status]] | R | PUT | Set the status to the application task in question |
+| [[api:/api/applications/ID/tasks/ID/documents|/api/applications/ID/tasks/ID/documents]] | C | GET HEAD | Get a list of documents attached to this task |
+| [[api:/api/applications/ID/tasks/ID/documents|/api/applications/ID/tasks/ID/documents]] | C | POST | Upload a new document to this task |
+| [[api:/api/applications/ID/tasks/ID/documents/ID|/api/applications/ID/tasks/ID/documents/ID]] | R | GET HEAD | Get a specific document from this task (binary data) |
 | [[api:/api/applications/ID/exports|/api/applications/ID/exports]] | C | GET HEAD | List all exports that have been generated from the application in question |
 | [[api:/api/applications/ID/exports/ID|/api/applications/ID/exports/ID]] | R | GET HEAD | Fetch a specific application export identified by the export ID |
@@ Line 160: / Line 203: @@
 | [[api:/api/applications/ID/exports/ID/blobs/blob|/api/applications/ID/exports/ID/blobs/blob]] | R | GET HEAD | Retrieve a downloadable file (blob) regarding this export |
 | [[api:/api/applications/ID/documents|/api/applications/ID/documents]] | C | GET HEAD | Get a list of documents attached to this application |
+| [[api:/api/applications/ID/documents|/api/applications/ID/documents]] | C | POST | Upload a new document to this application |
 | [[api:/api/applications/ID/documents/ID|/api/applications/ID/documents/ID]] | R | GET HEAD | Get a specific applicant document (binary data) |
-| [[api:/api/applications/ID/studyplans|/api/applications/ID/studyplans]] | C | GET HEAD | Get a list of study plans attached to this application |
+| [[api:/api/applications/ID/scores|/api/applications/ID/scores]] | C | GET HEAD | Get a list of scores for this application |
-| [[api:/api/applications/ID/studyplans/ID|/api/applications/ID/studyplans/ID]] | R | GET HEAD | Get a specific study plan attached to this application |
+| [[api:/api/applications/ID/pdf|/api/applications/ID/pdf]] | C | GET HEAD | Get The PDF printout of this application |
+| [[api:/api/applications/ID/invoices|/api/applications/ID/invoices]] | C | GET HEAD | List invoices for this application |
+| [[api:/api/applications/ID/invoices|/api/applications/ID/invoices]] | C | POST | Create an invoice for this application |
+| [[api:/api/applications/ID/invoices/ID|/api/applications/ID/invoices/ID]] | R | GET HEAD | Get information about an application invoice  |
 | [[api:/api/applications/flags|/api/applications/flags]] | C | GET HEAD | Get a list of all flags |
 | [[api:/api/applications/flags|/api/applications/flags]] | C | POST | Create a new flag  |
@@ Line 173: / Line 220: @@
 | [[api:/api/institutions/ID/departments|/api/institutions/ID/departments]] | C | GET HEAD | List departments under the given institution |
 | [[api:/api/institutions/ID/departments/ID|/api/institutions/ID/departments/ID]] | R | GET HEAD | Show information about a given institution department |
-| [[api:/api/institutions/ID/contacts|/api/institutions/ID/contacts]] | C | GET HEAD | List contact persons under the given institution |
-| [[api:/api/institutions/ID/contacts/ID|/api/institutions/ID/contacts/ID]] | R | GET HEAD | Show information about a given institution contact person |
 | [[api:/api/courses|/api/courses]] | C | GET HEAD | List courses using filters set as parameters |
+| [[api:/api/courses|/api/courses]] | C | POST | Create a new blank course |
 | [[api:/api/courses/ID|/api/courses/ID]] | R | GET HEAD | More detailed information about a specific course |
 | [[api:/api/intakes|/api/intakes]] | R | GET HEAD | List configured intakes |
 | [[api:/api/intakes/ID|/api/intakes/ID]] | R | GET HEAD | Get details of a specific intake |
 | [[api:/api/invoices|/api/invoices]] | C | GET HEAD | List all issued invoices |
-| [[api:/api/invoices/ID|/api/invoices/ID]] | R | GET HEAD | Get more information about an invoices |
+| [[api:/api/invoices/ID|/api/invoices/ID]] | R | GET HEAD | Get more information about an invoice |
 | [[api:/api/invoices/ID|/api/invoices/ID]] | R | DELETE | Delete an invoice |
+| [[api:/api/invoices/ID/transactions|/api/invoices/ID/transactions]] | C | GET HEAD | List transactions of a specific invoice |
+| [[api:/api/invoices/ID/transactions|/api/invoices/ID/transactions]] | C | POST | Create transaction for invoice ("collect invoice") |
+| [[api:/api/invoices/ID/transactions/ID|/api/invoices/ID/transactions/ID]] | R | GET HEAD | Get more information about a transaction |
 | [[api:/api/invoices/series|/api/invoices/series]] | R | GET HEAD | List invoice series |
+| [[api:/api/invoices/transactions|/api/invoices/transactions]] | C | GET HEAD | List transactions |
+| [[api:/api/invoices/transactions/ID|/api/invoices/transactions/ID]] | R | GET HEAD | Get more information about a transaction |
 | [[api:/api/academic-terms|/api/academic-terms]] | R | GET HEAD | Get a list of all academic terms configured |
 | [[api:/api/academic-terms/ID|/api/academic-terms/ID]] | R | GET HEAD | Get information about an academic term |
@@ Line 194: / Line 245: @@
 | [[api:/api/scoresheets|/api/scoresheets]] | C | GET HEAD | List all scoresheets |
 | [[api:/api/scoresheets/ID|/api/scoresheets/ID]] | R | GET HEAD | Get info about scoresheet |
-| [[api:/api/scoresheets/ID/scores|/api/scoresheets/ID/scores]] | R | GET HEAD | Get scores |
+| [[api:/api/scoresheets/ID/scores|/api/scoresheets/ID/scores]] | C | GET HEAD | Get scores |
+| [[api:/api/scoresheets/ID/scores|/api/scoresheets/ID/scores]] | C | POST | Append an application for scoring |
+| [[api:/api/scoresheets/ID/scores/ID|/api/scoresheets/ID/scores/ID]] | R | GET HEAD | Get information about a score |
+| [[api:/api/scoresheets/ID/scores/ID/points|/api/scoresheets/ID/scores/ID/points]] | R | GET HEAD | Get the points of a scoresheet score |
+| [[api:/api/scoresheets/ID/scores/ID/points|/api/scoresheets/ID/scores/ID/points]] | R | PUT | Set the points of a scoresheet score |
+| [[api:/api/scoresheets/ID/scores/ID/points|/api/scoresheets/ID/scores/ID/points]] | R | DELETE | Clear the points of a scoresheet score |
+| [[api:/api/scoresheets/ID/scores/ID/comments|/api/scoresheets/ID/scores/ID/comments]] | R | GET HEAD | Get the comments of a scoresheet score |
+| [[api:/api/scoresheets/ID/scores/ID/comments|/api/scoresheets/ID/scores/ID/comments]] | R | PUT | Set the comments of a scoresheet score |
+| [[api:/api/scoresheets/ID/scores/ID/comments|/api/scoresheets/ID/scores/ID/comments]] | R | DELETE | Clear the comments of a scoresheet score |
 | [[api:/api/tableviews|/api/tableviews]] | C | GET HEAD | List all tableviews created with the GUI |
 | [[api:/api/tableviews/ID|/api/tableviews/ID]] | R | GET HEAD | Get more information about a tableview |
@@ Line 200: / Line 259: @@
 | [[api:/api/administrators|/api/administrators]] | R | GET HEAD | List all administrators in the system |
 | [[api:/api/administrators/ID|/api/administrators/ID]] | R | GET HEAD | Get information about an administrator |
+| [[api:/api/ping|/api/ping]] | R | GET HEAD | A dummy call for testing authentication |
 ♦ The types are as follows: **C**ollection, **R**esource, **A**ssociation. The latter is an object that represents the relationship between two resources. It is used on one-to-many and many-to-many relationships. However, an association between an applicant and a tracker may carry some information itself, such as the time the association was established. Thus is a special kind of resource.
@@ Line 221: / Line 281: @@
 * Note that if you issue multiple ''DELETE'' requests for the same resource, you will receive this error on any subsequent requests.
 ===== Throttling  =====
-All API calls placed to the same API key are, by default, limited to **60 queries per minute** and **600 queries per hour**. Please note that 60 queries/minute is not the same as 1 query per second, see below.
+All API calls placed to the same API key are, by default, limited to **180 queries per minute** and **600 queries per hour**. Please note that 60 queries/minute is not the same as 1 query per second, see below.
 If you exceed your API key queries-per-minute quota, you may start to receive ''429 Too Many Requests'' responses. This means that the request was **not** processed and will have to be issued again.
@@ Line 231: / Line 292: @@
 We also use other methods to monitor the amount of resources consumed with a specific API key and will notify you in case we find anything in your usage patterns that seems unreasonable or seems to constitute a bug on your part.
+===== Changelog  =====
+==== Version 6 ====
+This version brings changes to the notes related API calls, related to the change made to the applicant and offer notes system. Previously, applicant and offer cards had a single large "Notes" field. It has since been expanded to be able to create multiple notes (with different colours). For backwards compatibility reasons, the API usage still remained the same up until API version 5 . For example, the ''GET /api/applicants/ID/notes'' call returns a single string concatenating all the notes together as it still remains a single big notes field. Starting from API version 6, the API semantics reflect the true nature of the notes system.
+  * The calls ''PUT /api/applicants/ID/notes'' and ''PUT /api/applications/ID/offers/ID/notes'' have been discontinued. Use the POST verb instead for the same functionality of creating a new note:  ''POST [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]]'' or ''POST [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]]''. For backwards compatibility, the PATCH verb is also supported, but is deprecated.
+  * The calls ''GET [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]]'' and ''GET [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]]'' now return a proper collection of notes, instead of the concatenated string.
+==== Version 5 ====
+  * Discontinued the ''GET /api/applicants/ID/documents'' call, replaced by ''GET [[api:/api/applications/ID/documents|/api/applications/ID/documents]]''
+  * Discontinued the ''GET /api/applicants/ID/documents/ID'' call, replaced by ''GET [[api:/api/applications/ID/documents/ID|/api/applications/ID/documents/ID]]''
+==== Version 4 ====
+Offer types are now referenced by an ID (such as ''123''), rather than a name (such as ''Accepted''), related to the introduction of fully customisable offer types. This includes the following changes:
+  * The ''GET [[api:/api/applications/offers/types|/api/applications/offers/types]]'' has a different output if version 4 or above is specified - mapped by ID rather than the name.
+  * A new ''GET [[api:/api/applications/offers/types/ID|/api/applications/offers/types/ID]]'' call has been implemented, only accessible if using version 4 or above
+  * The ''GET [[api:/api/applications/ID/offers|/api/applications/ID/offers]]'' call will return the full resource path (such as ''/api/applications/offers/types/123'') for the ''type'' and ''type-confirmed'' fields. Before version 4, these fields contained the name of the offer type, such as ''Accepted''.
+  * The ''GET [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]]'' call l will return the full resource path (such as ''/api/applications/offers/types/123'') in the response. Before version 4, the response referred to the currently set offer type using the offer type name, such as ''Accepted''.
+  * The ''GET [[api:/api/journal|/api/journal]]'' call now expects in the ''byEvents'' parameter to specify the ''Offer was edited: ?'' and ''Offer was confirmed: ?'' events using a numeric offer type ID, rather than a name, for example ''Offer was edited: 123''