Skip to content
HubSpot Developer Changelog

Public beta: New DealSplits API

We are excited to announce the release of the new DealSplits Public API for HubSpot customers, which will be live starting May 28, 2024. This API lets customers list and create deal splits for batches of deals directly through HubSpot's CRM. The DealSplits Public API enhances revenue forecasting accuracy and sales team performance tracking by allowing for more granular deal attribution. This new API addresses a critical need for businesses to accurately attribute revenue and track sales performance across team members.

What's new?

List Deal Splits for a Batch of Deals: This allows fetching a list of deal IDs to deal splits for all input IDs in the request object.
  • HTTP Method + Path: POST /crm/v3/objects/deals/splits/batch/read

Request object example:

// Request example { "inputs": [ { "id": "4533747560" // deal objectId } ] }

Response example:

// Response example { "status": "COMPLETE", "results": [ { "id": "4533747560", "splits": [ { "id": "50636518818", "properties": { "hs_deal_split_percentage": "0.6", "hubspot_owner_id": "88345679" }, "createdAt": "2023-11-15T21:32:18.990Z", "updatedAt": "2023-11-15T21:32:18.990Z", "archived": false }, { "id": "50636518819", "properties": { "hs_deal_split_percentage": "0.4", "hubspot_owner_id": "148111145" }, "createdAt": "2023-11-15T21:32:18.990Z", "updatedAt": "2023-11-15T21:32:18.990Z", "archived": false } ] } ], "startedAt": "2023-11-29T15:47:46.079Z", "completedAt": "2023-11-29T15:47:46.301Z" }

 

Create Deal Splits for a Batch of Deals: This enables creating deal splits for a batch of deals with specified split percentages and owners.
  • HTTP Method + Path: POST /crm/v3/objects/deals/splits/batch/upsert

Request object example:

// Request example { "inputs": [ { "id": 4533747560, // deal objectId "splits": [ { "ownerId": 88345679, "percentage": 0.5 }, { "ownerId": 129556876, "percentage": 0.5 } ] } ] }

Response example:

// Response example { "status": "COMPLETE", "results": [ { "id": "4533747560", "splits": [ { "id": "51132142674", "properties": { "hs_deal_split_percentage": "0.5", "hubspot_owner_id": "88345679" }, "createdAt": "2023-11-29T15:57:33.027Z", "updatedAt": "2023-11-29T15:57:33.027Z", "archived": false }, { "id": "51132142675", "properties": { "hs_deal_split_percentage": "0.5", "hubspot_owner_id": "129556876" }, "createdAt": "2023-11-29T15:57:33.029Z", "updatedAt": "2023-11-29T15:57:33.029Z", "archived": false } ] } ], "startedAt": "2023-11-29T15:57:32.964Z", "completedAt": "2023-11-29T15:57:33.547Z" }

The API supports OAuth for authentication, ensuring secure access to the functionality. The required scope group for accessing the API is crm.dealsplits.read_write.

Note: For POST batch requests, all input items must pass the percentage validation, meaning this beta currently doesn’t support partial successes. The request will be rejected if any items in the batch request fail validation.

Validations:

  • The API performs validations to ensure the integrity of the deal splits, including verifying the validity of the deal objectId, ensuring the sum of deal split percentages equals 100%, and confirming the deal has an assigned owner included in the deal splits.
  • Portal self-service validations support up to 10 deal splits for admin privileges, with a default of 5 splits for all other users. There is no minimum split percentage.
  • Errors, such as batch sizes exceeding 100 or portals not enabling deal splits, are communicated through 400 and 403 response statuses, respectively.

When is it happening?

This new API is live and available to the public. Questions or comments? Join us in the developer forums.