WFDASH-WEBAPP/docs/api-reference/quote-create-and-customer-lookup.md

WFDASH API — Quote Create + Customer Lookup Reference

What the WFDASH REST/MCP API actually exposes today for the two tasks you keep hitting during intake: creating a quote, and finding an existing customer.

---

Quote create — three flavours

There are three different quote-creation endpoints. Pick by where the data came from, not by what feels closest:

1. quotes.create (walk-in) — the one for your intake

POST /api/v1/quotes/create

• Use when: there's no inbound RFQ email. Operator types it in, you extracted items from a PDF / phone-call / WhatsApp, or you're driving the quote from the in-store counter PWA.
• Body has customer (id OR name), company (id OR name), and items[]. Names are resolved case-insensitive exact — if there's no match, a new customer / company row is created with empty defaults. So passing a name is safe; passing the wrong name silently creates a duplicate.
• Returns { quote, customer, company, items, quote_number } on 201.
• Status default is "new". quote_number is auto-generated unless you supply one (operator-supplied conflicts return 409).
• MCP wrapper: mcp__wfdash-mcp__quotes__create. Same body shape.

2. quotes.ingest_from_email (inbound RFQ email)

POST /api/v1/quotes/ingest-from-email

• Use when: the customer actually emailed in. Returns immediately with ai_status="pending"; the background processor runs Claude against the body + attachments to extract items. Don't extract items yourself — let the pipeline do it.
• MCP wrapper: mcp__wfdash-mcp__quotes__ingest_from_email.

3. quotes.create_from_email (legacy, avoid)

POST /api/v1/quotes/create-from-email

• Caller passes a pre-extracted extracted_items[]. Only use this if you're calling on behalf of a parser that already did the extraction. Wrong tool if you don't have an inbound email — it requires subject + parsed body and silently rewrites email_message_id to a synth-…@wfdash.local sentinel.
• MCP wrapper: mcp__wfdash-mcp__quotes__create_from_email.

---

Customer lookup — fuzzy search by name / company

customers.list — substring search

GET /api/v1/customers

Query params:

Param	Type	What it does
search	string	Substring match on customer name / email / phone, OR'd together; also matches rep name / rep email (the user that owns this customer). One query covers all four fields. Case-sensitive PB ~ operator.
rep	string	Exact filter on the rep relation. Accepts a 15-char PB user id OR a user name / email (case-insensitive).
page	number	1-based, default 1
perPage	number	default 50, hard cap 100
sort	string	PB sort expression, default -created
expand	string	Comma-separated, e.g. "company,rep" to inline relations

Returns { items, totalItems, totalPages, page, perPage }.

MCP wrapper: mcp__wfdash-mcp__customers__list. Same params.

customers.get — fetch by id

GET /api/v1/customers/{id}

For when you already have the PB id and just need the full row + relations.

MCP wrapper: mcp__wfdash-mcp__customers__get.

What we DO NOT have today

• No direct "filter customers by company name" on customers.list. The search param doesn't search across the company relation. Two workarounds:

  1. Pass expand: "company" on the list call, then filter the returned items[] client-side by company name.
  2. First companies.list({search: "<name>"}) to get the company id, then iterate the matching customers client-side. (The customers.list search filter does not accept a company relation id today.)

• No dedicated customers.lookup endpoint — customers.list with a small perPage (e.g. 5) is the closest equivalent.

• No fuzzy / Levenshtein matching. It's PB's literal substring ~ operator. "AB" won't match "ABC Trading" if you typed it wrong-case, and partial-token matches like "Bear" against "Bearings Co" will work — but "Bearings" against "Bear" works too (substring is bidirectional). Typos are not forgiven.

---

The intake pattern that works

Given what we have, the cleanest customer-resolution flow at intake is:

// 1. Try the most specific lookup first.
const hit = await customers.list({
  search: customerName,
  expand: "company",
  perPage: 5,
});

// 2. If the caller ALSO gave a company name, narrow client-side.
const filtered = companyName
  ? hit.items.filter(c => c.expand?.company?.company === companyName)
  : hit.items;

// 3. If 0 hits → create via customers.create (auto-creates company
//    if company name doesn't resolve either). Use quotes.create with
//    the names directly — it has the same auto-create behaviour, so
//    you don't need a separate customers.create call unless you want
//    to backfill email/phone/etc.

For quote creation specifically, just pass customer and company as names to quotes.create — the service layer resolves them by case-insensitive exact match and creates missing rows. You only need the lookup step when:

• You're filling in email / phone from a contact form.
• You want to verify the customer exists before showing the operator a "is this the right John Smith?" confirmation.
• You're merging two customer records.

---

Companies (related, since you mentioned name + company)

companies.list — substring search

GET /api/v1/companies

Query params: page, perPage, search (substring on company.company / address / vendor), sort. Same shape as customers.list.

MCP wrapper: mcp__wfdash-mcp__companies__list.

companies.get — fetch by id

GET /api/v1/companies/{id}

MCP wrapper: mcp__wfdash-mcp__companies__get.

companies.create / companies.update

Free-text company name, optional address / vendor / coordinates. Same auto-resolve-and-create-on-no-match behaviour as customers.