Tidely Developer Portal

Welcome to the Tidely Developer Portal. This portal provides everything you need to integrate with the Tidely financial planning and cash flow management platform.

Using API v1?

If you are currently using the v1 API, the documentation is still available at:

https://api.tidely.com/tidely-open-api/swagger-ui/index.html

The v1 API is deprecated but continues to be supported. We recommend migrating to v2 when possible. See our Migration Guide for details.

What is Tidely?

Tidely is a financial management platform that helps businesses track cash flow, manage bank accounts, create financial plans, and import invoices from external systems.

APIs

Tidely offers two APIs:

Public API

The Public API is designed for end users and customers who want to build direct integrations with their own Tidely account. Authentication uses API keys.

→ Public API Documentation

Partner API

The Partner API is designed for white-label partners and system integrators who need to access the API on behalf of multiple customers. Authentication uses OAuth 2.0.

→ Partner API Documentation

Release Cycle & Versioning

Versioning Policy

The Tidely API uses semantic versioning with the major version included in the URL path (e.g., /public/v2). This ensures backward compatibility within a major version.

Breaking vs. Non-Breaking Changes

Non-breaking changes (no version bump):

• Adding new optional request fields
• Adding new response fields
• Adding new endpoints
• Adding new enum values (treat enum fields as open-ended strings in your client)

Breaking changes (major version bump):

• Removing or renaming existing fields
• Changing field types
• Removing endpoints
• Changing authentication mechanisms

Changelog

Version	Public API	Partner API	Status	End of life
v2	[x]	[x]	Current	not scheduled
v1	[x]	[ ]	Deprecated	not scheduled

→ View Full Changelog — see all API changes and updates

Support Policy

New major versions of the API are released when breaking changes become necessary to further evolve the API. We aim to limit the number of major versions released in one calendar year to a maximum of 2.

When a new major version is released, the previous major version is automatically deprecated. Deprecated versions continue to be supported, receiving security patches and bugfixes, but no new features will be added.

After a version is deprecated, end of life may be announced for it at any time. There will be at least 6 months between announcement and end of life. End of life of API versions will be announced via email to registered API users and in the changelog.

Error Handling

All Tidely API error responses follow a consistent structure, making it easy to implement robust error handling in your integration.

Error Response Format

When an API request fails, the response body contains an ExceptionDetails object:

{
  "timestamp": 1711234567890,
  "error": "INVALID_REQUEST",
  "message": "userId must be a positive integer"
}

Fields:

Field	Type	Description
timestamp	integer	Unix timestamp (milliseconds) when the error occurred
error	string	Stable, machine-readable error code (e.g. INVALID_REQUEST, USER_NOT_FOUND). Use this for programmatic error handling.
message	string	Human-readable error description. For display/logging only — do not match on it.

The HTTP status is conveyed by the response status line and is not duplicated in the body.

HTTP Status Codes

Code	Meaning	Typical Cause
400	Bad Request	Invalid request body, missing required fields, or validation errors. Check message and the error code for details.
401	Unauthorized	Missing or invalid credentials. Verify your authentication header.
403	Forbidden	Valid credentials but insufficient permissions for the requested operation.
404	Not Found	The requested resource does not exist. Verify the resource ID.
500	Internal Server Error	An unexpected server-side error. Retry the request after a short delay. If the problem persists, contact support.

Retry Strategy

For 500 errors, implement an exponential backoff retry strategy:

1. Wait 1 second, then retry
2. If still failing, wait 2 seconds, then retry
3. If still failing, wait 4 seconds, then retry
4. After 3 retries, log the error and alert your team

Do not retry 400, 401, 403, or 404 errors — these require a change to the request itself.

Pagination

Some API endpoints return paginated responses when the result set is large. Endpoints that support pagination are indicated in the API reference. You can identify them by the page and pageSize query parameters in their request definition and pagination metadata in their response schema.

Request Parameters

Control pagination using query parameters:

Parameter	Type	Default	Description
page	integer	0	Page number (0-based)
pageSize	integer	50	Number of items per page (minimum: 1)

Example:

curl -X GET "https://api.tidely.com/public/v2/bank-account-transactions?bankAccountId=10&page=0&pageSize=20" \
  -H "X-Authorization: YOUR_API_KEY"

Response Structure

Paginated responses include metadata alongside the data array:

{
  "success": true,
  "message": "Resources retrieved successfully",
  "number": 0,
  "size": 20,
  "totalElements": 125,
  "totalPages": 8,
  "data": [
    ...
  ]
}

Pagination Metadata Fields:

Field	Type	Description
number	integer	Current page number (0-based)
size	integer	Number of items per page
totalElements	integer	Total number of items across all pages
totalPages	integer	Total number of pages

Iterating Through All Pages

To retrieve all items, increment the page parameter until you have fetched all pages:

GET /example-resource?page=0&pageSize=50
GET /example-resource?page=1&pageSize=50
GET /example-resource?page=2&pageSize=50
...

Stop when page reaches totalPages - 1 (since pages are 0-based) or when the data array is empty.

Migration Guide

→ Migration Guide (v1 → v2) — how to upgrade from API v1 to v2

Webhooks

Webhooks are not currently available. All integrations must use polling to detect changes. We are evaluating webhook support for a future release — if this is important for your use case, please let us know at support@tidely.com.

Contact and Support

• Contact support@tidely.com for general questions and support regarding Tidely
• Use our helpdesk for questions, technical advice and reporting problems when using the API