Versioning and changelog

API versioning

The API version number only increments when backwards-incompatible changes are introduced or when the semantics or structure of data change significantly. For example, adding new data, such as a new field in the application, does not necessarily require a new version, as long as existing clients continue to work without disruption.

Maintaining backward compatibility is a high priority for DreamApply. However, when breaking changes are required, earlier API versions remain available for a limited time to allow clients to migrate.

For details about changes introduced in each version, see the Changelog.

Supported API versions

Specify an API version

To use a specific API version, include the version number in the request URI:

GET /api/v3/applicants/123/photo

If the version number is omitted, the latest API version is used:

GET /api/applicants/123/photo

Query an API version

To retrieve the current API version, send the following request:

GET /api/version

Implications of using API versions

If a certain query is no longer available in the latest API version, the request will return an error. For example, if GET /api/something is removed in favour of a different endpoint, subsequent requests to that endpoint will return an error. To continue using a legacy query, you must specify the last API version in which the query was available, for example: GET /api/v2/something.

In a similar manner, if you specify an earlier version and attempt to use a query that was introduced in a later version, the request will return an error.

We recommend always prefixing your queries with the current API version. This guarantees a stable and predictable API interface. You can increase the version number to access new features or continue using an earlier version if needed. If you omit the version, you are on the “bleeding edge”. This might be good for testing, but before you go live, please stabilize the interface on your part.

Version sunsetting policy

If an API version is scheduled for discontinuation, DreamApply will notify you in advance. API versions are supported for a minimum of 180 days following the release of a new major version. We guarantee a minimum of 180 days notice before any API version is officially discontinued (sunset date). All notifications will follow the formal procedures outlined in the DreamApply Terms of Service.

Changelog

Version 9

DreamApply has standardized the representation of several commonly used data fields across the system:

• Dates and datetime: Dates are now returned as single-value strings, replacing structured objects and the legacy MySQL format previously used in applications and tableviews.
• Language and country codes: Country and language values in tableviews are now provided using the ISO alpha-2 format.
• Extra fields: Each extra field or custom section is now represented as a dedicated object that includes a unique ID.

Version 8

Starting with this version, any empty repeating sections (education, languages, career, activities, residences) in the application data will be omitted. Previously an empty array [] was emitted.

Version 7

No incompatible changes are expected in this API version. This version was reserved out of abundance of caution, in case of unexpected compatibility issues resulting from an internal refactor.

Version 6

This version brings changes to the notes related API requests, 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 request 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 PUT /api/applicants/ID/notes and PUT /api/applications/ID/offers/ID/notes requests have been discontinued. Use the POST verb instead for the same functionality of creating a new note:

  • POST /api/applicants/ID/notes
  • POST /api/applications/ID/offers/ID/notes

  For backwards compatibility, the PATCH verb is also supported, but is deprecated.

• The GET /api/applicants/ID/notes and GET /api/applications/ID/offers/ID/notes requests now return a proper collection of notes, instead of the concatenated string.

Version 5

• The GET /api/applicants/ID/documents request has been discontinued, replaced by GET /api/applications/ID/documents.
• The GET /api/applicants/ID/documents/ID request has been discontinued, replaced by GET /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/applications/offers/types request has a different output if version 4 or above is specified — mapped by ID rather than the name.
• A new GET /api/applications/offers/types/ID request has been implemented, only accessible if using version 4 or above.
• The GET /api/applications/ID/offers request 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/applications/ID/offers/ID/type request 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/journal request 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.