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.

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."
}