Create or Open Quote

This tutorial guides you through the two primary actions for managing quotes via the API: creating a new quote from a CRM opportunity and opening an existing quote to view or edit it in the DealHub CPQ interface.The goal of both API calls is to receive a unique URL from DealHub, which you will use to redirect the user's browser, providing them with a seamless transition from your CRM directly into the quote.

Before You Begin

To follow this tutorial, make sure you have the following information ready:

• An authenticated dealhub_user_id and a valid one-time access_token. See our Authentication Guide for details.
• The external_opportunity_id from your CRM that the quote will be associated with.
• The customer's customer_name and their unique external_customer_id from your CRM.
• At least one customer contact, with one designated as the primary contact (primary_contact: true).
• The correct currency (e.g., "USD") and geo_code (e.g., "US-WEST") for the quote.

Create a New Quote

Use this process when a sales representative needs to generate a new quote for an opportunity in your CRM.

Step 1: Construct the JSON Payload

First, create a JSON object containing all the necessary information for the new quote. This payload includes identifying information, location, currency, and customer contacts.

{
  "dealhub_user_id": "111.0",
  "external_opportunity_id": "opp_456",
  "external_opportunity_name": "Q2 Deal",
  "external_customer_id": "cust_101",
  "customer_name": "Acme Corp",
  "geo_code": "US-WEST",
  "currency": "USD",
  "customer_contacts": [{
    "first_name": "John",
    "last_name": "Smith",
    "title": "Procurement Manager",
    "email": "[email protected]",
    "phone": "555-0123",
    "primary_contact": true
  }]
}

❗️

Currency is Final

The currency set during quote creation is permanent and cannot be changed later. Always ensure the correct currency is provided in this initial request.

Step 2: Send the API Request

Send a POST request to the Create Quote endpoint with your JSON payload.

• Endpoint: /api/v1.1/quote/create
• Headers:
  • Authorization: Bearer <ONE_TIME_ACCESS_TOKEN>
  • Content-Type: application/json

Step 3: Handle the Response

A successful request will return a 200 OK status and a JSON response containing a unique url.

{
  "url": "[https://service-eu1.dealhub.io/..../](https://service-eu1.dealhub.io/..../)",
  "errors": []
}

Your application should now redirect the user's browser to this URL to land them directly in the newly created quote within the DealHub CPQ.

Open an Existing Quote

Use this process when a user needs to access a quote that has already been created in DealHub.

Step 1: Construct the JSON Payload

To open a quote, you must provide the dealhub_quote_id. You also have the option to pass updated opportunity information in the opportunity_info object.

{
  "dealhub_user_id": "111.0",
  "dealhub_quote_id": "87948759384759",
  "external_opportunity_id": "opp_456",
  "opportunity_info": {
    "external_opportunity_name": "Q2 Deal (Updated Name)",
    "customer_name": "Acme Corp International"
  }
}

📘

Tip: Updating Opportunity Data

Any data passed in the opportunity_info object will only update the quote if it is still in a Draft state. For compliance and historical accuracy, submitted quotes will not be affected by these updates.

Step 2: Send the API Request

Send a POST request to the Open Quote endpoint with your JSON payload.

• Endpoint: /api/v2/quote/open
• Headers:
  • Authorization: Bearer <ONE_TIME_ACCESS_TOKEN>
  • Content-Type: application/json

Step 3: Handle the Response

Similar to creating a quote, a successful request will return a 200 OK status and a JSON response with a unique url for redirection.

{
  "url": "[https://service-eu1.dealhub.io/..../](https://service-eu1.dealhub.io/..../)",
  "errors": []
}

Redirect the user's browser to this URL to open the existing quote in the DealHub CPQ.

Next steps

Now that you learned how to create and open quotes, learn how to view quotes and opportunities.