Promote a deal to investors

POST/deals/{id}/actions/promote

Emails a promotion for a published deal and returns the deal; its status doesn't change and it can be promoted again. With no body, the email goes to the investors who can see the deal through its visibility rules: user rules first, then team, then classification, with exclusions applied before inclusions at each level, investors only. The visibility of the token's own user is ignored. With distribution_list_id, investor_ids or both, the recipients are the members of the list, whether or not they can see the deal, plus the given investors who can see it. The emails use the promote_deal template, are queued after the request commits and aren't sent for a dry_run. When nobody qualifies it returns 200 with the deal and emits no event. A distribution list outside the organisation returns 422. A deal that is not published returns 409 invalid_state. Emits deal.promoted. It can't be undone.

Path parameters

idstring (uuid)Required#
The deal's id, a uuid. An unknown id, or a deal the token can't see, returns 404.

Query parameters

dry_runboolean#
Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

Idempotency-Keystring#
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, optional · DealPromote

investor_idsstring (uuid)[]#
Investors to promote to, by id. Only those who can see the deal are emailed.
distribution_list_idinteger#
A distribution list in your organisation. Its members are emailed whether or not they can see the deal.
titlestring | null#
The email title. The template's default is used when it is null or omitted.
bodystring | null#
The email message. The template's default is used when it is null or omitted.

{
  "distribution_list_id": 12,
  "title": "New documents added",
  "body": "We have added the latest investor presentation to the data room."
}

Responses

200

The deal, after the promotion was queued.

Deal

{
  "data": {
    "id": "f6071829-3a4b-4c5d-9e6f-8091a2b3c4d5",
    "name": "Series B — Acme Robotics",
    "status": "published",
    "external": false,
    "external_id": "CRM-2026-0042",
    "summary": "Late-stage growth round in autonomous logistics.",
    "description": "<p>Acme Robotics is raising a Series B.</p>",
    "currency": "USD",
    "min_investment": 25000,
    "structure": "direct",
    "sub_structure": "equity",
    "type_details": {
      "sector": "information_technology",
      "growthStage": "growth"
    },
    "sponsor": "Acme Capital",
    "show_funding_secured": true,
    "allow_questions": false,
    "request_further_docs": false,
    "available_from": "2026-07-01T00:00:00+00:00",
    "available_to": "2026-09-30T23:59:59+00:00",
    "transaction_workflow_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "investor_engagement_enabled": true,
    "active_tranche_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "drafted_at": "2026-06-15T10:30:00+00:00",
    "approval_started_at": "2026-06-16T09:00:00+00:00",
    "approved_at": "2026-06-17T09:00:00+00:00",
    "published_at": "2026-06-18T09:00:00+00:00",
    "rejected_at": null,
    "retired_at": null,
    "tabs": [
      "deal",
      "documents",
      "video"
    ],
    "image_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "sponsor_image_id": null,
    "video_id": "76979871",
    "custom_status_id": null,
    "created_at": "2026-06-15T10:30:00+00:00",
    "updated_at": "2026-06-18T09:00:00+00:00"
  }
}

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

409

The request conflicts with existing state (error.code = conflict), e.g. a compliance flow with the requested name already exists.

Error

422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/deals/{id}/actions/promote\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "distribution_list_id": 12,
  "title": "New documents added",
  "body": "We have added the latest investor presentation to the data room."
}'