Quote requests

Use this when a form on your own website — an ad landing page, a microsite, a campaign page — should land in Riverr as a quote. Riverr does not price the job from this call. The request shows up in Quotes so you can calculate ink, build the line items, and send the quote back.

This is a REST call. It is not a GraphQL operation, and it does not use the order API key.

Endpoint

POST https://api.riverr.app/public/quote-requests

Authenticate

Send the quote intake key in the x-uid header. Authorization: Bearer works as well.

The quote intake key starts with rv_quote_. It can only create a quote request. It cannot read or create orders. Keep it on your server. Do not put it in page JavaScript.

Find it in Riverr: Settings → Developer → API credentials. Confirm it is you, then copy Quote intake key. The first time you open that page, a key is created. Rotating it stops the previous key immediately.

curl https://api.riverr.app/public/quote-requests \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-uid: rv_quote_YOUR_KEY" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "555-0100",
    "company": "Acme",
    "zip": "90210",
    "quantity": 48,
    "garment": "Gildan 5000",
    "colors": "black",
    "inkColors": "white, red",
    "sizes": "M: 24, L: 24",
    "decoration": "front",
    "needBy": "2026-11-20",
    "comments": "Left chest print",
    "site": "Summer tees ad",
    "pageUrl": "https://example.com/summer",
    "artwork": ["https://cdn.example/logo.png"]
  }'

You can also nest the same fields under contact, order, and context if that matches the form you already have. firstName and lastName are accepted in place of name. ink, inks, and printColors are accepted in place of inkColors.

Customers

Each request is attached to a customer already on the account when one matches. The check runs in this order:

1. customerId, when you send one. This skips email and phone matching. The id has to belong to this account.
2. Email. Exact match, ignoring upper/lower case and spaces.
3. Phone. The last 10 digits, so +1 (562) 555-1234, 5625551234, and 562-555-1234 are the same number. Used only when the email does not match.
4. Otherwise a new customer is created.

When an existing customer matches, the quote is added to that profile. Empty fields (address, company, phone, and so on) are filled in from the request. Fields that already have a value are left as they are.

customerId can sit on the root or under contact (customer_id is also accepted). Look the id up first with getCustomer if you have it.

A full mailing address is saved on the customer: street1, street2, city, state, zip, and country. Those can also be nested under address or shippingAddress.

Required fields

Field	Notes
name	Or firstName plus lastName.
email	A real email address. The priced quote is sent here.
One job detail	At least one of quantity, garment, colors, inkColors, sizes, decoration, comments, or artwork.

Artwork

artwork is a list of https URLs, or objects { "name", "url" }. Up to 10. http links are dropped. Host the file yourself and pass the URL. This endpoint does not accept a file upload.

Response

{
  "id": "QT-0042",
  "status": "draft",
  "customerId": "abc123",
  "customerMatched": true
}

id is the quote number in Riverr. The row is marked Website.

customerId is the customer profile the quote was attached to. Store it and send it back as customerId on the next request. customerMatched is true when that profile already existed, and false when this request created it.

Status	Meaning
200	The draft was created.
400	Name, email, or job detail is missing, or customerId is not a customer on this account. message says which.
401	The quote intake key is missing or not recognized.
429	More than 30 requests from this account in 10 minutes.

What happens next

The draft is filed on the Riverr account that owns the key. Open it in Quotes, price the ink and the garments, and send the quote. The customer receives the quote from that send.