Analysing documents for emissions data
NZ only
Document processing is available for New Zealand documents only.
Introduction
In carbon accounting scenarios, it is often important to extract emissions data from invoices, bills, and receipts. CarbonAPI supports the extraction of an organisation's documents, scanning them for pertinent emissions data, and returning the results to developers.
Supported document categories
- Air Tickets
- Accommodation (Hotels)
- Fuel Invoices/Receipts
- Waste Pickups
- Mileage Claims
- Electricity Invoices
- Natural gas / reticulated gas
See platform coverage to understand if your country/region is supported. Please contact us if your region is not yet supported.
Accepted document formats
- image/jpeg
- application/pdf
Other document types will be rejected. You will not be billed for rejected document types.
Accepted document types
- Invoices + Bills
- Pictures and scans of receipts
Pages in a document
You may submit a document with at most 50 pages. Note, for billing purposes, a document is considered to have 3 pages. Subsequent pages after the first 3 will be billed as separate documents. For example, a document with 9 pages, will billed 3x.
Documents with over 50 pages will be rejected.
Base64 uploads
Submit document bytes inline as Base64 using content or blob on each document, with type: "base64". URL upload via fileUrl is no longer supported.
Payload size limits
The maximum request body size is 200 MB (aligned with the Cloudflare edge limit). Oversized payloads are rejected before processing begins.
import { CarbonAPIClient } from "@carbonapi/typescript-sdk";
import { readFileSync } from "node:fs";
const client = new CarbonAPIClient({
apiKey: "your-api-key-here",
});
const content = readFileSync("./invoice.pdf").toString("base64");
const batchId = await client.createDocumentBatch({
type: "base64",
countryCode: "NZL",
documents: [
{
content,
contentType: "application/pdf",
},
],
});Step-by-step guide
First, we need to sign up for CarbonAPI. You can do this and get free evaluation credits by heading to the Account Portal and signing up.
For this guide, we'll use polling to check for the results of our call, but to reduce overhead, we strongly recommend using our Webhooks approach, which allows you to be notified once processing has completed.
Now, you can either review our API Reference, or drop in our TypeScript SDK, which will allow you to get started quickly.
Good to know
CarbonAPI is powered by AI, which can sometimes make mistakes. It is important that you review the outputs of this service.
Okay, so we have now created a document analysis job. At the time of writing, only an asynchronous approach is supported, but we plan to add sync calls in the future.
Now, let's poll for changes in the batch. As mentioned, this is not the preferred approach, we strongly suggest using Webhook calls to reduce the complexity of your application, this is just for demo purposes.
Note, this is queue-based service. Your request will be processed as soon as possible, but you may need to wait for a few minutes when we're busy. Again, a good reason to use Webhooks!
const poll = setInterval(() => {
const documentBatch = await client.getDocumentBatch(batchId);
if (documentBatch.status === "Completed") {
console.log(documentBatch.documents); // This will contain your categories and emissions information.
clearInterval(poll); // Don't forget to do this.
}
}, 10_000); // Call every 10 seconds.