Quick Start - AP - Dolfin AI

This guide walks through the end-to-end flow of processing a bill via the Dolfin API. You’ll get a bill into Dolfin — either by forwarding it to a dedicated email address or by uploading it through the API — optionally correct any fields the extraction got wrong, submit the bill for review, and let your approval policies decide whether it auto-approves or routes to an approver.

Prerequisites

A Dolfin API key
An organisation already provisioned (see Client Integration)
A valid session token or API key for authentication
A bill PDF or image file to upload (or an email inbox to forward from)

All requests below require the x-dolfin-api-key and x-dolfin-organisation-id headers. See Authentication for details.

Overview

Get the bill into Dolfin

Either forward it to your organisation’s inbound email address, or upload it via POST /v1/bills. Both create a bill and read the document asynchronously.

Patch extracted fields (optional)

Fix any fields the extraction got wrong while the bill is in PendingReview.

Submit for review

Submit the bill. Your approval policies decide the next state — auto-approve, route for approval, or void.

Approve or reject

An approver takes the final call on any bill that lands in NeedsApproval.

Bill lifecycle

A bill moves through these states:

                                                 ┌─ AutoApprove ─→ Approved → Scheduled → Paid
Created → Extracting → PendingReview → (submit) ─┼─ AlwaysReview ─→ NeedsApproval ─→ Approved
        ↘ ExtractionFailed                       └─ AutoVoid ────→ Voided        ↘ Rejected

The branch after submit for review is decided by your approval policies. With no policies configured, every bill with a resolved supplier goes to NeedsApproval (the safe default).

Step 1: Get a Bill into Dolfin

There are two ways to bring a bill in. Both end up in the same place: a bill in Extracting that moves to PendingReview once the document has been read.

Option A — Forward it by email

Every organisation has a dedicated inbound email address. Forward supplier bills to it (or ask suppliers to send them there directly) and Dolfin ingests the attachments, creating one bill per document — no code required. Fetch the address with GET /v1/bills/inbound-email-address:

curl https://api.dolfinai.co/v1/bills/inbound-email-address \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"

const { address } = await fetch(
  'https://api.dolfinai.co/v1/bills/inbound-email-address',
  {
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    },
  },
).then(r => r.json());

Response (200 OK):

{
  "address": "[email protected]"
}

Surface this address in your UI with a copy button so users can save it as a contact. Any email sent to it with a PDF or image attachment becomes a bill.

Sender allowlisting. To stop a leaked address being abused, Dolfin only auto-ingests mail from allowed senders — your organisation’s own users are trusted automatically, and you can add colleagues or suppliers explicitly. Mail from an unknown sender is quarantined for a human to approve rather than silently accepted or bounced, so a genuine bill from a new address is never lost.

Option B — Upload it via the API

Upload the bill document as multipart/form-data. The document is read asynchronously, so the response returns immediately with the new bill’s id and initial state.

curl -X POST https://api.dolfinai.co/v1/bills \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -F "file=@./acme-invoice-2025-01.pdf"

import fs from 'node:fs';

const form = new FormData();
form.append(
  'file',
  new Blob([fs.readFileSync('./acme-invoice-2025-01.pdf')], {
    type: 'application/pdf',
  }),
  'acme-invoice-2025-01.pdf',
);

const bill = await fetch('https://api.dolfinai.co/v1/bills', {
  method: 'POST',
  headers: {
    'x-dolfin-api-key': 'dol_live_abc123',
    'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
  },
  body: form,
}).then(r => r.json());

Response (202 Accepted):

{
  "id": "b1234567-abcd-ef01-2345-6789abcdef01",
  "state": "Extracting"
}

Save the bill id — you’ll use it in every subsequent call. The bill starts in Extracting and automatically moves to PendingReview once the document has been read. Subscribe to the bill.pending_review webhook to be told when, or poll GET /v1/bills/{id}.

Wait for extraction to finish

Whether the bill arrived by email or upload, its fields aren’t populated until the document has been read. There are two ways to find out when that’s done. Recommended — subscribe to a webhook. Dolfin posts bill.pending_review to your endpoint the moment extraction completes, with the full bill in the payload, so there’s nothing to poll and no follow-up call to make. Subscribe to bill.ocr_failed too, to catch documents that couldn’t be read. See the webhooks guide to set one up. Otherwise — poll the bill. If you don’t have an endpoint to receive webhooks, fetch the bill until it leaves Extracting. Forwarded bills don’t return an id to you directly — list recent bills with GET /v1/bills to find them.

