Bookkeeping

Vendors

The people and companies the business pays. Bills and expenses point at a vendor.

List and search vendors

Scope: vendors:read or vendors:write. Filter by q (name contains, ignoring case), external_id, or status (active, inactive, archived). Page with limit (up to 200) and offset; next_offset is null on the last page.

GET

curl "https://api.helloledger.ai/v1/companies/{company_id}/vendors?q=staples&limit=50" \
  -H "Authorization: Bearer $HL_API_KEY"

One vendor · GET

curl "https://api.helloledger.ai/v1/companies/{company_id}/vendors/66f1a2b3c4d5e6f708092a01" \
  -H "Authorization: Bearer $HL_API_KEY"

Create a vendor

Scope: vendors:write. Only name is required. Names are unique per company: creating a name that exists (ignoring case) returns 409 vendor_exists with the existing vendor_id in the message.

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/vendors" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Idempotency-Key: vend_8812" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Staples",
  "email": "ap@staples.example",
  "phone": "555-0101",
  "payment_terms": "Net 30",
  "is_1099_eligible": false,
  "external_id": "vend_8812"
}'

Response (201)

{
  "vendor_id": "66f1a2b3c4d5e6f708092a01",
  "external_id": "vend_8812",
  "name": "Staples",
  "email": "ap@staples.example",
  "phone": "555-0101",
  "payment_terms": "Net 30",
  "is_1099_eligible": false,
  "tags": ["vendor"],
  "status": "active",
  "needs_review": false,
  "result": "created"
}

Update a vendor

Send only the fields to change. Renaming to a name another vendor already has returns 409 vendor_exists.

PATCH

curl -X PATCH "https://api.helloledger.ai/v1/companies/{company_id}/vendors/66f1a2b3c4d5e6f708092a01" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "555-0199",
  "address_line1": "500 Main St",
  "city": "Austin",
  "state": "TX"
}'

Fields

Field	Notes
name	Required on create. Up to 200 characters.
email, phone	Contact details.
address_line1, address_line2, city, state, zip, country	Mailing address.
tax_id, is_1099_eligible	For 1099 reporting.
payment_terms, vendor_type, notes	Free text.
metadata	Up to 20 string key/value pairs.
external_id	Your ID for the vendor, stored for reference.
status	active, inactive, or archived.
needs_review	Read only. True when HelloLedger created the vendor from a bill or expense.