API Introduction - Smartbills

Introduction

The Smartbills API is a RESTful API that allows you to programmatically manage expenses, expense reports, approvals, vendors, bills, categories, departments, and more. Use this API to integrate expense management capabilities into your applications, automate workflows, and build custom integrations.

Getting started? If you are new to the Smartbills API, start by creating an account and obtaining your API keys.

Base URL

All API requests should be made to:

https://api.smartbills.io/v1

For sandbox testing, use:

https://sandbox-api.smartbills.io/v1

See Environments for details on the available environments.

Authentication

All API requests require authentication using a JWT Bearer token. Include your API key or OAuth2 access token in the Authorization header:

GET /v1/expenses HTTP/1.1
Host: api.smartbills.io
Authorization: Bearer YOUR_API_KEY

See Authentication for complete details on obtaining and managing tokens.

Required Headers

Every request to the Smartbills API must include the following headers:

Header	Value	Required	Description
`Authorization`	`Bearer {token}`	Yes	Your API key or OAuth2 access token
`Content-Type`	`application/json`	For POST/PUT/PATCH	Request body format
`Accept`	`application/json`	Recommended	Expected response format
`x-tenant-id`	`{businessId}`	Yes	Business context for multi-tenant operations
`Accept-Language`	`en-CA`, `fr-CA`, `en-US`	Optional	Locale for localized responses

Multi-Tenant Architecture

Smartbills uses a multi-tenant architecture. You must specify the business context for each request using the x-tenant-id header:

GET /v1/expenses HTTP/1.1
Host: api.smartbills.io
Authorization: Bearer YOUR_API_KEY
x-tenant-id: 123

This header determines which business’s data you are accessing. Your API key must have permission to access the specified business.

Quick Example

Here is a quick example showing how to list expenses for a business:

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=1&pageSize=20' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 123'

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

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

const expenses = await client.expenses.list({
  page: 1,
  pageSize: 20
});

console.log(`Found ${expenses.pagination.totalCount} expenses`);

from smartbills import SmartbillsClient

client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

expenses = client.expenses.list(page=1, page_size=20)

print(f"Found {expenses.pagination.total_count} expenses")

Response

{
  "data": [
    {
      "id": 12345,
      "merchant": "Office Depot",
      "amount": 45.99,
      "currency": "CAD",
      "date": "2025-01-15",
      "category": "Office Supplies",
      "status": "pending"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 95,
    "hasNext": true,
    "hasPrevious": false
  }
}

Request Format

JSON Body

For POST, PUT, and PATCH requests, send JSON in the request body:

{
  "merchant": "Office Depot",
  "amount": 45.99,
  "currency": "CAD",
  "date": "2025-01-15",
  "categoryId": 10
}

Query Parameters

List endpoints support query parameters for pagination, sorting, and filtering:

GET /v1/expenses?page=2&pageSize=50&sortBy=date&sortOrder=desc&status=approved

Response Format

Success Response (Single Resource)

{
  "data": {
    "id": 12345,
    "merchant": "Office Depot",
    "amount": 45.99,
    "currency": "CAD"
  }
}

Success Response (List)

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 95,
    "hasNext": true,
    "hasPrevious": false
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount is required",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be greater than 0"
      }
    ]
  }
}

API Endpoint Groups

Expenses

Create, read, update, and delete expenses. Upload attachments and export expense data.

Expense Reports

Create and manage expense reports. Submit, approve, reject, and track report workflows.

Businesses

Manage businesses and their settings.

Vendors

Manage vendors and supplier information.

Departments

Manage departments and organizational structure.

Employees

Manage employee records and permissions.

Locations

Manage business locations and addresses.

Developer Resources

Authentication

Set up authentication and obtain tokens

API Keys

Create and manage API keys

Pagination

Paginate through large result sets

Error Handling

Handle API errors effectively

Rate Limits

Understand rate limiting policies

Webhooks

Receive real-time event notifications

Versioning

API versioning and compatibility

Localizations

Multi-language and locale support

SDKs

Official SDKs are available for the following platforms:

JavaScript SDK (@smartbills/sdk)
.NET SDK (Smartbills.NET)
React SDK
React Native SDK

Need Help?

Developer Portal: developers.smartbills.io
General Support: [email protected]
Security Issues: [email protected]
Community: community.smartbills.io

​Introduction

​Base URL

​Authentication

​Required Headers

​Multi-Tenant Architecture

​Quick Example

​Response

​Request Format

​JSON Body

​Query Parameters

​Response Format

​Success Response (Single Resource)

​Success Response (List)

​Error Response

​API Endpoint Groups

Expenses

Expense Reports

Businesses

Vendors

Categories

Departments

Employees

Locations

​Developer Resources

Authentication

API Keys

Pagination

Error Handling

Rate Limits

Webhooks

Versioning

Localizations

​SDKs

​Need Help?

Introduction

Base URL

Authentication

Required Headers

Multi-Tenant Architecture

Quick Example

Response

Request Format

JSON Body

Query Parameters

Response Format

Success Response (Single Resource)

Success Response (List)

Error Response

API Endpoint Groups

Developer Resources

SDKs

Need Help?