Partner API Overview

The Partner API enables partner users to access DealHub CPQ directly from a Partner Relationship Management (PRM) system or partner portal, without requiring a separate DealHub login. The integration standardizes the selling procedure and streamlines the CPQ process for partner users.

The solution uses a two-phase request/response flow in JSON format:

1. Authenticate: The PRM backend authenticates the partner user and receives a short-lived access token from DealHub.
2. Open DealHub CPQ: The PRM client uses that token to redirect the partner user directly into DealHub CPQ, either to create a new quote, view an existing quote, or browse all quotes for a given opportunity.

📘

Note

The Partner API currently supports PRM systems for accounts that use Salesforce (SFDC) or Microsoft Dynamics as their CRM.

How It Works

The diagram below describes the end-to-end flow, from initial CRM setup through quote submission:

sequenceDiagram
    actor Admin as DealHub Admin
    participant DH as DealHub
    participant PRM as Partner Relationship <br/>Management (PRM)
    participant CRM as Customer Relationship <br/>Management (SFDC, MSD, etc)
    Note over Admin,CRM: System configuration by admin (Manual activities - start)
    Admin->>DH: Enable DealHub Authenticator (via system settings)
    Admin->>DH: Define authentication key name and save authentication token generated by DH
    Admin->>DH: Specify trusted IP(s) from which partner will send requests to create/view quotes
    Admin->>PRM: Share generated authentication token with the partner
    Note over Admin,CRM: System configuration by admin (Manual activities - end)
    Note over Admin,CRM: Now partner would like to use DealHub platform (to create/view quotes)
    PRM->>CRM: Create opportunity at CRM
    Note over PRM,DH: The authenticate request should be sent from the PRM backend
    PRM->>DH: Get one-time access token based on authentication token - POST /api/v1/authenticate/user
    DH-->>PRM: one-time access token
    Note over DH,CRM: The create/open requests should be sent from the PRM web portal
		Note over DH,CRM: PRM should redirect the user to the URL returned by DealHub

    alt Create new quote
        PRM->>DH: POST /api/v1/create/quote
        DH-->>PRM: redirect URL to start quote creation
    else View specific quote
        PRM->>DH: POST /api/v1/open/quote
        DH-->>PRM: redirect URL to view existing quote
    else View list of existing quotes
        PRM->>DH: POST /api/v1/open/opportunity
        DH-->>PRM: redirect URL to view existing opportunity
    end
    Note over PRM,CRM: User will be able to work at DealHub portal as <br/>per the system boundaries of the authenticated session
    Note over DH,CRM: Once the user is redirected to CPQ, they can complete quote details and submit the quote
    Note over DH,CRM: Upon submit, CPQ will sync quote details to CRM
    DH->>CRM: sync quote

The behavior of the CRM sync on submit depends on the connected solution:

• Salesforce: sync runs on behalf of the opportunity owner.
• Microsoft Dynamics: sync runs as the integration user.

Prerequisites

Before making API calls, a DealHub CPQ administrator must complete the setup described below.

Enable the Partner Integration

Before the PRM system can authenticate partner users, a DealHub admin must enable the Partner API and generate an authentication key. Complete the following steps once per environment before any API calls are made:

1. In DealHub CPQ, navigate to System Settings > API Settings.
2. Under DealHub Authentication Tokens, check the Enable DealHub Authenticator checkbox.
3. Under Key Management, enter a name for the new key and click Add.
4. Copy the generated authentication key immediately. DealHub displays this value only once. If you lose the key, you must delete it and generate a new one.
5. Share the key securely with the PRM system that will consume the API.

Configure IP Allowlisting (Recommended for Production)

For each authentication key, you can restrict API requests to specific IP addresses.

• If you specify one or more IPs, DealHub only accepts requests from those addresses.
• If you leave the IP list empty, DealHub accepts requests from any IP.

❗️

Security recommendation

Always configure allowed IPs in production environments to prevent unauthorized use of the authentication key.

Best Practices

DealHub displays the key value only once at generation time. Store the authentication key in a secrets manager or environment variable, never in source code or client-side configuration files.

Authentication keys are permanent and do not expire. If you suspect a key has been exposed, delete it in System Settings immediately and generate a new one. Update the consuming system with the new key before the old one is removed.

Next Steps

Now, you can Authenticate Partner User to obtain a one-time access token, and use the access token to Open DealHub CPQ.