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 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.
| Key | Value | Example |
|---|---|---|
| event | The entity this event is about. See below for a list of all possible events | invoice |
| event_id | The unique ID of the event. This is a monotonically increasing 64 bit integer represented as a string | 695283292420706407 |
| company_id | The ID of the company that owns this connection | 1a6b35ab-9d0d-49c6-9bf3-e131d8699d6a |
| connection_id | The ID of the connection that created this event | f9fa5070-9379-4789-bc0a-24a729b8bdeb |
| document_id | The globally unique SmoothIntegration ID for the document this event describes | ac3249a6-a17c-db99-9fc5-1d265d8d3ff6 |
| document | The new state of the document after this event occurred. See the next section for more information | object |
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.
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.sssZ | 2023-05-22T16:44:21.000Z |
| Date | ISO 8601 date string YYYY-MM-DD | 2023-09-14 |
| Monetary | String with dot as decimal separator without any redundant decimals | 12345.67 |
| Currency Code | ISO 4217 Code in capital letters | USD |
| UUID | lowercase string with dashes | 01234567-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:
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
.
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
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.
Information on rate limiting will be added to the documentation soon. Please check back later.
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
)
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 | | | | | | | | | | QuickBooks Online only supports Bank Accounts for US based organisations. | | | | QuickBooks Online does not have a Sales Orders feature. | | | | 30 |
| Xero | | | | | | | | | | | | Xero does not provide any way to find out if an Item is archived. If this is critical, we recommend you delete Items instead of archiving. https://xero.uservoice.com/forums/5528-accounting-api?category_id=135816 | | | | | | 60 |
| Exact Online | | | | | | | | | | | | | | | | | | 30 |
| ZohoBooks | | | | | | | | | | | | | | | | | | 360 |
| MYOB | | | | | | | | | | | | | | | | | | 30 |
| FreeAgent | | | | | | | | | | | | | | | | | | 360 |