| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| api:api_journal [2021/02/01 08:56] – [Parameters] Lauri | api:api_journal [2024/10/28 11:51] (current) – [List of journal events] Safak |
|---|
| **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.** | **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.) | For example, if you want to copy data to your system once an applicant is given a specific offer type, 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 offer type is the one you're looking for and continue to poll more information about these applicants (documents, application data etc.) |
| | |
| | **This call will only return events from the last 6 months, for performance reasons.** If you need to access older events, please request an exemption from customer support. |
| ==== Syntax ==== | ==== Syntax ==== |
| |
| |
| ^ Name ^ ^ Description ^ Notes ^ | ^ Name ^ ^ Description ^ Notes ^ |
| | ''byEvents'' | Optional | List of journal events you are interested in | [1] | | | ''byEvents'' | **Required** | 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] | | | ''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 [[api:api_academic-years|academic year]] to filter by. | [5] | | | ''byAcademicYear'' | Optional | The [[api:api_academic-years|academic year]] to filter by. | [5] | |
| | ''byAcademicTermID'' | Optional | The [[api:api_academic-terms|academic term]] to filter by. | [5] | | | ''byAcademicTermID'' | Optional | The [[api:api_academic-terms|academic term]] to filter by. | [5] | |
| * // Note [2]: An [[https://en.wikipedia.org/wiki/ISO_8601|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 [2]: An [[https://en.wikipedia.org/wiki/ISO_8601|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 [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 [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. Also note that the ''invoice'' expansion is not available when the API key is limited to an institution.// |
| * // 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. // | * // 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.// |
| |
| |
| ==== List of journal events ==== | ==== List of journal events ==== |
| |
| ^ Event ^ ^ Description | ^ Event ^ Description ^ |
| | |Applicant|| |
| | ''Applicant registered'' | A new applicant account was created | | | ''Applicant registered'' | A new applicant account was created | |
| | ''Applicant was deleted'' | Applicant account was soft-deleted | | | ''Applicant was deleted'' | Applicant account was soft-deleted | |
| | ''Applicant decision: ?'' | Applicant made a decision (accept/reject offer etc.) | | | ''Applicant decision: ?'' | Applicant made a decision (accept/reject offer etc.) | |
| | ''Applicant requested to be forgotten'' | Applicant issued a Right to be Forgotten request | | | ''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 | |
| | |Applicant trackers|| |
| | | ''Tracker was added'' | A marketing tracker was added to an applicant/lead | |
| | | ''Tracker was removed''| A marketing tracker was removed from an applicant/lead | |
| | |Application|| |
| | ''Application was created'' | New application was created (applicant can have several applications) | | | ''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 | | | ''Application was edited'' | Application was saved | |
| | ''Course was added to application'' | Should be self-explanatory | | | ''Course was added to application'' | Should be self-explanatory | |
| | ''Course was removed from application'' | Should be self-explanatory | | | ''Course was removed from application'' | Should be self-explanatory | |
| || | |Application submit|| |
| | ''Application was submitted'' | Application was submitted successfully | | | ''Application was submitted'' | Application was submitted successfully | |
| | ''Application was re-submitted'' | Application was submitted after being reopened previously | | | ''Application was re-submitted'' | Application was submitted after being reopened previously | |
| || | |Application assign|| |
| | | ''Application was assigned'' | Application was assigned to an administrator for handling (manually or via Director) | |
| | | ''Application was un-assigned'' | Application was un-assigned from an administrator | |
| | |Application flags|| |
| | ''Application was flagged'' | A flag was added to the application | | | ''Application was flagged'' | A flag was added to the application | |
| | ''Application was un-flagged'' | A flag was removed 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 reopened'' | Application was reopened for applicant to make changes | |
| | ''Application was silenced'' | Reminders were stopped regarding an application | | | ''Application was silenced'' | Reminders were stopped regarding an application | |
| | ''Application was un-silenced'' | Reminders were re-activated | | | ''Application was un-silenced'' | Reminders were re-activated | |
| | ''Application was migrated'' | Application was migrated to a different year/intake | | |
| | ''Application was frozen'' | Application does not accept further edits by applicant | | | ''Application was frozen'' | Application does not accept further edits by applicant | |
| | ''Application was defrosted'' | Applicant is again editable for the 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 closed'' | Application was soft-deleted | |
| | ''Application was reverted'' | Application soft-deletion was reverted (undelete) | | | ''Application was reverted'' | Application soft-deletion was reverted (undelete) | |
| | ''Application was marked as inactive'' | Application was not touched for a long time.. | | | ''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 added to an application'' | Referee was added to an application | |
| | ''Referee was removed from an application'' | Referee was removed from an application | | | ''Referee was removed from an application'' | Referee was removed from an application | |
| | ''Document was added to an application'' | Document was added to an application | | |Application sharing|| |
| | ''Document was removed from an application'' | Document was removed from an application | | |
| | ''Media was added to an application'' | A media (direct upload or 3rd party like YouTube, SoundCloud, Vimeo, ..) was added to an application | | |
| | ''Media was removed from an application'' | A media (direct upload or 3rd party like YouTube, SoundCloud, Vimeo, ..) was removed from an application | | |
| || | |
| | ''Application was shared with: ?'' | A share access was issued for an application | | | ''Application was shared with: ?'' | A share access was issued for an application | |
| | ''Application share was revoked'' | A share access was revoked 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 edited: ?'' | Offer contents were changed | |
| | ''Offer was confirmed: ?'' | Offer was sent out | | | ''Offer was confirmed: ?'' | Offer was sent out | |
| || | |Documents|| |
| | ''Document was uploaded'' | A document was uploaded | | | ''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 uploaded'' | A media file was uploaded directly to DreamApply | |
| | ''Media was added'' | A 3rd party media Media (YouTube, SoundCloud, Vimeo, ..) was added | | | ''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 started'' | A video interview was started by applicant | |
| | ''Interview was completed'' | A video interview was completed 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 invited'' | A referee was invited to submit a reference | |
| | ''Referee was reminded'' | A reminder (one and only) was sent to the referee | | | ''Referee was reminded'' | A reminder (one and only) was sent to the referee | |
| | ''Referee committed reference'' | Referee finished the reference for an applicant | | | ''Referee committed reference'' | Referee finished the reference for an applicant | |
| || | |Invoices|| |
| | ''Invoice was issued'' | A new invoice was issued | | | ''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 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) | | | ''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 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 resolved as: ?'' | Task status was changed to a status that is "successful" | |
| |
| 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. | 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. |
| | |
| | If you are interested in a specific event, instead of the wildcard, you can also use the following form: |
| | == API version >= 4 == |
| | ''Offer was confirmed: "28"'' or ''Offer was confirmed: 28'' |
| | == API version <= 3 == |
| | ''Offer was confirmed: "Enrolled"'' |