Quick Start - AP Agent

The Dolfin AP Agent lets your users review bills, correct extracted fields, manage suppliers, and approve payments through natural language. You upload the bill document via the direct API, then drive the rest of the workflow through POST /v1/agent/ap. This guide walks through the same bill flow as the AP Quick Start, but driven through the agent after the initial upload.

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

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

How the Agent Works

Every agent turn is a single POST to /agent/ap with just two body fields:

Field	Type	Notes
`message`	string, required	The user’s message for this turn
`conversationId`	UUID, optional	Omit on the first turn. Supply on every subsequent turn to continue the same thread

You do not send the full message history — Dolfin persists the conversation server-side and the agent loads it automatically from conversationId.

Response format

The response is a text/event-stream (SSE). Read events as they arrive:

Event	Payload	When
`conversation`	`{ "id": "uuid" }`	Fired once, on the first turn only, before any content
(unnamed)	`{ "content": "text chunk" }`	Streamed assistant text, one chunk per data frame
`action`	Tool action object	When the agent runs a tool (e.g. patched a bill)
(unnamed)	`{ "done": true }`	Final frame — stream is complete

On error, the final frame is { "error": "message", "done": true }.

Persisting `conversationId`

On the first request, read the conversation SSE event and save its data.id. Echo that UUID back as conversationId on every follow-up POST to continue the same conversation. See the AR Agent guide for an SSE parser example.

Once the first response returns a conversationId, the agent type is frozen on that conversation. Sending a request to POST /v1/agent/ar with an AP conversation’s conversationId (or vice versa) returns 409 Conflict.

Conversation scoping

Conversations are scoped by:

Organisation — always. A conversation belongs to the organisation in x-dolfin-organisation-id and can’t be read or continued from another organisation.
User — only when the call is authenticated with a Bearer JWT. API-key calls have no user binding, so any caller with the same API key and organisation can continue an API-key conversation.

Overview

Upload the bill (direct API)

Bill uploads are multipart file transfers, so Step 1 uses POST /v1/bills directly. After this, everything else runs through the agent.

Ask the agent to review the bill

Start a conversation by sending the bill’s ID to the agent. It loads the extracted fields and walks you through it.

Correct any fields (optional)

Tell the agent what’s wrong in natural language; it calls the patchBill tool to save your edits.

Submit for review and approve

The agent submits the bill for approval and, once approved, moves it to Approved.

Step 1: Upload the Bill (Direct API)

Bill uploads happen via POST /v1/bills as multipart/form-data. The document is read asynchronously.

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 { id: billId } = 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 hand it to the agent next. Wait for the state to move to PendingReview — subscribe to the bill.pending_review webhook, or poll GET /v1/bills/{id} — before talking to the agent.

Step 2: Ask the Agent to Review the Bill

This is the first turn of the conversation, so omit conversationId. Give the agent the bill ID and ask it to walk you through the extracted fields.

curl -N -X POST https://api.dolfinai.co/v1/agent/ap \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "I just uploaded bill b1234567-abcd-ef01-2345-6789abcdef01 — walk me through what was extracted."
  }'

const { conversationId } = await chat(
  'I just uploaded bill b1234567-abcd-ef01-2345-6789abcdef01 — walk me through what was extracted.',
);
// Persist conversationId — you need it for every subsequent turn.

SSE stream (excerpt):

event: conversation
data: {"id":"a7e1f3b2-9c0d-4e8a-b6f5-3d2e4f7c8a91"}

event: action
data: {"type":"bill.retrieved","billId":"b1234567-abcd-ef01-2345-6789abcdef01", ...}

data: {"content":"Here's what was extracted from that bill:"}

data: {"content":"\n\n- **Supplier:** Acme Supplies Ltd"}

...

data: {"done":true}

The agent replies with a summary:

Here’s what was extracted from that bill:

Supplier: Acme Supplies Ltd ([email protected])

Invoice number: ACM-2025-0142

Invoice date: 15 Jan 2025

Due date: 14 Feb 2025

Currency: GBP

Subtotal: £480.00

Tax: £96.00

Total: £576.00

Line items:

Bulk stationery order × 10 @ £48.00 (20% tax)

Extraction confidence is 0.94. Anything you’d like me to correct before we submit for review?

Step 3: Correct Any Fields (Optional)

Tell the agent what’s off. It’ll call the patchBill tool for you — no need to craft a patch payload by hand.

curl -N -X POST https://api.dolfinai.co/v1/agent/ap \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "conversationId": "a7e1f3b2-9c0d-4e8a-b6f5-3d2e4f7c8a91",
    "message": "Invoice number should be ACM-2025-00142, and add bank details: account 12345678, sort code 20-00-00, GB/GBP."
  }'

