API Reference
Vendors
Vendors are the suppliers, merchants, contractors, and contacts you pay through bills and expense transactions. A vendor holds contact details, an optional address, 1099 tax settings, and status.
Last updated 2026-11-18
Overview
The Vendors API lets your integration list, create, update, and delete vendors in a workspace. Vendors represent anyone you pay — suppliers, merchants, contractors, and other contacts.
Partner responses expose each vendor UUID as `id` and remove internal numeric identifiers and foreign keys such as `teamId`.
Key concepts
Identification
Vendors are referenced by UUID returned as `id`. Pass that value in the path to update or delete.
Required fields
Only `name` is required to create a vendor. Address and contacts can be supplied inline.
Duplicate handling
Creating a vendor with a name that matches an active vendor returns 400. Creating with a name that matches an inactive vendor reactivates and updates that record.
1099 vendors
Set `is1099` and related tax fields for contractor reporting. The API validates 1099 field combinations on create and update.
The vendor object
Fields returned on a vendor. Address and contacts are embedded when present.
Attributes
iduuidVendor identifier (UUID). Use in path parameters for update and delete.
namestringVendor display name. Required on create.
emailstringPrimary email address.
mainPhonestringPrimary phone number.
websitestringWebsite URL.
accountNumberstringYour internal vendor account number.
statusenumVendor status. Defaults to active.
One of: active, inactive
typeenumVendor classification. Defaults to MERCHANT.
One of: MERCHANT, SUPPLIER, CONTRACTOR, CONTACT, OWNER
legalNamestringLegal entity name for tax reporting.
businessNamestringDoing-business-as name when different from legal name.
taxNumberstringTax identification number.
taxTypeenumTax id type.
One of: none, ssn, ein, itin, atin
is1099booleanWhether the vendor receives 1099 reporting.
addressobjectMailing address, or null.
streetstringStreet address.
citystringCity or locality.
statestringState, province, or region.
zipCodestringPostal or ZIP code.
countrystringCountry name or ISO code.
contactsarrayContact people for this vendor.
iduuidContact identifier (UUID).
firstNamestringContact's first name.
lastNamestringContact's last name.
emailstringContact's email address.
phonestringContact's phone number.
isPrimarybooleanMarks the primary contact.
createdAtdatetimeISO 8601 creation timestamp.
updatedAtdatetimeISO 8601 last update timestamp.
{
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"name": "Office Depot",
"email": "ap@officedepot.com",
"mainPhone": "+18001234567",
"website": "https://officedepot.com",
"accountNumber": "V-1001",
"status": "active",
"type": "SUPPLIER",
"legalName": "Office Depot Inc.",
"businessName": null,
"taxNumber": null,
"taxType": "none",
"is1099": false,
"address": {
"street": "500 Supply Chain Blvd",
"city": "Boca Raton",
"state": "FL",
"zipCode": "33431",
"country": "USA"
},
"contacts": [
{
"id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67",
"firstName": "Accounts",
"lastName": "Payable",
"email": "ap@officedepot.com",
"phone": "+18001234567",
"isPrimary": true
}
],
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-28T14:22:30.000Z"
}Search covers name, account number, and contact email
The `search` query parameter on list matches vendor name, account number, and contact email addresses (case-insensitive, partial).Contractor-linked vendors
Vendors linked to a payroll contractor person record have restricted update fields. Attempts to change protected keys return 400.Recent changes
Incremental sync: updatedSince on every list endpoint, includeDeleted, and the deleted-records feed
Every Partner API list endpoint now takes updatedSince, so an integration can pull only what changed instead of re-reading whole lists. Pass an ISO 8601 date-time and the list returns the records created or changed at or after it, oldest change first, with nextUpdatedSince and hasMore beside the rows; pass nextUpdatedSince back as updatedSince to read the next page, and keep it for the next poll once hasMore is false. Paging by cursor means a record changed mid-walk can no longer move between pages and be skipped, so updatedSince cannot be combined with page above 1 or a sort. includeDeleted=true returns deleted records with isDeleted: true on vendors, customers, products, people, taxes, projects, project tasks, tasks, time entries, recurring invoice templates, the chart of accounts, transactions, invoices, and bills. The chart of accounts returns a flat list of changed accounts in this mode, each naming its parent in parentAccountUuid. Records removed outright — tags, tag groups, journal entry lines, expense receipts, customer contacts, addresses and notes, budgets, and any other hard delete — are listed by the new GET /partners/deleted-records, which keeps 90 days. updatedFrom and updatedTo stay on transactions, invoices, and bills, now read as UTC when they carry no offset. The new Keeping in Sync guide (/guides/keeping-in-sync) puts the pieces together into a 15-minute poll with a sync-now button. The MCP catalog adds COUNT_list_deleted_records, and every list tool takes updatedSince (and includeDeleted where it applies) under query.
Accounting Playbooks and Ledger Semantics published as documentation
The workflows and behaviour rules the MCP server serves to agents through COUNT_playbooks and COUNT_knowledge are now readable documentation. Accounting Playbooks (/guides/playbooks) covers nine ordered workflows across 54 steps — invoicing, credit memos, recurring templates, vendor bill payment, chart-of-accounts setup, migration imports, budget planning and round-trip, and month-end review — each naming the exact tool per step. Ledger Semantics & Lifecycles (/guides/ledger-semantics) documents 33 confirmed behaviours across twelve resources: the state each operation is valid in, the fields accepted and then ignored, and the calls that cannot be undone, with every irreversible behaviour collected in one table at the top of the page. Both pages carry the COUNT_playbooks and COUNT_knowledge ids they were ported from so the agent-facing and human-facing copies stay in step. Playbooks, lifecycle sections, and individual behaviour rules are indexed into site search.
Complete Partner API reference
Documented all remaining API reference groups: Chart of Accounts, Vendors, Products & Services, Recurring Invoice Templates, Credit Memos, Bills, Journal Entries, Tags, People, Projects, Tasks, Time Entries, Expense Receipts, Reports, and Workspace Stats. Added missing invoice endpoints (audit log, attachments, credit application, remove transaction) and group overviews for Invoices and Transactions.
Endpoints
/partners/vendorsReturns a paginated list of vendors in the workspace.
/partners/vendorsCreates a new vendor in the workspace.
/partners/vendors/{uuid}Updates an existing vendor. Only the fields you send are changed.
/partners/vendors/{uuid}Deletes a vendor by UUID.
