Creating an External Query

This guide provides step-by-step instructions for creating and configuring an External Query object within DealHub's admin panel. This object is a reusable configuration that defines the endpoint, authentication method, and the data payload for an external API call.

📘

Creating or modifying an External Query configuration must be done through the DealHub admin UI as described above.

Prerequisites

Before you begin, ensure you have:

• DealHub administrator privileges.
• The exact URL of the external API endpoint.
• The required authentication details (e.g., a Bearer Token or username/password) to authenticate the requests DealHub will send to the URL you will provide.

Creating the External Query Object

The entire configuration is managed within the settings of a specific DRAFT version.

Step 1: Navigate to Advanced Settings

1. Log into your DealHub account and enter Admin Mode.

2. From the Control Panel, navigate to Version Settings.

   

3. Select the DRAFT version where you want to add the query and click Edit.

   

4. Click on Advanced Settings.

   

5. Select the Manage External Object section.

   

Step 2: Configure the Endpoint and Authentication

In the Manage External Object interface, create a new query and define its connection details.

1. Create a new query object and give it a descriptive name that reflects its purpose (e.g., "Shipping Cost Calculator").

2. Ensure the query Type is set to API.

3. In the URL endpoint field, enter the full URL of the third-party service that will receive the request.

   

4. From the Authentication Type dropdown, select the method required by your external system.

   • Token: Select this and paste the Bearer Token provided by your endpoint provider.
   • Basic: Select this and enter the Username and Password.
   • None: Select this if the endpoint requires no authentication or uses a token embedded in the URL (e.g., a Shared Access Signature).

Step 3: Define the Request Payload

Next, specify exactly which pieces of information from DealHub should be sent to your external system when the query is triggered.

1. Choose the source Playbook from which the query will gather data.

2. In the Playbook answers to send field, select the specific playbook questions whose answers you want to include in the request. These will be sent in the playbook_data object in the JSON payload.

3. In the Product attributes to send field, select the product-level information (e.g., SKU, quantity, or custom attributes) to include. These will be sent in the product_data array in the JSON payload.

   

Step 4: Save Your Configuration

Once you have finished, save the settings for your version. You have now successfully created a reusable External Query object.

🚧

Error Handling

If your external system fails to process a request, it should return an HTTP 400 status with a JSON object containing a message key; this message will be displayed to the user in the DealHub UI. An error will not automatically stop the quote generation process, but you can build validation rules within the Playbook to check if the required data was populated and prevent submission if necessary.

Next Steps

Now that you have created the query object, you must attach it to a playbook to make it functional. Learn how to use an External Query in a Playbook.