July 3, 2023

This document provides an overview of the July 3, 2023 Karbon API release.

We have created API endpoints that make it possible to list and retrieve invoices and their associated line items.

1. GET Invoices

2. GET Invoices by InvoiceKey

Note that draft invoices will not be returned by these APIs, i.e. an invoice must have been approved before it will be returned.

GET Invoices

Endpoint: https://api.karbonhq.com/v3/Invoices

When used with GET method, this end point returns a list of Invoices. Optionally, this list can be sorted by InvoiceDate using the $orderby querystring parameter either newest first with $orderby=InvoiceDate desc or oldest first with $orderby=InvoiceDate

Example use case

You want to retrieve a list of the three latest invoices by invoice date:

https://api.karbonhq.com/v3/Invoices?$orderby=InvoiceDate+desc&$top=4

This will return a JSON payload with the array value containing a summary of invoices. type: asset-hyperlink id: 7szye4Hw454pb8KFFRCGWr

GET Invoices by InvoiceKey

Endpoint: https://api.karbonhq.com/v3/Invoices/{InvoiceKey}

To make an API call to this endpoint using GET method replace {InvoiceKey} parameter in the URL above with a valid InvoiceKey (you can retrieve these using the Get Invoices endpoint).

To retrieve the line items for an invoice use the $expand querystring parameter with the value LineItems

Example use case

You want to retrieve an invoice along with it's line items:

https://api.karbonhq.com/v3/Invoices/{invoiceKey}?$expand=LineItems

This will return a JSON response with a single invoice as the payload. type: asset-hyperlink id: 79phUQ6M0eAJQkB9HSrsYj

Note on invoice line items

Each line item contains a set of properties that describe where it came from and it's value. Notable are the BillableItemType and BillableItemEntityKey properties which provide some indication of the WorkItem, Organisation or Contact the line item relates to.

Possible values BillableItemType are:

• TimeEntry - this indicates the line item is for billed time and that BillableItemEntityKey could be a WorkItem, Organization or Contact

• Expense - this indicates the line item relates to a billed expense and that BillableItemEntityKey could be a WorkItem, Organization or Contact

• Entity - this signifies that line items is for billed work and that BillableItemEntityKey is a WorkItem

In future a BillableItemEntityType field will be added and will specify one of WorkItem, Organisation or Contact to disambiguate the related BillableItemEntityKey entry for BillableItemType TimeEntry