curl https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01 \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"

const bill = await fetch(
  'https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01',
  {
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    },
  },
).then(r => r.json());

Once the state is PendingReview, the extracted fields are populated on the bill:

{
  "id": "b1234567-abcd-ef01-2345-6789abcdef01",
  "state": "PendingReview",
  "supplierName": "Acme Supplies Ltd",
  "supplierEmail": "[email protected]",
  "invoiceNumber": "ACM-2025-0142",
  "invoiceDate": "2025-01-15T00:00:00Z",
  "dueDate": "2025-02-14T00:00:00Z",
  "currency": "GBP",
  "subTotal": "480.00",
  "taxAmount": "96.00",
  "totalAmount": "576.00",
  "confidence": 0.94,
  "lineItems": [
    {
      "id": "li-0001",
      "description": "Bulk stationery order",
      "quantity": "10",
      "unitPrice": "48.00",
      "taxRate": "20",
      "taxAmount": "96.00",
      "subTotal": "480.00"
    }
  ]
}

If the state becomes ExtractionFailed, the document couldn’t be read. Call POST /v1/bills/{id}/retry-ocr to try again.

Extraction methods. Dolfin can read bill documents with either OCR or LLM vision extraction. Which one your account uses is configured per client — contact us to switch. The states, fields, and events are identical either way.

Step 2: Patch Extracted Fields (Optional)

Extraction isn’t perfect. If any fields came out wrong — the supplier name, invoice number, amounts, line items, bank details — patch them while the bill is in PendingReview.

curl -X PATCH https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01 \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceNumber": "ACM-2025-00142",
    "totalAmount": "576.00",
    "accountHolderName": "Acme Supplies Ltd",
    "accountNumber": "12345678",
    "sortCode": "20-00-00",
    "bankCountry": "GB",
    "bankCurrency": "GBP"
  }'

const patched = await fetch(
  'https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01',
  {
    method: 'PATCH',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      invoiceNumber: 'ACM-2025-00142',
      totalAmount: '576.00',
      accountHolderName: 'Acme Supplies Ltd',
      accountNumber: '12345678',
      sortCode: '20-00-00',
      bankCountry: 'GB',
      bankCurrency: 'GBP',
    }),
  },
).then(r => r.json());

Only the fields you include are updated — everything else stays as extracted. You can only patch bills in PendingReview; attempts against any other state return 409 Conflict.

To link the bill to an existing supplier record, set supplierId to the supplier’s UUID. Otherwise the free-text supplierName, supplierEmail, etc. are kept as-is and used for supplier resolution when you submit for review (see Step 3).

Step 3: Submit for Review

Once the extracted data is correct, submit the bill. This runs supplier resolution and then evaluates your approval policies to decide the bill’s next state.

Supplier resolution

When you submit a bill for review, Dolfin resolves the bill’s supplier in this order:

If you set supplierId explicitly (via patch), that supplier is used.
Otherwise, Dolfin looks for an existing supplier on the organisation whose tax ID or email matches the extracted value and links to it.
If no match is found, a new supplier is created from the extracted data. This requires at minimum supplierName and supplierEmail — fill these via PATCH /v1/bills/{id} in Step 2 if extraction didn’t capture them. Any other extracted details (phone, address, website, tax ID, bank details) are copied onto the new supplier too.

If the bill has no linked supplier and not enough data to create one, submit-review returns 400 Bad Request.

curl -X POST https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01/submit-review \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"

const submitted = await fetch(
  'https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01/submit-review',
  {
    method: 'POST',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    },
  },
).then(r => r.json());

How approval policies steer the bill

At submit time, Dolfin evaluates your organisation’s ordered list of approval policies against the resolved bill (its amount, currency, supplier, and supplier standing). The highest-priority matching policy decides the outcome:

Policy action	Resulting state	Meaning
`AutoApprove`	`Approved`	Trusted bill — skips review entirely and is ready for payment.
`AlwaysReview`	`NeedsApproval`	Routed to the policy’s approvers (or any admin) for a decision.
`AutoVoid`	`Voided`	Hard stop — e.g. a blocked supplier or unsupported currency.

If no policy matches, the bill goes to NeedsApproval — the safe default. The response reflects the state the winning policy produced:

{
  "id": "b1234567-abcd-ef01-2345-6789abcdef01",
  "state": "NeedsApproval",
  "invoiceNumber": "ACM-2025-00142",
  "totalAmount": "576.00",
  "currency": "GBP"
}

