Callouts API Reference

This document provides developers with the technical specifications required to build an external API endpoint that can communicate with the DealHub Callouts API.

📘

API Reference

If you prefer, you can check the Endpoint definition using the Retrieve Real-Time Pricing reference page.

Authentication

DealHub sends authentication credentials in the request header and the request body. Your endpoint must be prepared to handle both.

• Request Header: The standard Authorization header will be sent with either a Bearer token or Basic credentials, depending on the administrator's configuration.
• Request Body: The same token or credentials will also be present in the authentication field within the JSON payload.

Request Contract

Your endpoint will receive an HTTP POST request with Content-Type: application/json.

The JSON payload will contain a request_id, authentication details, playbook_answers, and an items array listing every product that requires external pricing.

📘

Property Name Conversion

Property names in the JSON payload that contain spaces or hyphens (e.g., a proposal attribute named "start-date") will have those characters converted to underscores (e.g., "start_date").

Here's an example request body:

{
  "request_id": "RANDOM-32bit-string",
  "authentication": "DASFE$df422ffg",
  "playbook_answers": {
    "general.currency": "USD",
    "general.geo": "North America",
    "group1.customer_type": "Enterprise"
  },
  "items": [
    {
      "id": 1,
      "sku": "A-1",
      "type": "product",
      "quantity": 15,
      "duration": 12,
      "family": "hardware",
      "returned_attributes": {
        "price": "number",
        "MSRP": "number",
        "start_date": "date"
      }
    },
    {
      "id": 2,
      "sku": "B-1",
      "type": "bundle",
      "quantity": 2,
      "duration": 24,
      "family": "software",
      "returned_attributes": {
        "MSRP": "number",
        "start_date": "date"
      },
      "bundle_items": [
        {
          "id": 3,
          "sku": "B-111",
          "type": "product",
          "quantity": 15,
          "duration": 12
        }
      ]
    }
  ]
}

Response Contract

For a successful transaction, your service must return an HTTP 200 status with a JSON body.

The response body must contain a top-level items array. Each object within this array corresponds to a product sent in the request.

Each object in the response items array must contain the following three fields:

• id: The same item id that was sent in the request.
• sku: The same sku that was sent in the request.
• price: The list price of the line item. This should be a a numeric value.

❗️

Critical Failure Condition

The price field is absolutely mandatory. If your response is missing the price field for even a single product, the entire quote generation process in DealHub will stop and an error will be displayed to the user.

Here's an example response:

{
  "items": [
    {
      "id": 1,
      "sku": "A-1",
      "price": 100,
      "MSRP": 200,
      "start_date": "2021-03-25T15:39:25z"
    },
    {
      "id": 2,
      "sku": "B-1",
      "MSRP": 600,
      "start_date": "",
      "bundle_items": [
        {
          "id": 3,
          "sku": "B-111",
          "price": 100,
          "MSRP": 200
        }
      ]
    }
  ]
}

Error Response

If your service encounters an error and cannot return prices, it should respond with an HTTP 400 status.

The body of the error response must be a JSON object with a single message key containing a description of the error.

Here's an example error response:

{
  "message": "This is an example of the formatted error from the external system."
}