Vendors

Vendors represent the people and businesses you pay. They are linked to bills, purchase orders, and payment records.

Create a Vendor

curl -X POST "https://api.ondayzero.com/api/v1/vendors" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office Depot",
    "email": "ap@officedepot.com",
    "phone": "+1-555-0200",
    "address": "456 Supply Rd, Austin, TX 78701",
    "default_payment_term_id": "PAYMENT_TERM_UUID"
  }'

The response is the created vendor (status 201):

{
  "success": true,
  "data": {
    "id": "0198a2c4-0000-7d3a-9a51-3f6f0c1d2e30",
    "business_id": "0198a2c4-0000-7d3a-9a51-3f6f0c1d2e00",
    "name": "Office Depot",
    "email": "ap@officedepot.com",
    "phone": "+1-555-0200",
    "status": "active",
    "default_payment_term_id": "0198a2c4-0000-7d3a-9a51-3f6f0c1d2e44",
    "registry_id": null,
    "is_deleted": false,
    "contacts": [],
    "created_at": "2026-03-01T14:02:11Z",
    "updated_at": "2026-03-01T14:02:11Z"
  }
}

name and email are required, and each email must be unique within the business: reusing one returns 409 (CONFLICT_006). Optional: tax_id, website, notes, category, status (active — the default — inactive or blocked), credit_limit_cents and default_payment_term_id (see Payment Terms).

default_payment_term_id must be a term of this business, on create and on update (otherwise 404 NOT_FOUND_001). PUT changes it to another term; null clears it; leaving the field out keeps the current term. It is used as a default, never forced:

• new purchase orders for the vendor take it when they don't name a payment_term_id;
• the app's bill form suggests the bill's due date from it;
• when the business counts terms from the receipt date (ap_due_date_basis: received_date), bills arriving through the AP inbox or a document upload are dated from it.

The bill API does not apply it: send due_on, and payment_term_id if you want the term recorded, on each bill. The Payment Terms page is switched off in the DayZero app for now and new businesses start with no terms, so create or seed them through the Payment Terms API before setting this field.

List Vendors

curl "https://api.ondayzero.com/api/v1/vendors?search=office&limit=25" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Filter Parameters

Plus the standard pagination parameters (sort_by accepts any vendor column, e.g. name or created_at). Soft-deleted vendors are left out of the list.

A vendor response carries the fields above plus id, business_id, created_at, updated_at, registry_id / registry_name (the linked counterparty registry entry, if any), default_location_id / default_location_name, is_deleted and contacts. A single-vendor GET also returns approval_route and approval_routes (the vendor's AP approval routes).

Get a Vendor

curl "https://api.ondayzero.com/api/v1/vendors/{vendor_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Update a Vendor

curl -X PUT "https://api.ondayzero.com/api/v1/vendors/{vendor_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office Depot Inc.",
    "website": "https://officedepot.com"
  }'

Contacts

Each vendor can have multiple contacts:

curl -X POST "https://api.ondayzero.com/api/v1/vendors/{vendor_id}/contacts" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@officedepot.com",
    "role": "Account Manager",
    "is_primary": true
  }'

Only name is required; email, phone, role (max 100 chars) and notes are optional. List contacts: GET /api/v1/vendors/{vendor_id}/contacts. Fetch, update or remove one with GET / PUT / DELETE /api/v1/vendors/{vendor_id}/contacts/{contact_id}.

Bulk Upload

Download the CSV template with GET /api/v1/vendors/bulk-upload/template (returns the CSV as csv_content_stringified and csv_content_base64), then import:

curl -X POST "https://api.ondayzero.com/api/v1/vendors/bulk-upload" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -F "file=@vendors.csv"

CSV columns: name, email, phone, address, tax_id, website, notes, category, status, credit_limit (in dollars, not cents). name and email are required, and a file may hold up to 1,000 data rows. Rows whose email appears earlier in the file or already exists are skipped. The response includes created and skipped counts and any row-level errors.

Duplicate Detection

Check for similar existing vendors before creating:

curl "https://api.ondayzero.com/api/v1/vendors/check-duplicates?name=Office%20Depot&email=ap@officedepot.com" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Returns has_duplicates and a duplicates list of matches with similarity_score (0.0-1.0) and match_type (name, email, tax_id or phone). name is required; email, tax_id and exclude_id are optional.

Delete a Vendor

curl -X DELETE "https://api.ondayzero.com/api/v1/vendors/{vendor_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Deletion is a soft delete: the vendor is hidden from list results but remains retrievable by ID so existing bills and other records stay intact. Deleting an already-deleted vendor returns 404.

Common errors