API v1 is being shut down on March 3rd, 2025
We recommend starting your migration from API v1 to API v2 as soon as possible.
We released v2 of our API publicly in November 2023, and have continued to incrementally update it since then. API v2 brings a huge number of improvements compared to v1: it fixes many longstanding bugs and issues, adds new endpoints and properties, and is more performant. We’ve also made it easier to understand and implement, both by using modern API conventions, and simplifying and unifying requests and responses. API v2 is much easier to maintain, monitor, and add new features to, so we hope to add to this list of improvements going forward.
API v2 has been completely rebuilt from the ground up, and contains multiple breaking changes from API v1. While we never like introducing breaking changes if we can help it, they were unfortunately a necessary part of this change. API v1 is currently deprecated, and will be shut down entirely on March 3rd, 2025.
This document provides a starting point for upgrading from API v1 to v2 by outlining some of the major changes that you will need to take into account. We understand that migrating to a completely new version of an API is not an easy task (we’ve been on the other side of this before), but we are committed to providing you with the documentation and support you need to make this transition as easy as possible.
Fundamentals
API v2 is organized around REST. It has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Authentication
Authentication in API v1 took the form of an API token that was passed as part of the query string parameters. In API v2, the same API token should be used, but now must be passed in the Authorization header when making the request (this is known as HTTP bearer Authentication).
Response codes
API v1 almost always returned 200 Ok responses, even when the request resulted in an error, which is highly unusual for an API. That has been fixed in API v2, which means all requests now return the conventional HTTP response codes. This approach makes it easier to determine if an API call succeeded or failed (and why), without needing to parse the response in non-standard ways.
In general (and according to convention), API v2 uses:
2xxcodes to indicate success4xxcodes to indicate an error with the request (e.g., a required parameter was omitted, an object was not found, an unauthorized request, etc.)5xxcodes indicate an error with AddEvent's servers
HTTP Verbs
All endpoints in API v1 exclusively accepted GET requests, even requests to create, update or delete a resource. In API v2, conventional verbs are used for each type of request, as follows:
GETto retrieve a resource, or to search for several resourcesPOSTto create a resourcePATCHto perform a partial update to an existing resourceDELETEto delete a resource
Base URL
The base url of all api requests has been updated from one of the following:
<https://www.addevent.com/api/v1/oe/>...<https://www.addevent.com/api/v1/me/>...
to
<https://api.addevent.com/calevent/v2/>...
Resource ids
API v2 uses new unique ids to identify events. These new event ids are prefixed with evt-. The old event ids that were used in API v1 are not compatible with API v2. The old event ids will not be returned as part of response objects in API v2, and should not be used in request paths.
There are no changes to the unique ids used for any other types of resources i.e. calendar ids, rsvp attendee ids, and calendar subscriber ids all remain unchanged.
Date and time formatting
API v1 accepted a wide range of date and time formats when setting the start or end time of an event, e.g. American style mm/dd/yy, European dd-mm-yyyy, or ISO8601 yyyy-mm-dd, and distinguished between those based on several assumptions e.g. the separator provided. While this may have been useful in some cases, it also added complexity, and often resulted in ambiguity when parsing certain dates. API v2 accepts more limited date and time formats, based on ISO8601. The following formats are accepted:
YYYY-MM-DD hh:mm:sse.g.2023-11-28 10:00:00YYYY-MM-DD hh:mme.g.2023-11-28 10:00YYYY-MM-DDe.g.2023-11-28
Dates and times within a response in API v2 are also always represented as YYYY-MM-DD hh:mm:ss e.g. 2023-11-28 10:00:00. We think that this approach to dates and times is much simpler and more predictable, and will result in fewer issues compared to API v1.
Consolidated endpoints
Many event endpoints were duplicated in API v1. For example, there was both an endpoint to “Create an event”, and another (almost identical) endpoint to “Create an event in a calendar”. In API v2, both of these endpoints have been consolidated into a single endpoint.
Search endpoints
Many of the old “list” endpoints in API v1 have been replaced by “search” endpoints in API v2. For example, “List RSVP attendees for an event” in API v1 is the equivalent to “Search RSVP attendees” in API v2. These new “search” endpoints are much more flexible and easy to use. Instead of retrieving the RSVP attendees for just one event at a time in API v1, with API v2 you can pass in 0, 1, or many event ids and/or 0,1, or many calendar ids to retrieve the RSVP attendees associated with that particular combination of resources.
Search, filter, and sorting parameters have been added across these new search endpoints in API v2 (with more to come) so relevant resources can be retrieved more easily. All search responses include standardized pagination properties to make it easier to understand the number of results and manage the pages that may need to be iterated.
Request bodies
In API v1, properties of resources to be created or updated were passed in as query string parameters. In API v2, these properties are passed in as a JSON-encoded request body instead.
New stuff
Alongside all of the above changes, several new endpoints have been added. Additional resource properties have also been exposed on requests to and responses from existing endpoints. It’s worth reading through the API docs in detail to understand if any of these new endpoints or properties might be relevant for your use case.
The new endpoints that were added to API v2 that were not available in API v1 are
Support
API v2 is comprehensively documented, with sample requests and responses included. If you run into any issues while upgrading, or if you have any questions or concerns, please don’t hesitate to reach out to our support team by using the contact support form on our website or sending an email to [email protected].