Localizations

Overview

The Smartbills API supports multiple languages and locales, allowing you to receive localized responses for your users. Use the Accept-Language header to specify the desired locale for each request.

Supported Locales

Language	Locale Code	Description
English (Canada)	`en-CA`	Default locale
French (Canada)	`fr-CA`	Canadian French
English (US)	`en-US`	US English

Default locale: If no Accept-Language header is provided, the API defaults to en-CA.

Setting the Locale

Include the Accept-Language header in your API requests to receive localized responses:

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

Code Examples

# English response
curl --request GET \
  --url https://api.smartbills.io/v1/expenses \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123' \
  --header 'Accept-Language: en-CA'

# French response
curl --request GET \
  --url https://api.smartbills.io/v1/expenses \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123' \
  --header 'Accept-Language: fr-CA'

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

// Set locale at client initialization
const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

// Or set locale per request using raw fetch:
const response = await fetch('https://api.smartbills.io/v1/expenses', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-tenant-id': '123',
    'Accept-Language': 'fr-CA'
  }
});

from smartbills import SmartbillsClient

# Set locale at client initialization
client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

# Or set locale per request using raw requests:
import requests

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

Localized Response Fields

When you specify a locale, the following elements are localized in API responses:

Error Messages

Error messages are returned in the requested language:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The amount field is required"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le champ montant est requis"
  }
}

Category Names

Expense categories are automatically localized:

{
  "categories": [
    { "id": 1, "name": "Office Supplies" },
    { "id": 2, "name": "Travel" },
    { "id": 3, "name": "Meals & Entertainment" }
  ]
}

{
  "categories": [
    { "id": 1, "name": "Fournitures de bureau" },
    { "id": 2, "name": "Voyage" },
    { "id": 3, "name": "Repas et divertissements" }
  ]
}

Status Labels

Status labels are localized based on the Accept-Language header:

{
  "status": "pending",
  "statusLabel": "Pending Review"
}

{
  "status": "pending",
  "statusLabel": "En attente de revision"
}

Validation Messages

Field-level validation messages are returned in the requested language:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request data is invalid",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be greater than 0"
      },
      {
        "field": "date",
        "message": "Date must be in ISO 8601 format"
      }
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Les donnees de la requete sont invalides",
    "details": [
      {
        "field": "amount",
        "message": "Le montant doit etre superieur a 0"
      },
      {
        "field": "date",
        "message": "La date doit etre au format ISO 8601"
      }
    ]
  }
}

Fields That Are NOT Localized

The following fields are always returned as-is regardless of locale:

Identifiers: id, code, status (machine-readable values)
Amounts: amount, totalAmount (numeric values)
Dates: date, createdAt, updatedAt (ISO 8601 format)
Currencies: currency (ISO 4217 codes)
User-entered data: merchant, notes, description (stored as entered)
Error codes: code field in error responses (machine-readable)

Fallback Behavior

If a translation is not available for a specific locale, the API falls back to English (en-CA):

Accept-Language: de-DE

Since de-DE is not currently supported, responses will fall back to English.

Currency and Number Formatting

The API returns raw numeric values. Locale-specific formatting should be handled client-side:

{
  "amount": 1234.56,
  "currency": "CAD"
}

Use your client-side locale formatting libraries:

const formatter = new Intl.NumberFormat('fr-CA', {
  style: 'currency',
  currency: 'CAD'
});

console.log(formatter.format(1234.56));
// Output: "1 234,56 $"

const enFormatter = new Intl.NumberFormat('en-CA', {
  style: 'currency',
  currency: 'CAD'
});

console.log(enFormatter.format(1234.56));
// Output: "$1,234.56"

import locale

# French Canadian formatting
locale.setlocale(locale.LC_ALL, 'fr_CA.UTF-8')
print(locale.currency(1234.56, grouping=True))
# Output: "1 234,56 $"

Best Practices

Always Specify Accept-Language

Always include the Accept-Language header to ensure consistent localization. Do not rely on default behavior.

Store User Preferences

Store the user’s language preference in your application and include it in all API requests automatically.

Handle Missing Translations

Be aware that unsupported locales fall back to English. Design your UI to handle this gracefully.

Format Numbers and Dates Client-Side

The API returns raw values for amounts and dates. Use locale-aware formatting libraries on the client side for display.

Requesting New Languages

If you need support for additional languages, contact us at [email protected] with:

The language and locale you need
Your use case
Expected volume of requests

We regularly add new languages based on customer demand.

API Introduction

API overview and headers

Error Handling

Localized error messages

Authentication

Authentication and headers

Environments

Sandbox and production

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Overview

Supported Locales

Setting the Locale

Code Examples

Localized Response Fields

Error Messages

Category Names

Status Labels

Validation Messages

Fields That Are NOT Localized

Fallback Behavior

Currency and Number Formatting

Best Practices

Requesting New Languages

API Introduction

Error Handling

Authentication

Environments

​Overview

​Supported Locales

​Setting the Locale

​Code Examples

​Localized Response Fields

​Error Messages

​Category Names

​Status Labels

​Validation Messages

​Fields That Are NOT Localized

​Fallback Behavior

​Currency and Number Formatting

​Best Practices

​Requesting New Languages

​Related Resources

API Introduction

Error Handling

Authentication

Environments

Overview

Supported Locales

Setting the Locale

Code Examples

Localized Response Fields

Error Messages

Category Names

Status Labels

Validation Messages

Fields That Are NOT Localized

Fallback Behavior

Currency and Number Formatting

Best Practices

Requesting New Languages

Related Resources