Deals

Set the deal's custom status

PATCH/deals/{dealId}/custom-status
deals:writeset_deal_custom_statusDeprecatedSunset 2027-06-30

Sets the deal's custom status. status is the id of an org-defined deal status value (or null to clear); the current status is moved to previous_status. notify=true dispatches an in-app notification to the deal's participants and emails the deal's classified-investor audience (the users holding the deal's classifications, minus its exclusions) that the status changed. No email is sent while the deal is a draft. It can be undone by setting the previous status again, and emits deal.updated in the legacy envelope (data.deal). Deprecated: it will be withdrawn on 2027-06-30. POST /deals/{id}/actions/set-custom-status replaces it, and every answer carries a Link header with rel="successor-version" naming it. The action takes custom_status_id instead of status and returns the deal.

Path parameters

  • dealIdstring (uuid)Required#

    The deal's public uuid.

Request body

application/json, required

  • statusstring | nullRequired#

    Deal custom-status value id (an org-configured custom status, not a fixed enum), or null to clear.

  • notifyboolean#
    Default: false
{
  "status": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "notify": true
}

Responses

200

OK

DealCustomStatus
{
  "data": {
    "status": {
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "label": "Under Offer"
    },
    "previous_status": {
      "id": "2b3c4d5e-6f70-4182-9304-5a6b7c8d9e0f",
      "label": "Available"
    }
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
422

Request validation failed (HTTP 422). The body is either the Laravel validation envelope (message + field-keyed errors) or the API error envelope for domain rejections (e.g. form_type_not_supported, folder_locked, parent_not_found, folder_not_empty).

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X PATCH https://your-org-domain/kong/core/api/v2/deals/{dealId}/custom-status\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "status": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "notify": true
}'