Generate a Quote via API

This tutorial teaches you how to create an official quote object in DealHub using the Generate Quote API. Use this process for automated contract renewals, self-service portals, or CRM-driven quote generation.

📘

Billing

Calls to the Generate Quote API are counted towards your API usage and will be billed.

Prerequisites

Before you begin, ensure you have the following:

• DealHub Admin access
• The API Playbook enabled and configured
• All required products, pricing rules, and output documents associated with the API Playbook

📘

Automating Quote Generation

This tutorial is intended for developers who want to automate quote generation using the DealHub API. If you need to customize quotes, configure complex logic, or adjust layouts, please use the DealHub web UI.

Part 1: Construct the API Request

To generate a quote, you will send a POST request to the /api/v1/quote/generate endpoint. The JSON payload for this request has several mandatory fields and two distinct methods for defining the quote's contents.

Mandatory Request Parameters

Every Generate Quote request must include these top-level fields:

• external_opportunity_id: The ID of the opportunity from your CRM to which this quote will be linked. DealHub uses this ID to automatically fetch related opportunity data.
• request_action: This crucial field tells DealHub what initial action to perform on the new quote. The four valid options are:
  • draft: Creates the quote and saves it in a Draft status.
  • submit: Creates the quote and immediately submits it, moving it to the Approval Process or Ready To Be Sent status.
  • publish: Creates, submits, and, if approved, publishes the quote to a DealRoom.
  • sign_externally: Creates, submits, and, if approved, marks the quote as signed, moving it to the Won status.
• document_type: Specifies the primary output document type, such as DealRoom or PDF.

Choose a Data Injection Method

You must use one of the following two methods to specify the products for the quote.

Option A: Injecting Data via Playbook (quote_data)

This method simulates a user answering questions in the API Playbook. Use this when you want to leverage the product selection rules and logic built into the playbook. To populate a repeatable (table-based) question group, provide multiple objects within the questions array. The following code snippet shows an example payload using quote_data:

{
  "external_opportunity_id": "006J7000003wYhD",
  "request_action": "submit",
  "document_type": "DealRoom",
  "quote_name": "Automated Renewal Q3",
  "quote_data": [
    {
      "group_id": "GQ",
      "questions": [
        {
          "question_id": "product",
          "value": "Admin License"
        },
        {
          "question_id": "qty",
          "value": 10
        }
      ]
    }
  ]
}

Option B: Injecting Products Directly (line_items)

This method bypasses the playbook's selection logic and allows you to specify line items directly using their sku. Use this when your external system already knows exactly which products and prices to quote. The following code snippet shows an example payload using line_items:

{
  "external_opportunity_id": "006J7000003wYhD",
  "request_action": "draft",
  "document_type": "PDF",
  "quote_name": "Self-Service Portal Quote",
  "line_items": [
    {
      "sku": "ADMIN-LIC",
      "qty": 10,
      "list_price": 100,
      "term_duration": 12
    }
  ]
}

❗️

Restrictions

• You cannot push quote_data into a question group that is also configured to use an External Query.
• You cannot push data directly into a playbook field that is set as a Calculated Answer.

Part 2: Handle the Asynchronous Response

The Generate Quote API is asynchronous. When you send the request, DealHub immediately returns an HTTP 202 Accepted response. This confirms the request was received and the quote generation process has started. However, the process is not yet complete.

You should monitor Webhook events to receive the final confirmation and status of the newly created quote, especially to know if it has entered an approval workflow. This code snippet shows an example success response:

{
    "status": "submit",
    "dealhub_proposal_id": "Q-12928",
    "dealhub_quote_id": "12345zWIwGV12345",
    "dealroom_url": null,
    "approval_flows": true,
    "summary": {},
    "line_items": []
}

This initial response tells you the action was submit, provides the new quote IDs, and indicates that an approval flow was triggered (approval_flows: true).

Next Steps

Now that you learned how to generate a quote via API, learn how to use the Actions API