API Upgrades

Keep track of changes and upgrades to the Falu API

The version of Falu API in use controls the API and webhook behavior seen (for example, response properties and the parameters that can be sent in requests). The version gets set the first time an API request is made. When a breaking change is introduced to the Falu API, a new dated version is released. To avoid breaking users' code, we won’t change your version until you’re ready to upgrade.

Backward-compatible changes

Falu considers the following changes to be backward-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
    This includes adding or removing fixed prefixes (such as mtmp_ on message template IDs).
    You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If, for example, you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).
  • Adding new event types.
    Your webhook listener should gracefully handle unfamiliar event types.

Upgrading your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionalities or to streamline responses so the API is faster for you. Upgrading your API version will affect:

  • The API calls you make without a X-Falu-Version header, which affects the parameters you can send and the structure of objects returned.
  • The structure of objects sent to your webhook endpoints. If an endpoint has an explicit version set, it will remain unaffected.

To see what version you’re running and upgrade to the latest one, visit the Developers section of your Dashboard.

When performing an API upgrade, specify the API version you are integrating against in your code instead of relying on your workspace’s default API version. To test a newer version for API calls, set the X-Falu-Version header (in live or test mode). Learn how to manage versioning in our server-side libraries.

For webhooks, you can override the version of a single test webhook endpoint in your Dashboard. To safely upgrade your webhooks, Falu recommends that you:

  • Check the API changelog to see which objects will be structured differently.
  • Update your webhook code to handle both the old and new version of each object.
  • Change the version of a test webhook endpoint to the version you want to test.
  • Trigger the event in test mode and validate that your code works for the new structure.
  • When you are confident that your code can handle the latest API version, click the Upgrade version button in your Dashboard. This switches the version used by API calls that don’t have the X-Falu-Version header and the version used to render objects sent to your webhooks.

The shape of resources inside events retrieved from the API is defined by the default API version of your workspace at the time the event occurred. If your code retrieves events created when your default API version was different, your code will need to account for these changes when processing events.

images-developers-stay-informed-banner

API changelog

The API changelog only lists breaking changes to the Falu API. If you’re looking for information about feature additions and product updates, see the product changelog.

While we document changes through all API versions, only a few are retained on Falu servers. An API version is retained if it was released in the last 12 months, or it is among the top 3 latest versions. Before an API version is removed and if your workspace has used it recently, Falu shall send an email notifying the owner and admins about the removal.

2024-06-01

  • All HTTP PATCH endpoints now use JSON MergePatch instead of JSON Patch. This is easier to document and easier to implement for all developer scenarios including when generating an SDK for a language/ecosystem that we do not yet support.

2022-09-01

  • Sending multiple messages on one request is now only supported in the Message Batch API. See the guide for more information.

    Total number of messages in one request is still limited to 1,000.

2022-05-01

  • Evaluations now use a web based workflow. Falu will host the UI for this workflow which means that you have less work to actually do in your integrations and implementations. In the future, our client side SDKs would support this workflow hence give you better customizations. On creation of an evaluation, you will get a URL which you can give to your users to continue the evaluation process. An example of this URL: https://evaluate.falu.io/....

2022-01-01

  • Sending a message now takes an array of strings for the to property. With this, you can send the same message up to 500 recipients without needing the repeating the body in the batch endpoint. See Messages API.

  • Sending messages in bulk is now referred to as batch and supports up to 500 recipients in a single entry. See Messages Batch API.

    Total number of messages in one request is still limited to 1,000.

Deprecated API Versions

The following API versions are deprecated and are no longer served by FALU servers:

  • 2021-09-03
  • 2020-09-03