Give a workflow step a custom form

POST/workflow-steps/{id}/actions/set-custom-form

transaction-workflows:write set_custom_form_workflow_stepDestructiveIdempotent

Replaces the step's custom form and returns the step. The investor gets the form on entering the step and must complete it to leave, unless optional. doc_gen_template_id, a template of that form, also generates a document. Delegating to the deal returns 409 invalid_state once a published deal uses the workflow. It emits no webhook; has_custom_form: false undoes it.

Path parameters

idstring (uuid)Required#
The record's id.

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, required

form_idstring | null#
The form, from GET /forms. Required unless delegate_config_to_deal.
optionalboolean#
Whether the investor can leave the step without completing the form. Defaults to false.
delegate_config_to_dealboolean#
Each deal picks the form with a step config override.
delegate_doc_gen_to_dealboolean#
Each deal sets up document generation with a step config override.
doc_gen_template_idstring | null#
The form template to generate a document from. Needs doc_gen_template_name.
doc_gen_template_namestring | null#
The generated document's name.
signature_request_typestring | null#
How the generated document is signed: wet_ink on paper, electronic or soft in the platform, esig_connective or esig_connective_single through Connective, esig_docusign through DocuSign. Null for no signature.
One of: wet_ink, electronic, soft, esig_connective, esig_connective_single, esig_docusign
docusign_cc_recipientsstring[]#
Who DocuSign copies in.
docusign_require_2faboolean#
Whether DocuSign signers need two-factor authentication.
docusign_template_idsstring[]#
The DocuSign templates to use.
docusign_template_onlyboolean#
Whether DocuSign sends only its templates, not the generated document.
docusign_recipient_bindingsobject[]#
Who signs each DocuSign recipient role, for esig_docusign only. 422 invalid names the first bad binding.
docusign_send_helper_textstring | null#
Shown to whoever sends the document through DocuSign. For esig_docusign only.

{
  "form_id": "4f5a6b7c-8d9e-4f0a-9b1c-2d3e4f5a6b7c",
  "doc_gen_template_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
  "doc_gen_template_name": "Subscription agreement",
  "signature_request_type": "esig_docusign"
}

Responses

200

The step, with its new form requirement and triggers.

WorkflowStep

{
  "data": {
    "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "workflow_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "name": "string",
    "label": "string",
    "type": "string",
    "kind": "linear",
    "description": "string",
    "is_protected": true,
    "is_floating": true,
    "order": 1,
    "has_custom_form": true,
    "is_internal_only": true,
    "show_default_internal_message": true,
    "document_upload": {
      "optional": true,
      "document_name": "string",
      "document_instruction": "string"
    },
    "minimum_investment": {
      "optional": true,
      "disclaimer": "string"
    },
    "document_release": {
      "folder_name": "string"
    },
    "webhook": {
      "webhook_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "leading_edge": true
    },
    "posts_to_portfolio": true,
    "info_banner": {
      "title": "string",
      "body": "string",
      "delegated_to_deal": true
    },
    "requirements": [
      {
        "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
        "class_name": "string",
        "leading_edge": true,
        "optional": true,
        "delegated_to_deal": true,
        "config": {}
      }
    ],
    "triggers": [
      {
        "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
        "class_name": "string",
        "leading_edge": true,
        "delegated_to_deal": true,
        "config": {}
      }
    ],
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10: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/workflow-steps/{id}/actions/set-custom-form\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "form_id": "4f5a6b7c-8d9e-4f0a-9b1c-2d3e4f5a6b7c",
  "doc_gen_template_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
  "doc_gen_template_name": "Subscription agreement",
  "signature_request_type": "esig_docusign"
}'