Partner Portal

Accounting integrations

Enable your users to synchronize accounts payable and receivable data with popular accounting solutions.

Introduced in API version 2023-04-12.

Overview

Many SMEs use various accounting solutions to store their financial data and prepare it for submission to tax authorities. With Monite, you can connect your users' data to their preferred accounting software and pull necessary financial data for import into your interface, as well as push data in case they need to do any post-accounting work outside of your application.

📘

To support integration with accounting systems, Monite leverages the technology of its strategic partner, Codat, which supports a wide range of accounting systems and connections. You will also need to make a separate agreement with Codat. Please contact your Account Manager at Monite to assist in this process.

Supported accounting systems

Each entity can connect to one of the following accounting systems:

  • QuickBooks
  • Xero
    • Important: If you plan to provide Xero integration to more than 25 entities, you must register with Xero as a Xero App Partner. This involves additional requirements set by Xero. The registration can take several weeks to get finalized, so we recommend that you apply as soon as possible.

New supported accounting systems will be added in future releases of our platform. If you have any specific requests, please contact our Support team.

📘

An entity can connect their data to only one accounting system. If they want to connect to another accounting system, they have to disconnect the currently connected system first.

Requirements and considerations

  • A Monite partner should make a separate arrangement with Codat to enable their services via Monite API. To learn more about this and get Monite assistance, please contact your Account Manager at Monite.
  • Each entity that wants to connect to an external accounting system (like Xero or QuickBooks) should create an account with that system and securely store login credentials, as these credentials will be needed in the future to authorize its access to their data, which is stored within the corresponding accounting system.

How the integration works

As the first step, you need to establish a connection to the accounting software of an entity and ask an entity user to authorize the connection.

Once the connection has been established, all financial data of this entity is automatically synchronized every hour.

You can track the data synchronization status in the following ways:

  • call Monite's GET /accounting_connections/{connection_id} endpoint
  • review data in the Codat Portal
  • subscribe to Codat webhooks

What data is synchronized

Currently, Monite pulls and pushes the following data from and to accounting systems. Data is synchronized every hour.

DataPulledPushed
Ledger accounts:heavy-check-mark:References to ledger accounts
in invoice line items, and products
Counterparts:heavy-check-mark::heavy-check-mark:
Products:heavy-check-mark: *
Accounts Receivable: invoices:heavy-check-mark:
Accounts Payable: invoices (bills):heavy-check-mark:

* Products are matched by name (exact match, case-sensitive). When pulling data from an accounting systems, new products are created in Monite but existing products are not updated.

Limitations

Data push limitations

  • Accounts Receivable invoices with invoice-level discounts cannot be pushed to accounting systems. However, invoices with line item discounts are pushed.

Data pull limitations

  • In accounting systems, the currency is set at an entity level, while in Monite, each product can have a price in its own currency. Therefore, when pulling data from accounting systems, Monite uses the currency set at the entity level and sets it for each product.
  • Unlike Monite, Codat does not provide a separate collection of customizable measure units at the entity level. To overcome this limitation, Monite generates some stub measure units when pulling data via Codat. Entity users can adjust the measure units later if needed.

Terminology

The following table compares the terms used by Monite and Codat, so that you know which resources to examine when testing data synchronization:

Monite termCodat term
EntityCompany
Entity usern/a
CounterpartCustomer, Supplier
PayableBill
Receivable: InvoiceInvoice

Set up integration with an accounting system

1. Preliminary steps

Before you begin developing your implementation, there are some setup steps you need to complete in Codat and in the accounting systems you want to integrate with. This involves registering an app in QuickBooks Online and/or Xero platforms to get the client keys for integrating with these platforms. You will then need to enable the corresponding integrations in the Codat Portal (for both of your Codat Production instance and Test instance) and specify your app's client keys.

For the detailed instructions, refer to Codat documentation:

2. Get a Codat API key

Monite calls Codat API on behalf of a Monite partner. To do that, Monite needs a partner's encoded Codat API key. To get this key:

  1. Log in the Codat Portal.
  2. In the top right corner, select the Codat client account whose API key you need - Test instance or Production instance.
  3. Go to Developers > API > API keys.
  4. If you don't already have an API key, create one.
  5. Copy the value of the Authorization header (not the API key value). This value is in the format Basic YOUR_ENCODED_API_KEY.
  1. Remove the "Basic " prefix from the copied value, so that you have just YOUR_ENCODED_CODAT_API_KEY. This is the value you will have to specify later in your Monite partner settings.

Repeat the steps to get the encoded API keys for both Codat Test instance and Production instance. You need need to use the corresponding key with Monite Sandbox and Production environments.

3. Send Codat webhooks to Monite

In order for Monite to know the status of data synchronizations and accounting connections of your entities, you must subscribe to certain Codat webhooks and send them to Monite. The necessary Codat webhooks are:

  • Push Operation Status Changed
  • Data sync completed
  • DataConnectionStatusChanged

and Monite webhook listener URLs for accounting webhooks are:

📘

You must configure these webhooks both in Codat Test instance and Production instance. Codat Test instance should send webhooks to the Monite Sandbox environment, and Codat Production instance should send them to the Monite Production environment.

To configure the webhooks:

  1. In the Codat Portal, select your Codat client account to configure webhooks for - Test instance or Production instance.
  2. Go to Settings > Webhooks > Rules.
  3. Click Create new rule.
  4. Specify the following settings:
    • Rule type - select one of the above mentioned webhooks.
    • Company - select All companies.
    • (Optional) Email addresses to notify - a comma-separated list of email addresses where to send the notifications.
    • Webhook notification URL:
    • Click Save changes.

Repeat the steps to create the rules for all three webhooks in both Codat Test instance and Production instance.

