Guides

External Query Overview

Suggest Edits

The External Query API allows DealHub to retrieve data from your external systems in real time while a sales representative creates a quote. In this scenario, DealHub acts as the client, sending a request to an endpoint you provide and then integrating the response back into the quote's Playbook.

This request can include data from the quote level, enabling your external system to process the context of the quote and return relevant information. This allows you to enrich quotes with live data from proprietary databases or business logic hosted on your side.

This functionality is distinct from DealHub's standard APIs, where your application sends requests to DealHub. With External Queries, the data flow is reversed, DealHub initiates the request to enrich a quote with live, external data from your system.

❓

When should you use External Queries?

You should use the External Query API when you need to populate a quote with information that resides in a system other than your primary CRM (such as Salesforce or HubSpot). Since DealHub has native integrations for pulling data directly from CRMs, External Queries are specifically designed for all other external data sources.

Common applications include:

  • Calculating shipping costs: Querying a carrier's API (e.g., DHL) with package details to get real-time shipping prices and durations.
  • Fetching tax information: Sending line-item data to a tax calculation service to retrieve the correct tax rates for a quote.
  • Retrieving data from proprietary databases: Accessing internal company databases for custom pricing, stock availability, or user-specific information that isn't stored in the CRM.

How an External Query Works

To understand how an External Query works, it is helpful to follow the flow of data from start to finish. The process begins with a trigger, which an administrator configures within the Playbook. This can be a manual button that the sales representative must click, or it can be an automatic event that fires when the question group first appears or when the value of another field is changed.

Once triggered, DealHub sends a POST request to your system. The JSON payload for this request is highly configurable; an administrator can select specific information from both the Playbook (like customer details or choices made by the user) and the Products section (like SKUs and quantities) to be included in the call. In response, your external system must return a playbook_data array where the keys in the JSON objects exactly match the Question IDs in the target Playbook group, allowing DealHub to map the data correctly.

Finally, how this returned data is presented to the sales representative is also configurable. It can either appear in a pop-up modal, requiring the user to select a row to import the information, or it can be injected directly into the Playbook fields for a more seamless experience.

External Queries Lifecycle

An External Query follows a predictable, real-time data exchange process that involves configuration by an administrator, an action by a sales representative, and a direct API call between the DealHub platform and your external system. This flow ensures that live data can be pulled into a quote exactly when it's needed.

This process can be broken down into the following key stages:

  1. A DealHub Admin first configures the External Query, defining the external API endpoint, authentication method, and the specific data to be sent. They then attach this query to a question group in a Playbook.
  2. While working on a quote, a Sales Rep performs an action that triggers the query. This can be a manual button click or an automatic trigger based on changes to other fields.
  3. The DealHub Platform sends a POST request to your External System. Your system processes the data and sends a JSON response back to DealHub, indicating success (HTTP 200) or an error (HTTP 400).
  4. Upon receiving a successful response, the DealHub Platform parses the JSON and populates the data into the corresponding fields in the Sales Rep's Playbook, making the information visible and usable in real time.

Next steps

Now that you learned how External Queries work, you can proceed to the technical and practical guides:

Updated 14 days ago