What is SmoothIntegration

SmoothIntegration is a RESTful API built to make it easy to integrate with accounting systems.

The API is designed so that it will fulfill the following goals:
- Allow anyone to work with Accounting APIs with limited to no accounting experience.
- Create a unified experience, independent of the accounting system used.
- Remove all the challenges that come with Accounting APIs.

Just want to start? Then you can find the Getting Started and other guides here, Getting Started Guide ➔
To learn more about how to work with Smooth Integration, keep reading on.

Events

Events are at the core of SmoothIntegration. Whenever any accounting system is connected, SmoothIntegration will start producing events. An event describes a change in a Document in the accounting system. A Document is a single entity like an invoice or a customer. Events will be created for any change. This includes, creation events, update events, archive events, restoration events, and hard deletion events.

Events are chronological. This means that an event created at a later time, happened after an event created at an earlier time. Events are ordered by their event_id. A higher event_id means that the event happened after an event with a lower event_id. The document in any event will contain the complete latest known version of the document in the accounting system.

This monitoring of changes and producing events is also called Change Data Capture or CDC for short. From now on we will continue calling it CDC.

Events come in two flavours, "raw events" and "events". Raw events provide you the document exactly as it was returned by the external API. Whereas normal events provide you the document in a normalised manner. Meaning the structure will be consistent, independent of the accounting system. We recommend you use the normal events.

This all makes CDC a perfect solution for keeping data up-to-date in any data store or triggering business processes.

Events Structure
An event is is a JSON object with the following properties,
Key Value Example
event The entity this event is about. See below for a list of all possible eventsinvoice
event_id The unique ID of the event. This is a monotonically increasing 64 bit integer represented as a string695283292420706407
company_id The ID of the company that owns this connection1a6b35ab-9d0d-49c6-9bf3-e131d8699d6a
connection_id The ID of the connection that created this eventf9fa5070-9379-4789-bc0a-24a729b8bdeb
document_id The globally unique SmoothIntegration ID for the document this event describesac3249a6-a17c-db99-9fc5-1d265d8d3ff6
document The new state of the document after this event occurred. See the next section for more informationobject

Supported Events

Event Description
account General Ledger Account, an account on the Chart of Accounts
invoice Invoice (an invoice sent to a customer)
invoice_credit Invoice Credit, also known as a Credit Note or Credit Memo
bill Bill (an invoice received from a supplier)
bill_credit Bill Credit (an invoice credit received from a supplier), also known as a Vendor Credit or Debit Refund
company Company information or preferences of the connected company or organisation
item Item or Product sold or bought
purchase_order Purchase Order
sales_order Sales Order
customer Customer, someone you send invoices to, also known as a Contact
supplier Supplier, someone you receive bills from, also known as a Vendor or Contact
tax_rate Tax Rate
tracking_category Tracking Category, also known as a Class or Category
profit_and_loss Balances of P&L Accounts for a single month
balance_sheet Balances of BS Accounts for a single month
budget Budget information
budget_balance Balances of all accounts for a single budget
connection Connection on the SmoothIntegration platform
import Import job carried out by the SmoothIntegration platform

Raw CDC Events
If you're using the Raw CDC instead of the normal CDC, you will get different events. The events will use the naming convention of the accounting system prefixed with the accounting name. For example,
xero.profit_and_loss quickbooks.vendor myob.supplier exact.gl_account

The connection and import events will be identical between both CDC approaches, as they are generated by SmoothIntegration.

Documents

A Document is a single entity from the accounting system. This can be an invoice, a customer, a product, etc. Documents are the core of SmoothIntegration. All events are based on documents. The document will contain all the information that is available in the accounting system.

If you're using the Raw CDC, then a document will be returned exactly as is from the Accounting system. But if you're using the normal CDC, then the document will be normalised. This means that the document will be in a consistent format, independent of the accounting system. By normalising the documents for you we fix edge cases for you and ensure consistency between different ways of representing monetary values, dates, times, document statuses, references, and more, to ensure working with the data is as simple as possible, and your one solution will work with any accounting system.

Data Format Example
Timestamp ISO 8601 UTC datetime strings with millisecond precision YYYY-MM-DDTHH:mm:ss.sssZ2023-05-22T16:44:21.000Z
Date ISO 8601 date string YYYY-MM-DD2023-09-14
Monetary String with dot as decimal separator without any redundant decimals12345.67
Currency Code ISO 4217 Code in capital lettersUSD
UUID lowercase string with dashes01234567-89ab-cdef-0123-456789abcdef
Percentage numerical value where 1.0 represent 1%12.5

All keys in the document are in snake_case to ensure a consistent and non-ambiguous naming convention between all integrations.

References in a document to another document are always represented as an object containing identifying information of that other object. This means our documents will not contain a account_id , but instead contain a account object with the following structure:

API

SmoothIntegration provides a JSON based RESTful API hosted at https://api.smooth-integration.com .
You can learn more about the API in various places, but the two most important places are,
- API Explorer, which can be found in the Dashboard at API Explorer .
- API Reference, which can be found here API Reference .

Authentication

The SmoothIntegration API uses HMAC authentication. This means that you need to sign your requests with a Client Secret. This secret can be generated on the Authentication Page . Whilst very secure, HMAC is not the simplest to implement. Because of that reason we recommend you use one of our SDKs .

If you do want to implement it yourself, you can use this Authentication Guide or check the SDK implementations. The SDKs are open source and MIT licensed. They can be found on our Github .

Requests and Responses

Requests
All requests made to the SmoothIntegration API should be done using JSON. The API expects the following headers to be set:
- Content-Type : application/json
- Accept : application/json

Responses
The Rest API conforms to the RESTful convention when responding to requests. Every response will be in JSON. Every status code has a consistent response body structure.

Limits

Information on rate limiting will be added to the documentation soon. Please check back later.

SDKs

To simplify the integration with the SmoothIntegration API, we provide SDKs in various languages. These SDKs are all available on our Github . The SDKs are open source and MIT licensed.
- Python SDK available on PyPI ( Source Code )
- NodeJS SDK available on NPM and JSR ( Source Code )

Integrations

SmoothIntegration supports a wide array of integrations. We are constantly adding new integrations, if you have a specific integration you would like to see added, please reach out to us at [email protected]

Invoices
Bills
Invoice Credits
Bill Credits
Customers
Suppliers
Chart of Accounts
Profit and Loss
Balance Sheet
Bank Accounts
Company Info
Items
Purchase Orders
Sales Orders
Tax rates
Tracking categories
Budgets
Refresh Interval (minutes)
QuickBooks Online
30
Xero
60
Exact Online
30
ZohoBooks
360
MYOB
30
FreeAgent
360