Using the Actions API

This tutorial guides you through performing lifecycle actions on existing quotes in DealHub using the Actions API. Actions include submitting a quote for approval, publishing it to a DealRoom, or marking it as signed externally. The Actions API is typically used after a quote has been created using the Generate Quote API.

📘

Billing

Actions API calls are free of charge and do not count towards your API usage.

📘

The Actions API can be used for any existing quote, whether it was generated via API or created manually in the DealHub UI.

Before You Begin

Ensure you have:

• DealHub Admin access
• An existing quote object in DealHub
• The API Playbook enabled and configured

🚧

Quote Status

Each lifecycle action is only available for quotes in specific statuses. Attempting an action on a quote in the wrong status will result in an error. Always verify the quote’s current status before performing an action.

Before using the Actions API, it is essential to understand that it is state-dependent: The action you can perform on a quote is dictated entirely by its current status. Attempting to perform an action on a quote in an invalid state (for example, trying to publish a Draft quote) will result in an error.

Therefore, the first step in any automated workflow is always to check the quote's current status. Your application can get this information in two primary ways:

• From the Generate Quote Response: When a quote is first created, the API response body includes its initial status.
• Using the Get Quote API: For any existing quote, make a GET request to the Get Quote API to fetch its most up-to-date details, including the status.

The following are the official statuses a quote can have throughout its lifecycle.

Once you have determined the current status, use the table below as a guide to choose the correct action and endpoint.

Sending the API Request

Actions are performed using a POST request to the appropriate endpoint, with the action determined by the URL path:

📘

Response Status Code

All actions requests will return a 202 status code.

🚧

Error Responses

If your request resulted in an error, the response request will still return a 202 status code (Success) with the error message.

For submit and publish, no request body is required. The action is specified by the endpoint itself, and the dealhub_quote_id is passed in the URL path.

For sign_externally, you need to include an JSON body with the parameter sign_externally_comment:

{
  "sign_externally_comment": "Notes for external signing."
}

For example, suppose you have a quote with ID 12345zWIwGV12344 in Ready status and want to publish it to a DealRoom:

1. Confirm the quote status is Ready and document type is DealRoom.
2. Send a POST request to /api/v1/quote/12345zWIwGV12344/publish
3. Include your authentication token in the request headers.
4. On success, you will receive a 202 response and the quote will be published.

A successful response confirms the action has been initiated and provides the updated status of the quote. Actions are processed asynchronously and may require data synchronization with the CRM. Status updates and workflow progress should be monitored via Webhooks.

The following code snippets shows examples of a successful and a error response:

{
  "status": "Published",
  "dealhub_proposal_id": "Q-12927",
  "dealhub_quote_id": "12345zWIwGV12344",
  "summary": {
    "currency": "USD",
    "total_list_price": 458154.42,
    "total_net_price": 238042.66,
    "total_discount": 48.04,
    "total_sales_discount": 0
  },
  "line_items": [
    {
      "id": "12345zWIwGV12347",
      "sku": "999451",
      "name": "Gold Shield Pack",
      "list_price": 50.04,
      "net_price": 22500.02
      // ...additional fields...
    }
  ]
}

{
  "error": "Publish quote failed: The quote is in 'Draft' status and must be submitted first."
}

Error Handling

If an action is attempted in an invalid state, or if validation requirements are not met, the API will return an error response with a message indicating the reason (e.g., "Publish quote failed: The quote is in 'Draft' status and must be submitted first.").

🚧

Error Reference

To learn more about the actions API error responses, read the error reference page