v2.4 Release

Version 2.4 of the API is now available and contains some backward incompatible changes. As a result we're releasing v2.4 to and keeping v2.3 to until May 31, at which time v2.4 will be deployed to the existing base url.

Errors (breaking change)

In v2.3, error responses looked like this:

    "Code": "<error-type>",
    "Message": "<error-type>: <description>"

We're simplifying the structure by removing the code; instead, consume http status codes. The json contents are also updating to be more useful for resolving issues.

The new error structure looks like this:

  "message":"Failed to do something",
  "validation_errors": [], // only listed when invalid data is provided
  "event_id":"...", // provided with unexpected errors
  "reported_internally": true, // if reported to Bridge's engineering team

Tshe message is a summary of the problem. validation_errors is an array of strings and typically populated on 400 Bad Request errors where invalid data was used in a request. event_id is populated when Atlas experiences an unexpected error. Whenever you see this message, our development team has automatically been notified of the problem. If you'd like to follow up with support, providing the event ID will help us address the issue.

Filtering (breaking change)

Under v2.3 the API used double-underscores to provide filtering operations on fields. For example: if foo is a number you could provide foo__gt=X to get all the data where foo > X.

v2.4 enables much more complex filtering use cases using objects, which can be simple or complex. A simple filter is a key-value pair. For example, foo=X. A complex filter allows you to specify one or more conditions and looks like this:

  "foo": {
    "any_or_all": "all", // required only if more than 1 condition is provided
    "conditions": [{
      "value": 5,
      "op": "gte"
    }, {
      "value": 100,
      "op": "lte"

The above complex query will filter out all objects where foo is between 5 and 100.

For more details see API Usage > Filtering.

Output of removing data (breaking change)

There is no longer a /delete-many route to delete multiple objects. Instead, issue a DELETE request to the endpoint with several ids. For example to delete multiple objects (ids 1, 2 and 3) you would provide a payload with a DELETE method that looks like this:

  "ids": [1,2,3]


Under v2.3 pagination parameters were provided using the following query string variables:

  • page_size: The number of objects per page
  • page: The page number to fetch

With v2.4 the current api uses the following query string parameters:

  • pager.limit: the page size.
  • the page number

And the defaults and ranges have been changed:

  • Previous: Default = 100 with a max limit = 1,000
  • Current: Default = 10,000 with a max limit = 100,000

Endpoint routes

All endpoints in v2.4 have pluralized resource names. For example, if you retrieve object data then the resource and endpoint will be named objects. Moreover the complete set of supported methods for such data will looks like this:

Create routes

  • POST /objects: create a single object
  • POST /objects/create-many: create several objects (by providing an array of json objects)

Read routes

  • GET /objects: paginate objects using simple filters
  • POST /objects/filter: paginate objects using complex filters provided as a json payload
  • GET /objects/:id: details for an individual object

Update routes

  • PUT /objects/:id: update a single object
  • PUT /objects: update multiple objects

Delete routes

  • DELETE /objects/:id: delete a single object
  • DELETE / objects: delete multiple objects by providing a list of IDs in a json payload

Additional data envelope fields

The following additional fields are now available in the data envelope:

  • page_size_limit is the max size of each page (provided by the pager.limit parameter)
  • total_items is the total number of records available

For example:

    "object": "list",
    "has_next": true,
    "has_previous": false,
    "current_page": 1,          // the first
    "total_pages": 2,               // of 2 pages
    "page_size_limit": 10,  // which has a max of 10 objects
    "total_items": 18,          // and there are 18 objects in total
    "data": [{
        "object": "cac.class_tag",

Changes to fields (breaking change)

  • username is no longer required or used for firm profiles or client profiles

  • All models referencing valuetype has been renamed to value_type

Endpoint changes

  • Version 2.4 endpoints use /download for bulk download and /download/:id for single download.
    However, /bulk-download and /download-link/:id have been preserved for backwards compatibility.

  • Version 2.4 firm settings are available at org/firms, but the old firm/setting will still be available for backwards compatibility.

  • Data endpoints now provide separate url endpoints depending on whether the owning entity is an account or household. For example you can obtain account balances from /v2/data/luca/account-balances, household balances from /v2/data/luca/household-balances and /v2/data/luca/balances for account and household balances combined (the old behavior).

  • API key management has been moved to /v2/auth-management/api-keys

  • Jobs managment has been moved to /v2/jobs