This is an old revision of the document!


/api/journal

HEAD, GET

List journal events from the system using the filters set as parameters. The number of journal events matching the search options is represented in the X-Count header - use the HEAD request to simply check if anything interesting has happened in the system. Use the GET request to actually fetch the events and follow them up on.

This is an important API call, as in many cases you may want to pull some information from DreamApply to your systems. In order to know when something interesting has happened in the system, just poll this API call regularly, each time saving the logged timestamp or the incremental ID of the last request. For next requests, use the stored timestamp or ID for the bySince param. For example if your last processed event was 123 (as in the example below), your next call might be ?bySince=124, in order to return rows starting from 124 (inclusive. This will skip all events up to and including 123.

For example, if you want to copy data to your system once an applicant's offer is Enrolled, simply poll for the Offer was edited: ? event. This event is logged each time an offer is edited. If you go over the list of events received, you can easily pick out the ones where the status is Enrolled and continue to poll more information about these applicants (documents, application data etc.)

Syntax

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

Parameters

Name Description Notes
byEvents Optional List of journal events you are interested in [1]
bySince Optional An ISO datetime or the (sequential) ID from which you want to start searching from [2]
byUntil Optional An ISO datetime or the (sequential) ID of the last even you wish to receive [2]
byAcademicYear Optional The academic year to filter by. [5]
byAcademicTermID Optional The academic term to filter by. [5]
order Optional Specifies the order in which the results are returned. Legal values are “newest-first” and “oldest-first” (default).
If an illegal value is provided, the default will be applied silently.
[3]
limit Optional How many journal events to return (Allowed range is normally 1..1024, 1024 being the default).
If the expand parameter is used, the limit is 512. If the limit is exceeded, it is silently capped.
[3]
expand Optional Expand the chosen relational element(s), for example applicant,offer [4]
  • Note [1]: See the list of journal events below. The list must be comma-separated. All list items are combined with logical OR operators - in other words a journal event is considered matching if it matches to any of the values provided in the list.
  • Note [2]: An ISO 8601 compatible datetime (inclusive) or the journal event ID to start from (inclusive). The event ID-s are sequential integers, so you can simply save the last one you processed, and issue the next call with bySince=$lastID+1
  • Note [3]: For backwards compatibility reasons, the default order/limit are set to “oldest-first” and 1024, respectively. In many cases, for example when polling for new events, it makes sense to fetch the last 10 items. In this case, set “order” to “newest-first” and “limit” to 10.
  • 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,application,course,institution,invoice,offer,document,flag,tracker. 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.
  • Note [5]: Some events are not associated with any applications and these filters are thus unavailable. If you choose an incompatible event while also setting the byAcademicTermID or byAcademicYear filter, an error will be returned.

Response headers

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

Response codes

400 Bad Request One of the filters has bad parameters (see error description)

Ordering of the results

The returned journal events are ordered chronologically, so that the oldest events come first and the most recent event is last. The order is guaranteed even if the events happened in the same second.

:!: There is also a hard limit of maximum 1024 records returned as the number of journal events can be very large indeed. If you receive 1024 records, it is most likely being limited.

Response example

{
  "123": {
      "logged": "2014-06-20T08:13:41+00:00",
      "event": "Application was created",
      "bind": [],
      "applicant": "/api/applicants/123",
      "application": "/api/applications/321"
  }
}

List of journal events

Event Description
Applicant related events
Applicant registered A new applicant account was created
Applicant was deleted Applicant account was soft-deleted
Applicant decision: ? Applicant made a decision (accept/reject offer etc.)
Applicant requested to be forgotten Applicant issued a Right to be Forgotten request
Applicant email was changed Applicant contact email was changed (applicant themself or by an admin)
Applicant was transferred to another DreamID identity This can be carried out by ad administrator to restore applicant access
Application related events
Application was created New application was created (applicant can have several applications)
Application was created by cloning New application was created by cloning another application
Application was edited Application was saved
Course was added to application Should be self-explanatory
Course was removed from application Should be self-explanatory
Application submit
Application was submitted Application was assigned to an administrator for handling (manually or via Director)
Application was re-submitted Application was un-assigned from an administrator
Application assign
Application was assigned A flag was added to the application
Application was un-assigned A flag was removed to the application
Application flags
Application was flagged A flag was added to the application
Application was un-flagged A flag was removed to the application
Application management
Application was reopened Application was reopened for applicant to make changes
Application was silenced Reminders were stopped regarding an application
Application was un-silenced Reminders were re-activated
Application was frozen Application does not accept further edits by applicant
Application was defrosted Applicant is again editable for the applicant
Application was migrated Application was migrated to a different year/intake
Application was withdrawn Application was withdrawn by the applicant
Application was closed Application was soft-deleted
Application was reverted Application soft-deletion was reverted (undelete)
Application was marked as inactive Application was not touched for a long time..
Application references
Referee was added to an application Referee was added to an application
Referee was removed from an application Referee was removed from an application
Application sharing
Application was shared with: ? A share access was issued for an application
Application share was revoked A share access was revoked for an application
Offers and replies
Offer was edited: ? Offer contents were changed
Offer was confirmed: ? Offer was sent out
Documents
Document was uploaded A document was uploaded
Document was uploaded to a task A document was uploaded to a checklist task
Media files
Media was uploaded A media file was uploaded directly to DreamApply
Media was added A 3rd party media Media (YouTube, SoundCloud, Vimeo, ..) was added
Media was removed A 3rd party media Media (YouTube, SoundCloud, Vimeo, ..) was removed
Interviews
Interview was started A video interview was started by applicant
Interview was completed A video interview was completed by applicant
Interview was evaluated A video interview was evaluated by administrator
References
Referee was invited A referee was invited to submit a reference
Referee was reminded A reminder (one and only) was sent to the referee
Referee committed reference Referee finished the reference for an applicant
Invoices
Invoice was issued A new invoice was issued (the first “Save” operation)
Invoice was edited An invoice was edited (the subsequent “Save” operations)
Invoice was deleted An invoice was deleted
Invoice was reminded A payment reminder was sent in relation to an invoice
Invoice was marked as paid Funds were collected regarding an invoice (may be partially collected)
Tasks
Task was committed as: ? Task status was changed but not yet resolved
Task was resolved as: ? Task status was changed to a status that is “successful”
Task was commented Comments field was changed on a task

In some events, the name contains wildcards in the form of a question mark ?. This is used to “group” some very similar events together, in cases where the only differentiating factor is the status that something was set to etc.

You can also use the form Offer was confirmed: “Enrolled” if you are interested in a specific event, instead of the wildcard.