Get DealRoom Signers

A DealRoom is a customer-facing website used for sharing quotes and negotiating deals. Instead of emailing multiple PDF versions back and forth, you provide the customer with a single link to a portal that always shows the latest published version of the quote. This portal includes an e-signature widget, allowing customers and members of your organization to sign the contract directly.

📘

Tip

You can customize the DealRoom experience for each buyer, including branding, content, and signer workflow. This helps create a more engaging and professional buying experience.

After a contract is signed in the DealRoom, you may need to access the details of the signers for your records, for auditing purposes, or to trigger the next step in your business process (like provisioning a service). This is what the Get DealRoom Signers API endpoint allows you to do.

👍

Tip

Use the API to sync signers with your CRM, trigger notifications, or build custom approval workflows.

Prerequisites

Before you begin, ensure you have:

• A DealHub Authentication Token to authorize your API requests.
• The CRM opportunity_id for a deal.
• The deal must have a DealRoom that has been published and is at least partially signed.

Understanding the Endpoint and its Conditions

Before making the API call, it's important to understand the conditions under which it will work successfully.

• The DealRoom is associated with an opportunity, not a specific quote. Therefore, the API endpoint requires the opportunity_id from your CRM in the URL path.
• You can only retrieve signer information if a DealRoom has already been created (published) for the specified opportunity. if you try to access an opportunity that does not have a published DealRoom, the API will return an error.
• The API returns information about actual signers. This means that at least one person (either from the buyer's or seller's side) must have signed the contract in the DealRoom. If no one has signed yet, the signer lists in the response will be empty.

How to Get DealRoom Signers

First, get the unique opportunity ID from your CRM for the deal you want to query.

Next, make a GET request to the /api/v1/dealroom/{opportunity_id} endpoint. Remember to replace {opportunity_id} in the URL with the actual ID you identified in the previous step.

curl --location 'https://<YOUR_DEALHUB_URL>/api/v1/dealroom/<YOUR_OPPORTUNITY_ID>' \
--header 'Authorization: Bearer <YOUR_SECRET_TOKEN>'

If the request is successful, the API will return a 200 (Success) status code and a JSON object containing the state of the DealRoom and lists of the buyer and seller signers:

{
  "dealroom_state": "Partially signed",
  "buyer_signers": [
    {
      "company_name": "BBB Inc.",
      "signee_name": "John Brown",
      "signee_title": "CEO",
      "signature_date": "2024-02-06 16:41:29",
      "ordinal": 1
    }
  ],
  "seller_signers": []
}

The response provides a complete picture of the signing status. You will receive the overall state of the DealRoom (e.g., Partially signed) , along with two distinct lists:

• buyer_signers: people from the customer's organization.
• seller_signers: people from your organization.

Each entry in these lists contains the signer's name, title, company, and the exact date and time they signed the contract.

Next Steps

Now that you finished the Quote Management Section, Move forward to the External Query Section.