Version: v2

Destinations

Non-Production Preview

The Process Orchestration APIs are currently available as a Non-Production Preview (NPP) feature and are not available to all clients. For more information, see Process Orchestration.

Destinations are named, reusable external HTTP endpoint registrations. An External Orchestration process references a destination by its externalId to make outbound HTTP calls from within a BPMN process. Credentials are stored encrypted at rest and are never returned in GET responses — only the externalId, name, baseUrl, and authType are visible after creation.

Authentication types

Two authentication types are supported:

Type	Description
BASIC	HTTP Basic auth — username and password stored as secure properties
API_KEY	API key — key name and value stored as secure properties; sent as a request header. headerName defaults to api-key if omitted.

Endpoint summary

Method	Path	Description
POST	/destinations	Create a new destination draft
GET	/destinations	List all destinations
GET	/destinations/{externalId}	Get a specific destination by externalId
GET	/destinations/{externalId}/current	Get the current (active) revision of a destination
GET	/destinations/{externalId}/{revision}	Get a specific revision of a destination
PUT	/destinations/{externalId}/{revision}	Update a draft revision (for example, to rotate credentials)
DELETE	/destinations/{externalId}/{revision}	Delete a draft revision
POST	/destinations/{externalId}/{revision}/test	Test connectivity for a revision
POST	/destinations/{externalId}/{revision}:submit	Submit a draft revision for maker-checker approval
POST	/destinations:search	Search destinations

Creating a destination

BASIC auth

POST /api/destinations
Accept: application/vnd.mambu.v2+json
Content-Type: application/json
Authorization: Basic <base64-encoded username:password>

{
  "externalId": "my-crm",
  "name": "CRM System",
  "baseUrl": "https://crm.example.com",
  "authType": "BASIC",
  "secureProperties": {
    "username": "api_user",
    "password": "secret"
  }
}

API key auth

POST /api/destinations
Accept: application/vnd.mambu.v2+json
Content-Type: application/json
Authorization: Basic <base64-encoded username:password>

{
  "externalId": "payment-gateway",
  "name": "Payment Gateway",
  "baseUrl": "https://payments.example.com",
  "authType": "API_KEY",
  "secureProperties": {
    "headerName": "X-API-Key",
    "apiKey": "<your-api-key>"
  }
}

Request body fields

Field	Type	Required	Description
externalId	string	Yes	Unique business identifier for the destination (max 100 characters). Used in BPMN process definitions to reference this endpoint.
name	string	Yes	Human-readable display name (max 255 characters)
baseUrl	string	Yes	Base URL of the external service, must use https (max 500 characters). Process definitions append specific paths to this.
authType	enum	Yes	BASIC | API_KEY
secureProperties	object	No	Auth credentials. Fields depend on authType. Stored encrypted; never returned in GET responses.
verifyTlsCertificate	boolean	No	When false, outbound calls skip TLS chain and hostname verification. Defaults to true.

Destination lifecycle

DRAFT → PENDING_APPROVAL → APPROVED → CURRENT
                         └→ REJECTED

PUT updates a DRAFT revision. Use this to rotate credentials or update the base URL — you must provide the complete resource, including secureProperties. Only destinations in CURRENT status can be used by running process instances.

Deleting destinations

Deleting a destination that is actively referenced by a deployed process definition will cause runtime failures for that process. Ensure no active process definitions reference the destination before deleting it.