Introduction

Welcome to iCompleat’s API documentation. If you’re looking for real-time integration, how to import reference data, integrate purchase orders, invoices, credit notes and receipts from iCompleat, then you’re in the right place!

Follow the steps below to acquire your company's security credentials and begin implementing your finance solution with our API.

If you already have your credentials, scroll down to view the reference index for specific API calls.

 

Get your company credentials

Follow the steps below to get the credentials you need to begin using our APIs.

1. On the homepage, click Configuration.
2. Click Company management.
3. Click API. 
4. Your company credentials are displayed here.
5. Make a note of each field:
   1. API base URL
   2. Security key
   3. Tenant ID
   4. Company ID
   Click the icon to auto-copy to your clipboard.

Your Security key is a private key and should only be known to you and your organisation. If you think that your security is compromised, follow the steps below to generate a new key. 

With these credentials you can now begin working on your finance solution. Scroll down to view our reference index for specific API calls.

Otherwise, if you're building your own finance connector, scroll down to enable iCompleat for API integration.

 

How to generate a new Security key

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

Follow the steps below:

1. On the homepage, click Configuration.
2. Click Company management.
3. Click API. 
4. On the Security key field, click the icon to generate a new key.
   A new Security key is generated rendering your old key invalid.
5. Make a note of the new key or click the icon to auto-copy to your clipboard.

 

Response codes

We use conventional HTTP response codes in our API Reference to indicate the success or failure of a request, in addition to returning a data structure with any information returned, along with a set of metadata describing the response.

 

200 - Successful response

The HTTP 200 Successful response code indicates that the request has succeeded. A 200 response is cacheable by default. 

 

400 - Bad Request

The HyperText Transfer Protocol (HTTP) 400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

 

401 - Unauthorized

The HTTP 401 Unauthorized client error status response code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.

 

500 - Internal Server Error

500 Internal Server ErrorThe server has encountered a situation it doesn't know how to handle.

 

Reference Index

Tenant API

• Get a tenant's information
• Get the shard information of a tenant
• Get a tenant's company information
• Get detailed company information

User API

• Get a list of users for the tenant
• Get detailed user information

Transaction API

• Get a list of transactions
• Get details of a specific transaction
• Create a transaction (new purchase order, invoice or credit note)
• Edit a transaction (including approve or deny)
• Post approved invoices & credit notes to an endpoint

Transaction Attachment API

• Get a transaction's attachment

Transaction Timeline API

• Get a transaction's timeline(s)

Transaction Layouts API

• Get all layouts within a company

Suppliers API

• Get all suppliers within a company
• Create or append a company's suppliers
• Edit a supplier
• Delete a supplier

Analysis Fields API

• Get all analysis fields in a company or transaction

Account Codes API

• Get all account codes within a company
• Create or append a company's account codes
• Edit an account code
• Delete an account code

Tax Codes API

• Get all tax codes within a company
• Create or append a company's tax codes
• Edit a tax code
• Delete a tax code

Currency Codes API

• Get all currency codes within a company
• Create or append a company's currency codes
• Edit a currency code
• Delete a currency code

Delivery Sites API

• Get all delivery sites within a company
• Create or append a company's delivery sites
• Edit a delivery site
• Delete a delivery site

Custom Fields API

• Get all custom fields within a company
• Get details of a specific custom field
• Create or append a company's custom fields
• Edit a custom field
• Delete a custom field

Utilities API

• Get your connected system (heartbeat) status

 

Enable iCompleat for API Integration

Follow these steps to prep your iCompleat company for an API integration.

1. On the homepage, click Configuration.
2. Click Company management.
3. Click Connection.
4. Next to Connect to a new finance system, click Connect.
5. Select the API Integration tile.
6. Make a selection from the two dropdown fields that appear. 
   Which finance system are you integrating with?

   Which month is the start of your financial year?
   
7. When both dropdowns are populated, click Ok.

You have just prepped iCompleat for API Integration. Move on to the the section below to view the steps required to post transactions out of iCompleat to a webhook.

 

Post data out of iCompleat to a webhook

Configuration > Company Management > API

If your finance solution requires it, you can set a different endpoint for approved transactions (that includes purchase orders, invoices, credit notes and receipts).

You don't have to use a different endpoint for each transaction type, just use the same path in each drop-down explained below.

From the API screen, follow these steps to set a path for each transaction type:

1. Simply select from the drop-down the transaction type to set an endpoint for.
2.  Additional fields are displayed below to allow you to input a URL as an endpoint.
3. Use the auto-generated Secret token or rename it appropriately yourself for use in transaction integrations. 
4. Click Save.
5. Repeat this process on the remaining transaction types in the drop-down.

You're nearly ready to being integrating your iCompleat data! Please scroll below to read our last piece on responding to approved data once it is posted out of iCompleat.

 

Respond to approved transaction data with a Journal number

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

If you haven’t configured your endpoint details, scroll above for more information on posting to webhook endpoints and set the locations for your approved transaction data.

Journal number

After your endpoint has received an approved transaction from iCompleat, you must respond with a journal number.

See the POST Transaction call in our API reference index for more information.

Failing to do so will result in a posting failure in iCompleat.

Response sample below:

 

Once posted, this is displayed in the Approved tray of iCompleat in the far-right column.