Retrieving Multiple Quotes

This tutorial guides you through the different ways to use the GET /api/v2/quotes endpoint to retrieve lists of quotes from DealHub. You can use this endpoint in different ways:

• Perform bulk data operations, such as performing an initial sync of all historical quote data to a business intelligence (BI) system.
• Find all quotes associated with a specific sales opportunity.
• Get detailed information from specific quotes.

These processes are covered in details on this page.

Prerequisites

Before you begin, ensure you have:

• Your DealHub Authentication Token: Each API request must include an authentication token in the header. You can generate this token in the Control Panel > System Settings > API Settings section of the DealHub admin interface.

Retrieving All Historical Quotes with Pagination

Use this method when you need to retrieve all quotes that exist in your DealHub instance. This is a common first step for customers who have been using DealHub for some time and now want to sync that historical data to an external system.

The process involves making repeated requests and using the offset and limit parameters to page through the entire dataset.

Step 1: Make the Initial Request

To begin, make a simple GET request to the /api/v2/quotes endpoint. You do not need to add any parameters for the first call.

curl --location 'https://app.dealhub.io/api/v2/quotes' \
--header 'Authorization: Bearer <YOUR_SECRET_TOKEN>'

By default, the API returns a maximum of 50 results (limit) and starts from the beginning of the list (offset: 0). Unless you request specific features, the response for each quote will only contain the dealhub_quote_id, status, and quote_upgrade_required.

The response body will also contain pagination information:

{
  "quotes": [
    {
      "dealhub_quote_id": "12345zWIwGV12344",
      "status": "ReadyToBeSent",
      "quote_upgrade_required": false
    },
    {
      "dealhub_quote_id": "12345zWIwGV12347",
      "status": "Draft",
      "quote_upgrade_required": true
    }
    // ... 48 more results
  ],
  "more_results_matching_the_request": true,
  "offset": "0",
  "limit": "50"
}

Step 2: Check for More Results and Use the Offset

The more_results_matching_the_request field tells you if there is more data to retrieve. If it's true, you need to make another request and page to the next set of results.

To get the next page, use the offset query parameter. The offset tells the system how many records to skip. Since the first request returned 50 records (the limit), your next request should have an offset of 50.

curl --location 'https://app.dealhub.io/api/v2/quotes?offset=50' \
--header 'Authorization: Bearer <YOUR_SECRET_TOKEN>'

This request will return the next 50 quotes (records 51-100). [cite: 118]

Step 3: Loop Until All Quotes are Retrieved

Continue making requests, increasing the offset by 50 each time (offset=100, offset=150, and so on), as long as more_results_matching_the_request is true.

The loop is complete when a request returns more_results_matching_the_request: false. At this point, you have retrieved all the quotes in the system.

📘

Performance Best Practice

When retrieving all historical quotes, do not request detailed features (e.g., &feature=all or &feature=info) in your GET /quotes calls. Doing so can return tens of thousands of lines in the payload, which is slow and may cause the request to time out.

The recommended approach is:

1. Loop through the GET /quotes endpoint using offset to collect only the dealhub_quote_id for every quote in the system.
2. Once you have the complete list of IDs, make individual GET /api/v2/quote/{quote_id} calls for each quote to retrieve the specific details you need.
3. Consider running this bulk sync process over a weekend or during off-peak hours to avoid impacting system performance for other users.

Retrieving Quotes for a Specific Opportunity

If you only need the quotes associated with a single sales opportunity, you can use the external_opportunity_id query parameter for a much more targeted query. This ID is the unique identifier for an opportunity in your CRM system (e.g., Salesforce, HubSpot).

Step 1: Make a Request with the Opportunity ID

Append the external_opportunity_id parameter to your request URL.

curl --location 'https://app.dealhub.io/api/v2/quotes?external_opportunity_id=<YOUR_OPPORTUNITY_ID>' \
--header 'Authorization: Bearer <YOUR_SECRET_TOKEN>'

Step 2: Review the Filtered Response

The API will return a list containing only the quotes that are associated with that specific opportunity ID. You can also include feature parameters in this call if you need more details, as the result set will be much smaller than a full historical sync.

{
  "quotes": [
    {
      "dealhub_quote_id": "QUOTE_A_FOR_OPP_123",
      "status": "Won",
      "quote_upgrade_required": false
    },
    {
      "dealhub_quote_id": "QUOTE_B_FOR_OPP_123",
      "status": "Draft",
      "quote_upgrade_required": false
    }
  ],
  "more_results_matching_the_request": false,
  "offset": "0",
  "limit": "50"
}

Using the feature Parameter for More Detail

By default, the GET /quotes endpoint returns a minimal set of data for each quote. To retrieve more detailed information, you can add one or more feature parameters to your request.

You can specify multiple features in a single request.

curl --location 'https://app.dealhub.io/api/v2/quotes?external_opportunity_id=<YOUR_OPPORTUNITY_ID>&feature=info&feature=summary' \
--header 'Authorization: Bearer <YOUR_SECRET_TOKEN>'

The following table summarizes the what are the results returned for each of the featuresavailable and when you should use it:

🚧

Caution

Never use &feature=all when performing a bulk historical sync with pagination. The large amount of data returned for each quote can cause significant performance delays and may lead to the API request timing out.

Always follow the best practice of retrieving only the quote IDs first, then making individual requests for details as needed.