await chat(
  'Invoice number should be ACM-2025-00142, and add bank details: account 12345678, sort code 20-00-00, GB/GBP.',
  conversationId,
);

The agent calls patchBill, emits an action event, and confirms:

Done — I’ve updated:

Invoice number: ACM-2025-00142

Bank details: Acme Supplies Ltd · Account 12345678 · Sort 20-00-00 · GB / GBP

Ready to submit for review?

The agent can only edit bills in PendingReview — matching the direct-API rule. If extraction is still running, ask again in a few seconds.

Step 4: Submit for Review and Approve

When the data looks right, have the agent submit the bill and then approve it.

Submit for review

curl -N -X POST https://api.dolfinai.co/v1/agent/ap \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "conversationId": "a7e1f3b2-9c0d-4e8a-b6f5-3d2e4f7c8a91",
    "message": "Yes, submit for review."
  }'

await chat('Yes, submit for review.', conversationId);

The agent confirms and calls submitBillReview:

Submitted. The bill is now in NeedsApproval — Acme Supplies Ltd is linked as the supplier. Ready for you to approve?

Supplier auto-resolution. When the agent submits a bill, Dolfin resolves the supplier in this order: an explicit supplierId you set → an existing supplier on the organisation whose tax ID or email matches → a new supplier created from the extracted data (requires at minimum supplierName and supplierEmail). If the agent doesn’t have enough data to resolve or create a supplier, submit-review returns 400 Bad Request.

Approve

curl -N -X POST https://api.dolfinai.co/v1/agent/ap \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "conversationId": "a7e1f3b2-9c0d-4e8a-b6f5-3d2e4f7c8a91",
    "message": "Approve it."
  }'

await chat('Approve it.', conversationId);

The agent runs approveBill and confirms:

Approved. The bill is now in Approved and ready for payment scheduling. Want me to schedule the payment now?

The agent can also schedule the payment (schedulePayment) and confirm payment (confirmPaid) via further turns.

Rejecting a bill. The AP agent can’t reject bills — rejection is a direct-API-only call via POST /v1/bills/{id}/reject. Use the AP Quick Start for that flow.

Full Conversation Flow

Turn	`conversationId` sent?	User message
1	No (first turn)	“I just uploaded bill `{id}` — walk me through what was extracted.”
2	Yes	”Invoice number should be ACM-2025-00142, and add bank details…“
3	Yes	”Yes, submit for review.”
4	Yes	”Approve it.”

Managing Conversations

Endpoint	Purpose
`GET /agent/conversations?agentType=Ap`	List the caller’s AP conversations
`GET /v1/agent/conversations/{id}`	Get metadata for a single conversation
`GET /v1/agent/conversations/{id}/messages`	Paged message history
`PATCH /v1/agent/conversations/{id}`	Rename a conversation
`DELETE /v1/agent/conversations/{id}`	Delete a conversation and its messages

Agent vs Direct API

	Direct API	AP Agent
Upload	`POST /v1/bills` (multipart)	Same — agent doesn’t handle file upload
Review / patch	Craft a `PATCH /v1/bills/{id}` body by hand	Describe the changes in plain English
Submit / approve	Sequential endpoint calls	Single-turn natural language requests
Reject	`POST /v1/bills/{id}/reject`	Direct API only

Getting started

Accounts Payable

Accounts Receivable

Quick Start - AP Agent

Prerequisites

How the Agent Works

Response format

Persisting `conversationId`

Conversation scoping

Overview

Step 1: Upload the Bill (Direct API)

Step 2: Ask the Agent to Review the Bill

Step 3: Correct Any Fields (Optional)

Step 4: Submit for Review and Approve

Submit for review

Approve

Full Conversation Flow

Managing Conversations

Agent vs Direct API

Next Steps

AP Quick Start (Direct API)

API Reference

​Prerequisites

​How the Agent Works

​Response format

​Persisting conversationId

​Conversation scoping

​Overview

​Step 1: Upload the Bill (Direct API)

​Step 2: Ask the Agent to Review the Bill

​Step 3: Correct Any Fields (Optional)

​Step 4: Submit for Review and Approve

​Submit for review

​Approve

​Full Conversation Flow

​Managing Conversations

​Agent vs Direct API

​Next Steps

AP Quick Start (Direct API)

API Reference

Prerequisites

How the Agent Works

Response format

Persisting `conversationId`

Conversation scoping

Overview

Step 1: Upload the Bill (Direct API)

Step 2: Ask the Agent to Review the Bill

Step 3: Correct Any Fields (Optional)

Step 4: Submit for Review and Approve

Submit for review

Approve

Full Conversation Flow

Managing Conversations

Agent vs Direct API

Next Steps