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.

📘

API Reference

If you prefer, you can check the Endpoint definition using the External Data Query reference page.

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 (Data Retrieval)

When your service successfully processes a data retrieval 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 are 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"
    }
  ]
}

External Validation Responses

When the External Query is triggered by an External Validation rule (rather than just for retrieving data), your endpoint must respond with specific status codes to indicate if the validation passed or failed.

• Validation Passed: Return HTTP 200. No specific body is required.
• Validation Failed: Return HTTP 400. The response body must follow the specific JSON format below to ensure the error is displayed correctly to the user.

If validation fails, include both an error code/name and a message string.

{
  "error": "ERR_INVALID_ID",
  "message": "The Customer ID provided is inactive."
}

📘

Error Message Concatenation

In the DealHub validation rule configuration, the administrator can define a default error message. If your API returns a message in the response body, DealHub will concatenate the admin's message with your external message:

• Admin Message: "Validation Failed:"
• API Response: "The Customer ID provided is inactive."
• User Sees: "Validation Failed: The Customer ID provided is inactive."

Creating a General Error Response

If a general error occurs while processing a data retrieval request (e.g., server error, timeout, or invalid logic not related to specific validation rules), 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

A general API error (non-validation), such as a timeout or a 400 status during data retrieval, will not automatically block the user from submitting a quote. DealHub only displays a warning message. To strictly block submission, you must use the External Validation method described above or build additional internal validations into the Playbook.