Introduction

You can build your own connector with iCompleat's package of rest-based APIs and take full advantage of iCompleat's powerful automation solutions.

If you have already set up this configuration in iCompleat, follow this link to the available APIs in this package.

Getting started

The following steps are required to configure iCompleat and provide you with the correct security measures to begin building your own API powered connector:

Setup iCompleat for API Integration
Get your API security key
Set an Endpoint location
Set a Secret Token (recommended)
Get your Tenant and Company ID
Receiving approved transaction data from iCompleat

Set up iCompleat for API Integration

These steps will configure your iCompleat company for API integration.

On the homepage, click Configuration.
Click Company management.
Click Connection.
Next to Connect to a new finance system, click Connect.
Click API Integration.
Click from the two dropdowns
Which finance system are you integrating with?
Which month is the start of your financial year?
When both dropdowns are populated, click Ok.

You have just prepped iCompleat for API Integration. iCompleat will direct you to the API page where you can now Get your API security key.

Get your API security key

You must generate an API Security key for your account.

This is a private key and should be known only to your organisation.

Follow these steps to get your API security key.

On the homepage, click Configuration.
Click Company management.
Click API.
If this is your first visit to this page, you will have to activate API functionality. Click Activate.
On the Security Key field, click the icon to generate a key.
Make a note of the newly generated key or click the icon to copy to your clipboard.

Now continue to configure an endpoint location.

Generate a new key

If you are concerned your API key has been compromised, regenerate it to invalidate your key and replace it with a new one.

Follow these steps to delete your key.

On the homepage, click Configuration.
Click Company management.
Click API.
On the Security Key field, click the icon to generate a new key.
A new Security key is generated rendering your old key void.
Make a note of the newly generated key or click the icon to copy to your clipboard.

Configuring an endpoint location

An endpoint is the URL where your service can be accessed by a client application. It's a requirement with our API integration to configure an endpoint location for post approved order, invoice and credit note data.

We recommend sending requests to a secured HTTPS endpoint.

Follow these steps to set an Endpoint location:

On the homepage, click Configuration.
Click Company management.
Click API.
Simply paste your endpoint url into the dedicated fields for orders, invoices and credit notes.
Click Save.

Use the same URL in all 3 fields if you have chosen not to specify separate endpoints for orders, invoices and credit notes.

For added security we recommend setting a secret token for your endpoint, see our steps on setting secret tokens below.

Otherwise, advance to Finding your Tenant and Company ID.

Set a secret token (recommended)

As an added level of security to your API integration, we’ve implemented a token-based authentication system which can be sent as an additional parameter in your header data. This will enable you to verify that the data has come from a trusted source.

Follow these steps to access the API page and set a Secret token code.

On the homepage, click Configuration.
Click Company management.
Click API.
You can either:

Option 1

1. Use the auto-generated code in each field.

2. Copy the code to your clipboard using the icon.

Option 2

1. Delete the pre-populated code from the field and type a custom code as the token instead.

2. Copy to your clipboard using the icon.
3. Click Save.

Now advance below to find your Tenant and Company ID.

Get your Tenant and Company ID

In addition to a Security key, our APIs require you to submit a Tenant ID and Company ID to access the appropriate data.

Follow these steps to get your Tenant and Company IDs.

On the homepage, click Configuration.
Click Company management.
Click API.
Your IDs are displayed on screen.
Click the icon to copy an ID to your clipboard.

You are now ready to go!

You should now be fully configured and have the relevant keys and IDs to use our package on building an API powered connector.

Please view the section below on pushing data from iCompleat and how to acknowledge and respond with the transaction's journal number.

Receiving approved transaction data from iCompleat

Once a transaction has been fully approved in iCompleat, the transaction data will be sent automatically to your pre-configured endpoint via our webhooks.

If you haven’t added your endpoint details into iCompleat, see configuring an endpoint location to set the paths which your data will be sent to.

You can either specify separate endpoints for orders, invoices and credit notes, or you can use the same endpoint for all.

