| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| api:api_journal [2023/09/25 16:27] – [List of journal events] Lauri Elevant | api:api_journal [2024/02/15 10:11] (current) – [Parameters] Lauri Elevant |
|---|
| **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] | | | ''byUntil'' | Optional | An ISO datetime or the (sequential) ID of the last even you wish to receive | [2] | |
| * // 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.// |
| |
| |
| |
| ^ Event ^ Description ^ | ^ Event ^ Description ^ |
| |Applicant related events|| | |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 email was changed'' | Applicant contact email was changed (applicant themself or by an admin) | | | ''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 was transferred to another DreamID identity'' | This can be carried out by ad administrator to restore applicant access | |
| |Application related events|| | |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 created by cloning'' | New application was created by cloning another application | |
| 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. |
| |
| You can also use the form ''Offer was confirmed: "Enrolled"'' if you are interested in a specific event, instead of the wildcard. | 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"'' |