See the Approval Policies guide to configure auto-approve thresholds, per-supplier rules, and named approvers. A bill that auto-approves lands in Approved and skips Step 4.

Using purchase orders or delivery notes? When a bill matches against a PO or delivery note, Dolfin creates a match group, and a bill cannot leave review for approval while its match group is unresolved — any price or quantity variance must be resolved first. See the Three-way Matching guide.

Step 4: Approve or Reject

With the bill in NeedsApproval, an approver takes the final call.

Approve

curl -X POST https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01/approve \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"

const approved = await fetch(
  'https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01/approve',
  {
    method: 'POST',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
    },
  },
).then(r => r.json());

Response:

{
  "id": "b1234567-abcd-ef01-2345-6789abcdef01",
  "state": "Approved",
  "approvedBy": "u5678901-abcd-ef01-2345-6789abcdef01",
  "approvedAt": "2025-01-20T09:10:00Z"
}

An approved bill is ready for payment scheduling via POST /v1/bills/{id}/schedule-payment.

Reject

If something’s off, reject the bill with an optional reason.

curl -X POST https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01/reject \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Duplicate of ACM-2025-00141"
  }'

const rejected = await fetch(
  'https://api.dolfinai.co/v1/bills/b1234567-abcd-ef01-2345-6789abcdef01/reject',
  {
    method: 'POST',
    headers: {
      'x-dolfin-api-key': 'dol_live_abc123',
      'x-dolfin-organisation-id': '9a658587-fe02-402e-b1ac-bfaf53274ef8',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reason: 'Duplicate of ACM-2025-00141',
    }),
  },
).then(r => r.json());

Response:

{
  "id": "b1234567-abcd-ef01-2345-6789abcdef01",
  "state": "Rejected",
  "rejectedBy": "u5678901-abcd-ef01-2345-6789abcdef01",
  "rejectedAt": "2025-01-20T09:10:00Z",
  "rejectionReason": "Duplicate of ACM-2025-00141"
}

A rejected bill can be re-opened for editing with POST /v1/bills/{id}/reopen, which returns it to PendingReview.

Summary

Step	Endpoint	What it does
1a	`GET /v1/bills/inbound-email-address`	Fetch the address suppliers forward bills to
1b	`POST /v1/bills`	Upload a bill document; the document is read asynchronously
2	`PATCH /v1/bills/{id}`	Correct any fields extraction got wrong (optional)
3	`POST /v1/bills/{id}/submit-review`	Resolve supplier, evaluate approval policies, transition state
4a	`POST /v1/bills/{id}/approve`	Approve the bill for payment
4b	`POST /v1/bills/{id}/reject`	Reject with an optional reason

Next Steps

Approval Policies

Auto-approve trusted bills and route the rest to the right approver.

Three-way Matching

Match bills against purchase orders and delivery notes before approval.

Supplier Credit Notes

Record credit a supplier owes you and net it against bills.

API Reference

Explore the full Bills API, including payment scheduling and file URLs.

Getting started

Accounts Payable

Accounts Receivable

Quick Start - AP

Prerequisites

Overview

Bill lifecycle

Step 1: Get a Bill into Dolfin

Option A — Forward it by email

Option B — Upload it via the API

Wait for extraction to finish

Step 2: Patch Extracted Fields (Optional)

Step 3: Submit for Review

Supplier resolution

How approval policies steer the bill

Step 4: Approve or Reject

Approve

Reject

Summary

Next Steps

Approval Policies

Three-way Matching

Supplier Credit Notes

API Reference

​Prerequisites

​Overview

​Bill lifecycle

​Step 1: Get a Bill into Dolfin

​Option A — Forward it by email

​Option B — Upload it via the API

​Wait for extraction to finish

​Step 2: Patch Extracted Fields (Optional)

​Step 3: Submit for Review

​Supplier resolution

​How approval policies steer the bill

​Step 4: Approve or Reject

​Approve

​Reject

​Summary

​Next Steps

Approval Policies

Three-way Matching

Supplier Credit Notes

API Reference

Prerequisites

Overview

Bill lifecycle

Step 1: Get a Bill into Dolfin

Option A — Forward it by email

Option B — Upload it via the API

Wait for extraction to finish

Step 2: Patch Extracted Fields (Optional)

Step 3: Submit for Review

Supplier resolution

How approval policies steer the bill

Step 4: Approve or Reject

Approve

Reject

Summary

Next Steps