After your endpoint has received an approved transaction from iCompleat, you must acknowledge the message and respond with a journal number. The journal number will appear within iCompleat.

If a journal number is not returned to iCompleat, it will result in iCompleat recording the transaction as a posting failure.

See POST Transaction in our API library for more information.

Sample data for Postman

If you are using Postman as your API test tool, you can download a sample collection for both invoice and order data. Follow these steps to access our sample collection:

From the homepage, click Configuration.
Click Company management.
Click API.
At the bottom of the page, click the different sample data to download.

Feel free to use these samples as you see fit when testing your API calls.

APIs available in this package

Analysis Fields

HTTP METHOD	CRUD	DESC
GET Analysis Fields	Read	Used to retrieve a list of relevant analysis fields, either for a company, or in relation to a specific transaction.

Account Codes

HTTP METHOD	CRUD	DESC
GET Account Codes	Read	Used to retrieve all account codes within a given company.
POST Account Codes	Create	Used to refresh the account codes in a company with a complete new set of values, or append values to a previous new post.
PATCH Account Codes	Update / Modify	Used to add a single account code to an existing company, or update a single account code. A code and name is provided. If the code exists, then it is updated with the new name. If the code does not exist, it is added.
DEL Account Codes	Delete	Used to remove a specific account code.

Tax Codes

HTTP METHOD	CRUD	DESC
GET Tax Codes	Read	Used to retrieve all tax codes within a given company.
POST Tax Codes	Create	Used to refresh the tax codes in a company with a complete new set of values, or append values to a previous new post.
PATCH Tax Codes	Update / Modify	Used to add a single tax code to an existing company, or update a single tax code. A code and name is provided. If the code exists, then it is updated with the new name. If the code does not exist, it is added.
DEL Tax Codes	Delete	Used to remove a specific tax code.

Currency Codes

HTTP METHOD	CRUD	DESC
GET Currency Codes	Read	Used to retrieve all currency codes within a given company.
POST Currency Codes	Create	Used to refresh the currency codes in a company with a complete new set of values, or append values to a previous new post.
PATCH Currency Codes	Update / Modify	Used to add a single currency code to an existing company, or update a single currency code. A code and name is provided. If the code exists, then it is updated with the new name. If the code does not exist, it is added.
DEL Currency Codes	Delete	Used to remove a specific currency code.

Delivery Sites

HTTP METHOD	CRUD	DESC
GET Delivery Sites	Read	Used to retrieve all delivery sites within a given company.
POST Delivery Sites	Create	Used to refresh the delivery sites in a company with a complete new set of values, or append values to a previous new post.
PATCH Delivery Sites	Update / Modify	Used to add a single delivery site to an existing company, or update a single delivery site. A code and name is provided. If the code exists, then it is updated with the new name. If the code does not exist, it is added.
DEL Delivery Sites	Delete	Used to remove a specific delivery site.

Custom Fields (list only)

HTTP METHOD	CRUD	DESC
GET Custom Field(s)	Read	Used to retrieve all custom fields within a given company. Note that only active custom fields are returned in the list.
GET Custom Field	Read	Used to retrieve all details on a specific custom field within a given company.
POST Custom Field	Create	Used to refresh the list of options in a custom field with a complete new set of values, or append values to a previous new post.
PATCH Custom Field	Update / Modify	Used to add a single custom field list item to an existing custom field, or update a single custom field list item. A code and name is to be provided. If the code exists, then the name in the existing record is replaced with the new name provided. If the code does not exist, the record is added.
DEL Custom Field	Delete	Used to remove a specific custom field list item.

Suppliers

HTTP METHOD	CRUD	DESC
GET Suppliers	Read	Used to retrieve all suppliers within a given company.
POST Suppliers	Create	Used to refresh the suppliers in a company with a complete new set of values, or append values to a previous new post.
PATCH Suppliers	Update / Modify	Used to add a single supplier to an existing company, or update a single supplier. At least a code and name is to be provided. If the code exists, then all data in the existing record is replaced with the new data provided. If the code does not exist, the record is added.
DEL Suppliers	Delete	Used to remove a specific account code.