API Versioning - Smartbills

Overview

The Smartbills API uses versioning to ensure backward compatibility and allow for improvements without breaking existing integrations. The version is specified in the URL path.

Current Version

The current API version is v1. All API requests should include the version in the URL:

https://api.smartbills.io/v1/expenses

Version Format

API versions are specified in the URL path:

https://api.smartbills.io/{version}/{resource}

Examples:

https://api.smartbills.io/v1/expenses
https://api.smartbills.io/v1/expense-reports
https://api.smartbills.io/v1/businesses
https://api.smartbills.io/v1/vendors

Always specify the version: Do not omit the version from the URL path. Requests without a version may return unexpected results.

Checking Your API Version

You can check which version you are using by inspecting the response headers:

curl --request GET \
  --url https://api.smartbills.io/v1/expenses \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123' \
  --verbose 2>&1 | grep -i "x-api-version"

import { SmartbillsClient } from '@smartbills/sdk';

const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

// When making raw fetch requests:
const response = await fetch('https://api.smartbills.io/v1/expenses', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-tenant-id': '123'
  }
});

console.log('API Version:', response.headers.get('X-API-Version')); // "v1"

import requests

response = requests.get(
    'https://api.smartbills.io/v1/expenses',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'x-tenant-id': '123'
    }
)

print('API Version:', response.headers.get('X-API-Version'))  # "v1"

Backwards Compatibility Policy

We maintain backward compatibility within a major version. This means your integration will not break as long as you stay on the same major version.

Non-Breaking Changes (Safe)

The following changes are considered non-breaking and may be made within a major version without notice:

Adding new API endpoints
Adding new optional request parameters
Adding new properties to API responses
Adding new webhook event types
Adding new error codes
Adding new enum values to existing fields
Changing the order of properties in responses

Best practice: Your code should ignore unknown fields in API responses to handle new properties added in the future.

Breaking Changes (Require New Version)

The following changes are considered breaking and will only be introduced in a new major version:

Removing or renaming API endpoints
Removing or renaming required request parameters
Removing or renaming response properties
Changing the type of existing fields
Changing authentication methods
Changing error response formats
Removing enum values from existing fields

Deprecation Policy

When a new major version is released:

Deprecation Notice

We provide at least 12 months notice before deprecating an old version. You will receive notifications via email and the developer portal.

Deprecation Period

The old version continues to work during the deprecation period. You will see deprecation warnings in response headers.

Migration Guides

Detailed migration guides are provided to help you upgrade to the new version.

End of Life

After the deprecation period, the old version stops receiving updates. API requests to the deprecated version may eventually return errors.

Deprecation Headers

When a version is deprecated, responses include a warning header:

X-API-Deprecated: true
X-API-Sunset-Date: 2027-01-01

Best Practices

Always Specify the Version

Always include the version number in your API requests. Do not rely on default versions.

# Correct
https://api.smartbills.io/v1/expenses

# Avoid
https://api.smartbills.io/expenses

Handle Unknown Fields Gracefully

Your code should ignore unknown fields in API responses to handle new properties added in the future without breaking.

Test in Sandbox First

When migrating to a new API version, test thoroughly in the sandbox environment before updating production.

Version History

v1 (Current)

Released: January 2024 Status: Active Features:

Complete REST API for expenses, expense reports, businesses, vendors, and more
OAuth2 and API key authentication
Webhook support for real-time event notifications
Comprehensive error handling with error codes
Multi-language support (en-CA, fr-CA, en-US)
Multi-tenant architecture with x-tenant-id header
Pagination, sorting, and filtering on all list endpoints

API Introduction

API overview and getting started

Environments

Sandbox and production environments

Error Handling

Error codes and handling

Authentication

Authentication methods

Getting Help

If you have questions about API versioning or need help migrating to a new version:

Email: [email protected]
Developer Portal: developers.smartbills.io
Documentation: docs.smartbills.io

​Overview

​Current Version

Overview

Current Version