API

SDKs

Ready-made libraries for calling the API from TypeScript / JavaScript, Python, Go, PHP, Ruby and Rust. Each one covers the whole API, retries failed requests for you, and checks webhook signatures. They all behave the same way: the same methods, errors and retries.

TypeScript / JavaScriptPythonGoPHPRubyRustJava / KotlinSoonC# / .NETSoon

Which key?

A business creates a key in Invoist under Integrations, then API, and uses the invoice methods. A household on Invoist Personal, the plan for the home, creates one under Settings, then AI assistants, and uses the bill methods. Keep keys on your server, never in a browser or a mobile app.

TypeScript / JavaScript

@invoist/sdk on npm. Node 22 or newer, Bun, Deno, or any runtime with fetch. Source and full README on GitHub.

Install
npm install @invoist/sdk
A business: read an invoice
import { Invoist } from "@invoist/sdk";

const invoist = new Invoist({ apiKey: process.env.INVOIST_API_KEY! });
const { extraction } = await invoist.extractAndWait("invoice.pdf");
console.log(extraction.vendor_name, extraction.total_cents, extraction.currency);
A household: what is left to pay
const unpaid = await invoist.bills.list({ paid: false });
for (const bill of unpaid) console.log(bill.vendor_name, bill.total_cents, bill.due_date);

Python

invoist on PyPI. Python 3.11 or newer; sync and async clients. Source and full README on GitHub.

Install
pip install invoist
A business: read an invoice
import os
from pathlib import Path
from invoist import Invoist

invoist = Invoist(os.environ["INVOIST_API_KEY"])
result = invoist.extract_and_wait(Path("invoice.pdf"))
print(result.extraction.vendor_name, result.extraction.total_cents)
A household: what is left to pay
for bill in invoist.bills.list(paid=False):
    print(bill.vendor_name, bill.total_cents, bill.due_date)

Go

github.com/invoisthq/invoist-go on Go modules. Go 1.26 or newer; no dependencies. Source and full README on GitHub.

Install
go get github.com/invoisthq/invoist-go
A business: read an invoice
client, err := invoist.New(os.Getenv("INVOIST_API_KEY"))
if err != nil {
	log.Fatal(err)
}
file, _ := invoist.FileFromPath("invoice.pdf")
result, err := client.ExtractAndWait(ctx, file, nil)
A household: what is left to pay
bills, err := client.Bills.List(ctx, &invoist.ListBillsParams{Paid: new(false)})

PHP

invoist/invoist on Packagist. PHP 8.3 or newer with curl, or any PSR-18 client. Source and full README on GitHub.

Install
composer require invoist/invoist
A business: read an invoice
use Invoist\Invoist;
use Invoist\Upload;

$invoist = new Invoist(getenv('INVOIST_API_KEY'));
$result = $invoist->extractAndWait(Upload::fromPath('invoice.pdf'));
echo $result->extraction->vendor_name;
A household: what is left to pay
foreach ($invoist->bills->list(paid: false) as $bill) {
    echo "$bill->vendor_name: $bill->total_cents, due $bill->due_date\n";
}

Ruby

invoist on RubyGems. Ruby 3.3 or newer; no dependencies. Source and full README on GitHub, and every class and method on RubyDoc.

Install
bundle add invoist
A business: read an invoice
require "invoist"

client = Invoist::Client.new(api_key: ENV.fetch("INVOIST_API_KEY"))
result = client.extract_and_wait("invoice.pdf")
puts result.extraction.vendor_name
A household: what is left to pay
client.bills.list(paid: false).each do |bill|
  puts "#{bill.vendor_name}: #{bill.total_cents}, due #{bill.due_date}"
end

Rust

invoist on crates.io. Rust 1.88 or newer; async, with an optional blocking client. Source and full README on GitHub, and every class and method on docs.rs.

Install
cargo add invoist
A business: read an invoice
let client = invoist::Client::new(std::env::var("INVOIST_API_KEY").unwrap_or_default())?;
let file = invoist::UploadFile::from_path("invoice.pdf").expect("readable file");
let done = client.extract_and_wait(file, invoist::WaitOptions::default()).await?;
println!("{:?}", done.extraction.vendor_name);
A household: what is left to pay
let unpaid = client
    .bills()
    .list(invoist::ListBillsParams { paid: Some(false), ..Default::default() })
    .await?;

Coming soon

Libraries for Java / Kotlin and C# / .NET are written and tested, and will be on Maven Central and NuGet shortly. Until then, call the API over HTTP: the API introduction shows how.

Another language

The whole API is described in one OpenAPI file, kept in step with the API at github.com/invoisthq/invoist-openapi. Tools such as OpenAPI Generator turn it into a client for most languages. To import it into Postman or another tool that takes a URL, use the file's own address:

OpenAPI file
https://raw.githubusercontent.com/invoisthq/invoist-openapi/main/openapi.yaml

The same everywhere

  • Amounts are whole cents, never floating-point numbers.
  • A failed request raises one error type with the HTTP status, a stable code and the request id. Codes are listed in Errors and limits.
  • Connection failures, rate limits and server errors are retried twice, with a growing wait, or as long as the API asks (up to a minute).
  • Webhooks are checked with one call, from the raw request body. See Webhooks.