4. Generate a Monite partner access token

To authenticate your API calls with Monite, you need to generate a new partner-level token. To do this, call POST /auth/token with the following parameters:

curl -X POST 'https://api.sandbox.monite.com/v1/auth/token' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'Content-Type: application/json' \
     -d '{
        "grant_type": "client_credentials",
        "client_id": "YOUR_PARTNER_CLIENT_ID",
        "client_secret": "YOUR_PARTNER_CLIENT_SECRET"
     }'

The successful response contains the token and its validity time (in seconds):

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb...",
  "token_type": "Bearer",
  "expires_in": 1800
}

5. Specify Codat API key in Monite partner settings

Next, you need to specify your encoded Codat API key in your partner settings in Monite. To do this, call PATCH /settings and provide the accounting object containing the encoded API key you obtained in step 1. The value is that of the Codat "Authorization header" but without the "Basic " prefix.

curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "accounting": {
         "provider": "codat",
         "token": "YOUR_ENCODED_CODAT_API_KEY"
       }
     }'

6. Set up entities in Monite

If you have not already, create entities in Monite that represent your customers. Since the connection to an accounting system is configured on the entity level, entities must already exist in Monite before you proceed further.

Entities who use Accounts Receivable also need to create their product catalog in Monite before setting up accounting connection.

7. Check if an entity already has an active accounting connection

Before configuring a new accounting connection for an entity, make sure this entity has no other existing accounting connections that are active at the moment. For this purpose, call GET /accounting_connections with the X-Monite-Entity-Id header containing the entity ID:

curl 'https://api.sandbox.monite.com/v1/accounting_connections' \
  -H 'X-Monite-Version: 2023-06-04' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: YOUR_PARTNER_TOKEN'

If there are no other active connections set up for this entity, you will receive a 200 OK response with an empty data array:

{
  "data": []
}

8. Establish entity connection to an accounting system

To establish a new accounting connection that allows an entity to synchronize all its accounting data with a third-party accounting system, call POST /accounting_connections. In this request, pass the entity ID in the X-Monite-Entity-Id header and specify the software type in the platform parameter:

curl -X POST 'https://api.sandbox.monite.com/v1/accounting_connections' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d '{
       "platform": "xero"
     }'

The successful 201 Created response contains the information about the newly created connection:

{
    "id": "bb0b61e3-2295-4212-8a96-df60dd3528ab",
    "created_at": "2023-02-16T07:38:01.631172+00:00",
    "updated_at": "2023-02-16T07:38:01.631192+00:00",
    "status": "pending_auth",
    "platform": "xero",
    "connection_url": "https://link-api.codat.io/companies/42ed7770-51ea-45e5-9e4a-160er3db539d/connections/70eb9b71-7126-4d5f-b088-de7b86c84bc5/start",
    "last_pull": "2023-02-16T07:38:01.631218+00:00",
    "errors": null
}

The status of a newly created accounting connection is pending_auth. This means that an entity user needs to authorize this connection by using a web page specified by the the connection_url field.

Note down the connection_url value as you will need it on the next step.

Make sure to also store the id of this connection, as you will need it later to retrieve the connection status and details via GET /accounting_connections/{id}.

9. Entity user authorizes their connection

Next, send the connection_url received on the previous step to the entity user who is responsible for authorizing the accounting integration. For example, if your application is web-based, you can redirect the user to that URL.

On this page, the entity user must provide their login credentials with that accounting system and give authorization for Monite to access their data via Codat.

The URL of this authorization page looks like this:

https://link-api.codat.io/companies/SOME_ID/connections/SOME_ID/start

The next steps vary depending on the accounting system, and below we give you an example of how this flow might look like for Xero.

Xero authorization flow

Xero authorization flow

  1. Log in to Xero (if not already).
  2. The following screen is displayed.
    Select the organization account whose data you want to synchronize, and click Allow access:
  1. On the next screen, verify the selected organization and click Confirm:
  1. On the next screen, click Next:
  1. Click Finish:

10. Configure invoice statuses to push into the accounting system (Optional)

By default, Monite pushes payables and receivables to the connected accounting system when they have these statuses:

  • payable statuses: waiting_to_be_paid
  • receivable statuses: issued, paid, partially_paid, overdue, canceled, uncollectible

Entities can change the status list if needed.

To set the statuses, call PATCH /accounting_sync_rules with the following request body, replacing the status list as needed:

curl -X PATCH 'https://api.sandbox.monite.com/v1/accounting_sync_rules' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "push_statuses": {
         "payable": [
           "waiting_to_be_paid"
         ],
         "receivable": [
           "issued",
           "canceled",
           "overdue",
           "uncollectible",
           "partially_paid",
           "paid"
         ]
       }
     }'

To get the current list of pushable statuses, call GET /accounting_sync_rules.

📘

Note

The pull_statuses setting is currently unused and reserved for future use.

Disconnect the accounting system

To disconnect an already established accounting connection, call POST /accounting_connections/{id}/disconnect:

curl -X POST 'https://api.sandbox.monite.com/v1/accounting_connections/{id}/disconnect' \
  -H 'X-Monite-Version: 2023-06-04' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The successful 200 OK response contains "status": "disconnected":

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f76afa6",
  "status": "disconnected",
  "platform": "xero",
  "created_at": "2023-04-02T13:11:53.250Z",
  "updated_at": "2023-04-02T13:11:53.250Z",
  "last_pull": "2023-04-02T13:11:53.250Z",
  "errors": null
}

Troubleshooting

If you experience any issues and need our assistance with this integration, please feel free to contact our Support Team at any time.

External resources

Codat documentation contains some helpful information about implementing and testing your accounting integrations: