Skip to main content

API Upgrades

Your API version controls the API and webhook behavior you see (for example, what properties you see in responses, what parameters you’re permitted to send in requests, and so on). Your version gets set the first time you make an API request. When a breaking change is introduced to the Falu API, a new dated version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.

Backwards-compatible changes​

Falu considers the following changes to be backwards-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 functionality 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: 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 your Dashboard.

When performing an API upgrade, make sure that you specify the API version that you’re 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’re 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 also switches the version used to render objects sent to your webhooks.
caution

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.

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.

Whereas we document, the changes through all API versions, only a few a 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.

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
Last updated on