Create a quote

POST/api/v1/quotes

Needs an API key, and runs with the access of the member who made the key.
Send an Idempotency-Key. The same key with the same request within 24 hours gives the first answer again and changes nothing.
A connected AI assistant can use it too, as createQuote.

Parameters

Headers

Idempotency-Keystringrequired
Unique user-scoped key for safely retrying this mutation for 24 hours.
At least 1 character. Up to 200 characters.

Request body

Sent as application/json.

quoteobjectrequired
Fields(12)
- customer_idstring (uuid)required
- property_idstring (uuid) or null
- titlestringrequired
- descriptionstring or null
- currencystring
  At least 3 characters. Up to 3 characters.
- discount_centsinteger (int64)
  Integer minor currency units, such as pence.
  At least 0.
- deposit_centsinteger (int64)
  A deposit to ask for when the quote is accepted, tax included. 0, the default, asks for none. Never more than the quote's `total_cents`: a larger one is refused with 422. Like the rest of a quote, it can be changed only while the quote is a draft.
  At least 0.
- valid_untilstring (date) or null
- termsstring or null
- notesstring or null
- lock_versioninteger
  At least 0.
- items_attributesarray of object
  Each item(10)
  idstring (uuid)
  service_idstring (uuid) or null
  positioninteger
  At least 0.
  descriptionstring
  quantitystring
  Matches ^\d{1,9}(\.\d{1,3})?$.
  unit_namestring or null
  unit_price_centsinteger (int64)
  Integer minor currency units, such as pence.
  At least 0.
  tax_rate_basis_pointsinteger
  At least 0. At most 10000.
  tax_inclusiveboolean
  _destroyboolean

Responses

201Quote details.

dataobjectrequired
Fields(31)
- lock_versionintegerrequired
  At least 0.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- idstring (uuid)required
- source_visit_idstring (uuid) or null
  Assessment which produced this quote; retained when archived or converted to a job.
- account_idstring (uuid)required
- customer_idstring (uuid)required
- property_idstring (uuid) or null
- numberstringrequired
- titlestringrequired
- descriptionstring or null
- statusstringrequired
  One of: draft, sent, accepted, declined.
- expiredbooleanrequired
- currencystringrequired
- subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- discount_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- deposit_centsinteger (int64)
  The deposit asked for when the quote is accepted, tax included; 0 when none is. Accepting the quote issues an invoice of `kind` `deposit` for it, which carries this quote's `quote_id`.
  At least 0.
- valid_untilstring (date) or null
- sent_atstring (date-time) or null
- sent_to_emailstring (email) or null
  Where the quote was last emailed.
- email_messagestring
  The note the quote is emailed with unless the sender edits it, from the account's template. [Link] and any placeholder without a value yet are filled in on sending.
- public_urlstring (uri) or null
  The customer's link. Null while the quote is a draft or archived.
- accepted_atstring (date-time) or null
- accepted_by_namestring or null
- accepted_by_emailstring (email) or null
- declined_atstring (date-time) or null
- termsstring or null
- notesstring or null
- itemsarray of objectrequired
  Each item(12)
  idstring (uuid)required
  service_idstring (uuid) or null
  positionintegerrequired
  descriptionstringrequired
  quantitystringrequired
  Matches ^\d{1,9}(\.\d{1,3})?$.
  unit_namestring or null
  unit_price_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_rate_basis_pointsintegerrequired
  At least 0. At most 10000.
  tax_inclusivebooleanrequired
  subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.

A refusal answers in the one error shape every operation shares.

Example

A request our own tests send. The ids are made up: put your own in their place.

curl -X POST "https://app.tradesender.co.uk/api/v1/quotes" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "quote": {
    "customer_id": "372a8e62-6d44-552f-9c0e-c1229b6478be",
    "property_id": "20e51c3e-939a-59cd-998f-b3650207b9d5",
    "title": "Front hedge and borders",
    "valid_until": "2026-11-11",
    "terms": "Payment due within seven days of completion.",
    "items_attributes": [
      {
        "service_id": "b4ccc05f-b1ed-5dcd-bede-4479c3500345",
        "position": 1,
        "description": "Hedge cutting",
        "quantity": "1.000",
        "unit_name": "each",
        "unit_price_cents": 12000,
        "tax_rate_basis_points": 2000,
        "tax_inclusive": false
      }
    ]
  }
}'