Real-time integration with iCompleat using API V1

If you're new to iCompleat APIs, we have a new and improved package called API V2 which we recommend you use. Check out iCompleat API V2 now.

Welcome to iCompleat's API V1 documentation!

If you’re looking for real-time integration, and you want to know how to import reference data, integrate purchase orders, invoices, credit notes and receipts from Compleat, then you’re in the right place!

Follow the steps below to get your company's security credentials and begin implementing your iCompleat finance solution with API V1.

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

 

Get your company credentials

To get the credentials you need to begin using our APIs, follow these steps

 

1. On the homepage, click Configuration.
2. Click API.
3. In the top-left, go to API V1.
4. Click Activate.
5. API access has been enabled or your account, and your company's unique API credentials are displayed.These are:

   - API base URL

   - Security key

   - Tenant Id

   - Company Id

   Make a note of each credential.

   Use the copy button to the right of each field to copy it to your clipboard.

   

Your Security key is a private key and should only be known to you and your organisation. If you think 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.

 

Generate a new Security key

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

Here's how.

 

1. On the homepage, click Configuration.
2. Click API.
3. To the right of the Security key field, click the icon to generate a new key.
4. A new Security key is generated, rendering your old key invalid.

   Make a note of the new key or click the icon to copy it 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, and 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

 

Respond to approved transaction data with a Journal number

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

If you haven’t configured your endpoint details, read about posting to webhook endpoints here 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.

Here's a response sample:

 

Once posted, this is displayed in the Approved tray in Manage invoices in the far-right column.

 

 Still got questions? Comment below and let us know how we can improve this article.