Create Opportunity

In DealHub, every quote must be attached to an opportunity. An opportunity represents a potential sale or deal in your pipeline and acts as a container, typically created from your CRM (like Salesforce), that holds all related quotes for a specific sales deal. While the standard workflow involves a user creating an opportunity in DealHub by clicking a button in the CRM, this endpoint allows you to create an opportunity using the API in advance.

The most common use case for this API is to make the process of renewing a customer contract more efficient. By creating the renewal opportunity in DealHub automatically via the API, a salesperson can simply find the original won quote and duplicate it to the new opportunity, saving several manual steps.

Prerequisites

A DealHub Authentication Token to authorize your API requests.
Configure your CRM to make an API call when an event occurs (e.g., using Salesforce Apex Triggers or a similar automation tool to call the DealHub API when a renewal opportunity is created).

Understanding the Renewal Workflow

Using the API to create opportunities in advance simplifies the workflow for your sales team.

Without API automation, a salesperson renewing a deal has to:

Identify the new renewal opportunity.
Establish a link between the renewal opportunity and DealHub.
Discard the initially generated empty quote.
Locate the original, previously won quote from the earlier opportunity.
Duplicate the original quote and associate it with the new renewal opportunity.

By using the Create Opportunity API, the process becomes much simpler:

Automated Step: When a renewal opportunity is created in your CRM, an automated process calls the DealHub POST /api/v1/opportunity endpoint, creating the opportunity in DealHub.
User Step: The salesperson goes directly to the original won quote in the DealHub dashboard, clicks Duplicate Proposal, and selects the new, pre-created opportunity from the list.

Create an Opportunity via API

To create an opportunity, you must provide a JSON object in the request body with the mandatory fields. Your CRM automation should be configured to pass these values dynamically.

Field	Description
`external_opportunity_id`	The unique ID of the opportunity from your CRM.
`external_opportunity_name`	The name of the opportunity from your CRM.
`opportunity_owner`	An object containing details of the user who owns the opportunity. Must include `email` and `name`.
`currency`	The three-letter ISO code for the opportunity's currency (e.g., "USD").
`external_customer_id`	The unique ID of the customer account from your CRM.
`customer_name`	The name of the customer account.

Your request body should be a JSON object that looks similar to the following example.

{
  "external_opportunity_id": "OPP-RENEWAL-2025-12345",
  "external_opportunity_name": " Acme Corp - 2025 Renewal",
  "opportunity_owner": {
    "external_user_id": "salesforce_user_id_001",
    "email": "[email protected]",
    "name": "Vadim T",
    "login": "liotr"
  },
  "currency": "USD",
  "external_customer_id": "acme-corp-768",
  "customer_name": "Acme Corporation"
}

Send a POST request to the /api/v1/opportunity endpoint with your JSON payload.

A successful request will return an HTTP status code of 200 (Success), indicating that the opportunity has been created in DealHub and is now available.

f you try to create an opportunity with an external_opportunity_id that already exists, the API will return a 400 error with the message Entity (opportunity ID= \<entity ID\>) already exists.

Next Steps

Now that you learned how to Create an Opportunity, Learn how to Get DealRoom Signers.