External Query API Reference

This page provides developers with the technical specifications required to build an external API endpoint that can communicate with the DealHub External Query feature.

Authentication

All requests from DealHub will include an Authorization header. Your endpoint should be configured to validate requests using one of the following methods, as configured by the DealHub administrator.

Handling and Processing the Request

Your endpoint must be prepared to receive and process a POST request from DealHub. The request content type is application/json.

🚧

Developer Note

The data sent by DealHub can include different types. Your endpoint should be designed to handle strings, numbers, and dates. Date values are sent as a string in ISO 8601 format (e.g., `2021-03-25T15:39:25z).

The body of the request from DealHub contains two main objects: playbook_data and product_data.

📘

Repeatable Questions

A key aspect of processing the playbook_data object is distinguishing between regular and repeatable questions. A regular question will have a single value (e.g., a string or number), while a repeatable question will have an array of values. Your code must check the type of the value to process it correctly.

The following code example demonstrates the initial step for handling this data: accessing the playbook_data and product_data objects from the request body so you can begin your processing logic:

app.post('/your-dealhub-endpoint', (request, response) => {
  // Access the main data objects from the request body
  const { playbook_data, product_data } = request.body;

  // Your processing logic goes here...
  // ...
});

Creating a Success Response

When your service successfully processes the request, it must return an HTTP 200 status code with a JSON body.

❗️

Important

The keys in your JSON response object must exactly match the Question IDs in the target playbook group configured by the DealHub admin. This is how DealHub maps the returned data to the correct fields.

The response body must contain a playbook_data field, which is always an array of objects, even if you are only returning a single set of answers. Any additional keys or data in your response that do not correspond to a configured question ID will be ignored by DealHub.

Here is two Response examples:

{
  "playbook_data": [
    {
      "question_id_1": "Value for first question",
      "question_id_2": 12345,
      "hidden_field_id": "external-ref-abc"
    }
  ]
}

{
  "playbook_data": [
    {
      "col_1_id": "Row 1, Column 1 Value",
      "col_2_id": "Row 1, Column 2 Value"
    },
    {
      "col_1_id": "Row 2, Column 1 Value",
      "col_2_id": "Row 2, Column 2 Value"
    }
  ]
}

Creating an Error Response

If an error occurs while processing the request, your endpoint should return an HTTP 400 status code.
The body of the error response must be a JSON object containing a single message key. The string value of this key will be displayed to the user in the DealHub UI.

Here is an error message example:

{
  "message": "The provided customer ID is invalid or could not be found."
}

❗️

API Failure behavior

An API error, such as a timeout or a 400 status, will not automatically block the user from submitting a quote. DealHub only displays a warning message. To ensure data accuracy, you must build validations into the Playbook.