---
title: "Create an immutable, tax-inclusive quote"
method: POST
path: "/api/quotes"
---

# Create an immutable, tax-inclusive quote

`POST /api/quotes`

## Request

- Base URL: `https://postedly.com`
- URL: `https://postedly.com/api/quotes`
- Auth: HTTP bearer

Use for an intended physical send, not merely drafting a letter or emailing a PDF. Creates no order, approval, charge or send. The synthetic response example is not a current price or delivery promise. Always use the returned current total and expiry.

## Request body

- QuoteRequest: Handwritten cards use an exact catalog card, handwriting style, message and optional closing, with complete US sender and recipient addresses. No PDF upload is required. Catalog character limits apply to the exact raw text.
  - `service` 'fax' | 'letter' | 'certified' | 'postcard' | 'handwritten', required
  - `documentId` string, uuid: The id returned by an upload owned by this same session/OAuth connection. Required for document channels; handwritten cards do not require an upload.
  - `recipient` Contact, required
    - `name` string, required
    - `email` string, email
    - `fax` string
    - `phone` string
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
  - `sender` Contact, required
    - `name` string, required
    - `email` string, email
    - `fax` string
    - `phone` string
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
  - `options` object
    - `sendAsEntered` object: PostGrid postal mail only. Requests an exact-address quote for an address that failed live verification, set separately for each role. Does not grant approval; the delivery risk shown in addressWarnings is accepted only on the secure approval page before payment.
      - `recipient` boolean
      - `sender` boolean
    - `productId` string: Exact product id returned by the current product catalog.
    - `fontLabel` string: Handwritten cards only. Exact label from the selected card’s options.handwritingStyles; a style ID is not a substitute for this label.
    - `wishes` string: Handwritten cards only. Exact optional closing. Raw message.length + wishes.length must not exceed the card’s options.combinedCharacterLimit; no separator is added to this count.
    - `quantity` 1: One selected item per order.
    - `message` string: Exact personal message. Handwritten cards require nonempty text, at most options.maxMessageLength (never above 1000), with message plus wishes within options.combinedCharacterLimit.

## Response `201`

Immutable quote and final proof; explicit approval is still required. Handwritten cards contain design/style samples, exact text and addresses rather than a rendered final message.

- Quote: Immutable quote, normally valid for 20 minutes. The document is the final proof (including any fax cover or mail layout), which may differ from the uploaded file. Review this proof and the normalized contact/options snapshot. No approval, order or payment is created. Omitted optional properties are not null.
  - `id` string, uuid, required: Use as quoteId for the review link or explicitly approved checkout.
  - `service` 'fax' | 'letter' | 'certified' | 'postcard' | 'handwritten', required
  - `amountCents` integer, required: Amount in integer US cents; never a floating-point dollar amount.
  - `currency` 'USD', required
  - `lineItems` LineItem[], required
    - `label` string, required
    - `amountCents` integer, required: Amount in integer US cents; never a floating-point dollar amount.
  - `expiresAt` string, date-time, required
  - `estimatedDelivery` string, required: Provider estimate, not guaranteed arrival.
  - `summary` string, required
  - `document` Document
    - `id` string, uuid, required: Use this value as documentId in a quote; the person does not need to copy it.
    - `name` string, required
    - `pages` integer, required: Inspected page count; images count as one. Upload PDFs allow up to 50 pages; service-specific quote limits can be lower.
    - `bytes` integer, required
    - `sha256` string, required: Server-computed SHA-256 of the stored raw file bytes.
    - `contentType` 'application/pdf' | 'image/jpeg' | 'image/png', required: Detected media type, not a trusted client declaration.
    - `previewUrl` string, uri-reference, required: Private preview. Standard document URLs require the same owner’s bearer token; capability-scoped handoff URLs require their unexpired ticket. Resolve relative URLs against this API origin. Never make the file public to show a preview.
  - `recipient` Contact, required
    - `name` string, required
    - `email` string, email
    - `fax` string
    - `phone` string
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
  - `sender` Contact, required
    - `name` string, required
    - `email` string, email
    - `fax` string
    - `phone` string
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
  - `options` object, required: Saved, provider-validated options for this quote.
  - `handwritten` HandwrittenReview: Immutable quoted card, handwriting style, exact text, postal addresses and postage option. Images are design/style samples, not a rendered final-message proof.
    - `cardId` string, required
    - `cardName` string, required
    - `cardImageUrl` string, uri, required
    - `fontId` string, required
    - `fontLabel` string, required
    - `fontImageUrl` string, uri, required
    - `message` string, required
    - `wishes` string, required
    - `sender` Contact, required
      - `name` string, required
      - `email` string, email
      - `fax` string
      - `phone` string
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `postalCode` string
      - `country` string
    - `recipient` Contact, required
      - `name` string, required
      - `email` string, email
      - `fax` string
      - `phone` string
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `postalCode` string
      - `country` string
    - `previewKind` 'design_and_style_samples', required
    - `stampOptionId` integer, required
    - `stampName` string, required
  - `addressWarnings` AddressWarning[]
    - `role` 'recipient' | 'sender', required
    - `code` 'address_unit_required' | 'address_unverified', required
    - `message` string, required
    - `address` Contact, required
      - `name` string, required
      - `email` string, email
      - `fax` string
      - `phone` string
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `postalCode` string
      - `country` string

## Other responses

- `400`: Invalid input, missing document/address, unsupported destination/options, or price limit exceeded
- `401`: Authentication required
- `403`: Insufficient scope
- `404`: Document not found or belongs to another owner
- `409`: Provider or quote state conflict
- `410`: DOCUMENT_EXPIRED: upload is no longer retained
- `422`: File or recipient does not meet the selected service’s requirements
- `429`: Quote rate limit exceeded
- `500`: Internal failure; outcome unconfirmed
- `502`: Provider quote, price, tax calculation or final preview failed
- `503`: Service, tax calculation or mail capacity unavailable

---

[API](https://skmtc.dev/postedly/apis/postedly-send-api.md) · [All operations](https://skmtc.dev/postedly/apis/postedly-send-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postedly/apis/postedly-send-api/revisions/c7c71c05f64b?raw)