Quote Links for AI assistants

What to ask, and what comes back

• job: the job in words, as the user said it ("fix a running toilet", "install a ceiling fan").
• where: where the job is, as "City, ST" ("Austin, TX"), a state, or a New York City borough. Leave it out for the national figure.
• business (optional): the user's business name. When two trades do the same job, its trade wins.
• To reprice it: rate (the user's own hourly rate), markup (percent on parts), travel=on with miles and minutes, and the user's own hours or parts cost for this job.

It answers with the one job it matched, priced for that place: what the job includes, its hours, its parts, the markup and the price. The hours are Workeey's starting guess. The hourly rate starts from BLS data on what employees in that trade are paid and what employers pay on top, for that place or, where there is no figure, the state's or the nation's. The parts are online shelf prices, each with its product page; the ones nobody could check say so. Every source comes with the day it was checked.

The answer's draft_link is a ready-made link (way 1) with that job and price already in it: the user opens it, adds their business name and the customer's name, and presses Create approval link. If you already have those, write the link yourself with this price.

If the answer has an ask, two jobs match about equally (a toilet repair, or a new toilet?): ask the user which, then ask again with its name. With no match, it lists the closest jobs to ask about. A trade_note says another trade prices the same job at its own rate.

Show the user the price, where it comes from and the answer's honesty line, and let them change it. Put a price in the quote only once they agree: these are starting points, not what other businesses charge.

For every job of one trade at once, ask with trade instead: plumbing, electrical, hvac, handyman, cleaning or landscaping, with state (a two-letter code) or metro (a BLS area code inside that state), and per job hours.<job id> or parts.<job id>:

https://www.workeey.com/api/price-check?trade=plumbing&state=NY

The simple link

After #, write name=value pairs joined by &, in the order a person would read the quote. Write a space as +.

• Who and what: business, customer (a display name only), job, and where (the city and state).
• A line item: item=Description;quantity;price, with semicolons between the three parts. For a single one, leave the quantity out: item=Description;price. Write the price as a plain number with a dot for cents, such as 1450 or 2.10. If the user has no price yet and you can't open the price book, leave the price out too: item=Description.
• Options: option=Name starts an option, and the items after it belong to it. A quote takes up to 4. With no option, the items make one option. description= right after an option says what it is.
• Add-ons: addon=Name;price.
• Tax: tax=8.875 is a rate in percent, tax=$120 is an amount, and tax=not+included is a note. Leave tax out if the user gave no tax information.
• Deposit: deposit=25%25 is a percent (%25 is how a link writes %), and deposit=$200 is an amount. Words after it become its note: deposit=25%25+due+at+booking.
• The rest: valid=2026-12-15 (the last day the quote is good), notes, not_included, terms, currency, the business's own phone, email, address and license, and made_with= the name of your AI app.

Four characters need care inside a value: write & as %26, # as %23, % as %25 and + as %2B. Don't put a semicolon inside a description. Everything else stays as it is, commas included. The rules are the same as for every quote: only prices the user gave you or agreed to, no links, no payment details, and the customer's display name only.

Give the user the whole link on a line of its own, as plain text, and once more inside a code block, so they can copy it whole. Tell them: open it, check the details and prices, press Create approval link, then send the customer link to the customer and save the private link. Some chat apps send a tapped link through a search or redirect page, and the quote is lost on the way. So add: if the link opens a search page or an empty form, copy the link and paste it into Paste a quote from your AI at https://www.workeey.com/quote-links/.

This is example 2 below as a simple link, 344 characters after the address:

https://www.workeey.com/quote-links/new#business=Brightline+Painting&customer=Priya&job=Paint+living+room+and+hallway&where=Austin,+TX&option=Walls+and+ceiling&item=Walls,+two+coats,+per+square+foot;620;2.10&item=Ceiling,+one+coat;180&item=Paint+and+supplies;240&tax=not+included&deposit=25%25+Due+when+the+job+is+booked&not_included=Moving+large+furniture+and+repairing+water+damage.

The JSON link, step by step

1. Write the quote as one JSON object, in the format below, on one line. Add "source": {"client": "your AI app's name"}, so Workeey knows which assistant made it.
2. Encode it with encodeURIComponent, or the same thing in your language, and put it after the address:

   // JavaScript
   'https://www.workeey.com/quote-links/new#draft=' + encodeURIComponent(JSON.stringify(quote))
   
   # Python
   'https://www.workeey.com/quote-links/new#draft=' + urllib.parse.quote(json.dumps(quote, ensure_ascii=False, separators=(',', ':')), safe='')

3. If you can't run code, encode by hand: every character except letters, digits and - _ . ! ~ * ' ( ) becomes %XX. A space is %20, " is %22, { is %7B, } is %7D, [ is %5B, ] is %5D, : is %3A, , is %2C, / is %2F, # is %23, % is %25, & is %26, + is %2B. A letter outside English is its UTF-8 bytes, each as %XX. Leave out line breaks and the spaces between the JSON's parts; a space inside a text value stays, as %20.
4. Give the user the whole link on a line of its own, as plain text: not inside Markdown [text](link) brackets, and never shortened or cut. Show it once more inside a code block, so they can copy it whole.
5. Add one line for the user: if the link opens a search page or an empty form, copy the link and paste it into Paste a quote from your AI at https://www.workeey.com/quote-links/.
6. Tell the user: open it, check the details and prices, press Create approval link, then send the customer link to the customer and save the private link.

Use #draft=, never ?draft=. Don't use base64 or compression: the link is the plain JSON, encoded.

What stays private

The part of a link after # is not sent to any server when the link is opened. The draft stays in the user's browser until they press Create approval link; then the quote is sent to Workeey and stored. This is not encryption: the link itself stays in the chat and in the browser history. So put only the customer's display name in it, never their phone number, email or address.

The quote format

Required: business.name, customer.name, title, and options with at least one option that has a name and one item with a description and a unit_price.

• business (required): the user's own business.
  • name (required, 1 to 80 characters): the heading of the quote.
  • phone (up to 30), email (up to 120; the only field where an email address is allowed), address (up to 160), license (up to 60): all optional. The customer sees them marked as provided by the creator, not verified.
• customer (required): {"name": "Dana"}, a display name only, 1 to 80 characters. Nothing else about the customer.
• title (required, 1 to 120): the job, in a few words.
• location (optional, up to 80): city and state only, never a street address.
• currency (optional): a three-letter code for a currency with cents, such as USD (the default), CAD or EUR. A currency without 2-decimal cents, such as JPY or KWD, isn't supported yet and is refused.
• options (required, 1 to 4): the choices the customer picks between, each priced on its own. A quote with one price has one option.
  • name (required, 1 to 40) and description (optional, up to 500).
  • items (required, 1 to 50): each {"description": …, "quantity": …, "unit_price": …}. description is required (1 to 200). quantity is optional: more than 0, up to 100,000, default 1. unit_price is required: a plain number from 0 to 10,000,000 with at most 2 decimals, written with a dot (2.50, never 2,50). Workeey adds up the lines, so send no totals.
• addons (optional, up to 10): extras the customer can tick on top of the option they pick, each {"name": …, "price": …, "description": …}. name 1 to 80, price a number of 0 or more, description optional, up to 300.
• tax (optional), exactly one of:
  • {"label": "Sales tax", "rate_percent": 8.875}: a rate from 0 to 30, applied to the chosen option plus the chosen add-ons;
  • {"label": "Tax", "amount": 120}: a fixed amount;
  • {"note": "Tax not included"}: words instead of a number, up to 80 characters.
  Workeey applies what you send and never decides tax rules. Leave tax out if the user gave no tax information.
• deposit (optional): {"percent": 25} or {"amount": 200}, with an optional note (up to 200). It is wording only: Workeey takes no payments.
• notes, exclusions, terms (optional, up to 2,000 characters each).
• valid_until (optional): YYYY-MM-DD. The default is 30 days from today, and it can be at most 365 days ahead.
• source (optional): {"client": "the name of your AI app"}, with "route": "api" when you call the API. It is recorded as a claim and never shown to the customer.

Numbers are plain numbers, like 1450 or 2.1, never "$1,450" or "about 1.5k". Text can be in any language, including right-to-left scripts. Fields that aren't listed here are ignored.

The two examples below are made up. Never copy their business, customer or prices into a real quote: use only what the user tells you.

Example 1: water heater, two options, an add-on and a tax rate

The quote as JSON, then the same quote as a ready-made link (1,693 characters). Open example 1 in the editor: opening it publishes nothing. The tax rate is only an example: use the rate the user gives you.

{
  "business": { "name": "Rivera Plumbing", "phone": "718-555-0142", "license": "NYC LMP 12345" },
  "customer": { "name": "Dana" },
  "title": "Replace 50-gallon gas water heater",
  "location": "Brooklyn, NY",
  "currency": "USD",
  "options": [
    {
      "name": "Standard",
      "description": "Same-size tank, 6-year warranty",
      "items": [
        { "description": "50-gallon gas water heater, 6-year warranty", "unit_price": 1150 },
        { "description": "Labor: remove old heater, install, connect and test", "unit_price": 450 },
        { "description": "Haul away the old heater", "unit_price": 75 }
      ]
    },
    {
      "name": "Premium",
      "description": "High-efficiency tank, 12-year warranty",
      "items": [
        {
          "description": "50-gallon high-efficiency gas water heater, 12-year warranty",
          "unit_price": 1850
        },
        { "description": "Labor: remove old heater, install, connect and test", "unit_price": 450 },
        { "description": "Haul away the old heater", "unit_price": 75 }
      ]
    }
  ],
  "addons": [
    {
      "name": "Expansion tank",
      "price": 95,
      "description": "Protects the pipes from pressure build-up"
    }
  ],
  "tax": { "label": "Sales tax", "rate_percent": 8.875 },
  "notes": "About 4 hours of work. The water is off during the install."
}

https://www.workeey.com/quote-links/new#draft=%7B%22business%22%3A%7B%22name%22%3A%22Rivera%20Plumbing%22%2C%22phone%22%3A%22718-555-0142%22%2C%22license%22%3A%22NYC%20LMP%2012345%22%7D%2C%22customer%22%3A%7B%22name%22%3A%22Dana%22%7D%2C%22title%22%3A%22Replace%2050-gallon%20gas%20water%20heater%22%2C%22location%22%3A%22Brooklyn%2C%20NY%22%2C%22currency%22%3A%22USD%22%2C%22options%22%3A%5B%7B%22name%22%3A%22Standard%22%2C%22description%22%3A%22Same-size%20tank%2C%206-year%20warranty%22%2C%22items%22%3A%5B%7B%22description%22%3A%2250-gallon%20gas%20water%20heater%2C%206-year%20warranty%22%2C%22unit_price%22%3A1150%7D%2C%7B%22description%22%3A%22Labor%3A%20remove%20old%20heater%2C%20install%2C%20connect%20and%20test%22%2C%22unit_price%22%3A450%7D%2C%7B%22description%22%3A%22Haul%20away%20the%20old%20heater%22%2C%22unit_price%22%3A75%7D%5D%7D%2C%7B%22name%22%3A%22Premium%22%2C%22description%22%3A%22High-efficiency%20tank%2C%2012-year%20warranty%22%2C%22items%22%3A%5B%7B%22description%22%3A%2250-gallon%20high-efficiency%20gas%20water%20heater%2C%2012-year%20warranty%22%2C%22unit_price%22%3A1850%7D%2C%7B%22description%22%3A%22Labor%3A%20remove%20old%20heater%2C%20install%2C%20connect%20and%20test%22%2C%22unit_price%22%3A450%7D%2C%7B%22description%22%3A%22Haul%20away%20the%20old%20heater%22%2C%22unit_price%22%3A75%7D%5D%7D%5D%2C%22addons%22%3A%5B%7B%22name%22%3A%22Expansion%20tank%22%2C%22price%22%3A95%2C%22description%22%3A%22Protects%20the%20pipes%20from%20pressure%20build-up%22%7D%5D%2C%22tax%22%3A%7B%22label%22%3A%22Sales%20tax%22%2C%22rate_percent%22%3A8.875%7D%2C%22notes%22%3A%22About%204%20hours%20of%20work.%20The%20water%20is%20off%20during%20the%20install.%22%7D

Example 2: painting, one option

The quote as JSON, then the same quote as a ready-made link (902 characters). Open example 2 in the editor: opening it publishes nothing.

{
  "business": { "name": "Brightline Painting" },
  "customer": { "name": "Priya" },
  "title": "Paint living room and hallway",
  "location": "Austin, TX",
  "options": [
    {
      "name": "Walls and ceiling",
      "items": [
        { "description": "Walls, two coats, per square foot", "quantity": 620, "unit_price": 2.1 },
        { "description": "Ceiling, one coat", "unit_price": 180 },
        { "description": "Paint and supplies", "unit_price": 240 }
      ]
    }
  ],
  "tax": { "note": "Tax not included" },
  "deposit": { "percent": 25, "note": "Due when the job is booked" },
  "exclusions": "Moving large furniture and repairing water damage."
}

https://www.workeey.com/quote-links/new#draft=%7B%22business%22%3A%7B%22name%22%3A%22Brightline%20Painting%22%7D%2C%22customer%22%3A%7B%22name%22%3A%22Priya%22%7D%2C%22title%22%3A%22Paint%20living%20room%20and%20hallway%22%2C%22location%22%3A%22Austin%2C%20TX%22%2C%22options%22%3A%5B%7B%22name%22%3A%22Walls%20and%20ceiling%22%2C%22items%22%3A%5B%7B%22description%22%3A%22Walls%2C%20two%20coats%2C%20per%20square%20foot%22%2C%22quantity%22%3A620%2C%22unit_price%22%3A2.1%7D%2C%7B%22description%22%3A%22Ceiling%2C%20one%20coat%22%2C%22unit_price%22%3A180%7D%2C%7B%22description%22%3A%22Paint%20and%20supplies%22%2C%22unit_price%22%3A240%7D%5D%7D%5D%2C%22tax%22%3A%7B%22note%22%3A%22Tax%20not%20included%22%7D%2C%22deposit%22%3A%7B%22percent%22%3A25%2C%22note%22%3A%22Due%20when%20the%20job%20is%20booked%22%7D%2C%22exclusions%22%3A%22Moving%20large%20furniture%20and%20repairing%20water%20damage.%22%7D

Long quotes, and the paste box

Keep a ready-made link under about 1,800 characters: some chat apps cut longer links, and a cut link can't be read. The simple link is the shorter of the two, usually less than half the JSON link's length, so try it first. For a longer quote, with many line items or long notes and terms, do one of these instead:

• give the user the quote and tell them to open "Paste a quote from your AI" at https://www.workeey.com/quote-links/ and paste it there, which opens the same draft. The box takes the quote JSON, a ready-made link of either kind, or the labelled text below;
• create the quote with the API (way 2) or MCP (way 3), which have no link length to worry about.

The labelled text is for the paste box only. Write one thing per line, as Label: value. Under an Option: line, each line item is - description, quantity, price each, or - description, price for a single one. Write cents with a dot (2.50): a number like 2,50 is never guessed at, and the editor asks the user what it means. Tax is a percent (8.875%), an amount ($120) or words (not included). Dates are YYYY-MM-DD.

The labels: Business, Phone, Email (the business's), Address, License, Customer, Job, Location, Currency, Option, Description (under an option), Add-on, Tax, Deposit, Valid until, Notes, Not included, Terms, and Made with (the name of your AI app). The same rules apply: no links, no payment details, and the customer's display name only. An example:

Business: Rivera Plumbing
Phone: 718-555-0142
Customer: Dana
Job: Replace 50-gallon gas water heater
Location: Brooklyn, NY

Option: Standard
- 50-gallon gas water heater, 6-year warranty, 1, 1150
- Labor: remove old heater, install and test, 1, 450

Option: Premium
- 50-gallon high-efficiency gas water heater, 1, 1850
- Labor: remove old heater, install and test, 1, 450

Add-on: Expansion tank, 95
Tax: 8.875%
Deposit: 25% due before work starts
Notes: About 4 hours of work. The water is off during the install.

Create

Send the quote in the format above. The Idempotency-Key header is optional: send a new random UUID for each new quote ($(uuidgen) makes one), and the same key again only to retry that same quote. Within 24 hours, a retry with the same key gets the first answer back instead of making a second quote, so a retry after a timeout is safe. A key already used for a different quote is refused.

curl -s https://www.workeey.com/api/quote-links/create \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"business":{"name":"Rivera Plumbing"},"customer":{"name":"Dana"},"title":"Replace 50-gallon gas water heater","options":[{"name":"Standard","items":[{"description":"50-gallon gas water heater, installed","unit_price":1600}]}],"source":{"route":"api"}}'

What create returns

Give customer_url to the user to send to their customer. Give manage_url only to the user, and tell them to save it. Keep manage_token for the calls below. totals has one entry per option, in the same order as options: option is its index from 0, tax is null when the quote has no tax figure, and add-ons are added only when the customer picks them. The answer (201), with the tokens shortened here:

{
  "id": "3f6c2a9e-…",
  "version": 1,
  "customer_url": "https://www.workeey.com/q/Xq9…",
  "manage_url": "https://www.workeey.com/q/m/#Kp2…",
  "manage_token": "Kp2…",
  "valid_until": "2026-12-06",
  "totals": [
    { "option": 0, "name": "Standard", "subtotal": 1600, "tax": null, "total": 1600 }
  ]
}

Check without saving (optional)

The same body as create. Nothing is saved, and the answer has ok, quote, totals and errors.

curl -s https://www.workeey.com/api/quote-links/validate \
  -H 'Content-Type: application/json' \
  -d @quote.json

Status

The answer has status (one of open, approved, declined, changes_requested, expired, cancelled, disabled), versions (every version, each with its quote and totals), responses (each answer: the action; the option and add-ons picked, by index from 0 and by name; the amount, or null when no option was picked; the name typed; the time; and the version it answered), opens, email and customer_url.

curl -s https://www.workeey.com/api/quote-links/manage \
  -H 'Authorization: Bearer <manage_token>'

Revise

Send the complete new quote, not only the changes. The answer has version, unchanged, valid_until and totals. A new version gets the next number; a quote that is the same as the current version saves nothing and answers "unchanged": true with the current number. The customer link stays the same and shows the newest version, marked as updated.

curl -s https://www.workeey.com/api/quote-links/manage/revise \
  -H 'Authorization: Bearer <manage_token>' \
  -H 'Content-Type: application/json' \
  -d @quote-v2.json

Cancel

The answer is {"status": "cancelled"}. The customer link then says the quote was cancelled. To change prices or options, revise instead.

curl -s -X POST https://www.workeey.com/api/quote-links/manage/cancel \
  -H 'Authorization: Bearer <manage_token>'