Create a workflow. It starts paused unless status is "active".

POSThttps://app.softsolz.uk/api/v1/services/workflows/workflows

Recent Requests

Kept only in this browser

TimeStatusTook

Send a request with Try it to see it here.

Headers

Authorizationstringrequired

Bearer token: `Bearer sk_live_...` (or `sk_test_...` for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

namestringrequired

Workflow name.

descriptionstring | null

Optional description.

trigger_typestring

How the workflow runs. Defaults to "schedule" when cron_expression is sent, otherwise "manual".

cron_expressionstring | null

Required when trigger_type is "schedule": 5 parts, for example "0 9 * * *" for every day at 9am.

timezonestring

Schedule timezone (default "UTC").

statusstring

Initial status (default "paused", the same as a new workflow in the app).

visibilitystring

Default "tenant". A plain API key can only use "tenant" (400 private_needs_member otherwise); "private" and "shared" need a member connected through a connected app.

stepsarray of objectsrequired

Ordered workflow steps. At least one (400 steps_required).

Response

Response Body

idstringWorkflow id.

namestringWorkflow name.

descriptionstring | nullOptional description.

statusstringSchedule status.

trigger_typestringHow the workflow starts. event and webhook only appear on workflows built on the canvas.

cron_expressionstring | null5-field cron expression (when trigger_type is schedule).

built_onstringapi when the steps below are the full definition; canvas when the workflow was built or changed on the canvas in the app, in which case steps is a read-only outline.

trigger_eventstring | nullThe event that starts the workflow, for event-started workflows.

trigger_webhook_tokenstringPrivate token of an incoming-webhook workflow. Only returned by GET /workflows/:id, create and update, and only to keys holding service.workflows.workflows.manage. Never in lists.

graphobjectThe current steps and how they connect, as built on the canvas.

timezonestringSchedule timezone.

visibilitystringWho can see/edit it.

stepsarray of objectsOrdered step definitions. For built_on canvas this is a read-only outline: { step_order, step_type, label, read_only }.

created_atstringCreation timestamp.

updated_atstringLast update timestamp.

Request

curl --request POST \
  --url https://app.softsolz.uk/api/v1/services/workflows/workflows \
  --header 'Authorization: Bearer sk_live_your_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Monthly AR summary",
  "description": "Emails the receivables digest each month.",
  "trigger_type": "schedule",
  "cron_expression": "0 9 1 * *",
  "timezone": "Europe/London",
  "status": "paused",
  "visibility": "tenant",
  "steps": [
    {
      "step_type": "invoicing_ar_summary",
      "step_config": {
        "date_range": "previous_month"
      }
    },
    {
      "step_type": "send_email",
      "step_config": {
        "to": [
          "ops@example.com"
        ],
        "subject": "Monthly AR"
      }
    }
  ]
}'

Credentials

Authorization

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 201

{
  "data": {
    "id": "3f2a8c10-9b4e-4f7a-bb21-0c6d5e8a1f90",
    "name": "Monthly AR summary",
    "description": "Emails the receivables digest each month.",
    "status": "active",
    "trigger_type": "schedule",
    "cron_expression": "0 9 1 * *",
    "built_on": "api",
    "trigger_event": "contacts.created",
    "trigger_webhook_token": "whk_3c1f0e",
    "graph": {
      "nodes": [
        {
          "key": "trigger",
          "type": "core.manual",
          "label": "Manual",
          "kind": "trigger"
        },
        {
          "key": "create_notification_1",
          "type": "core.create_notification",
          "label": "Notify the team",
          "kind": "action"
        }
      ],
      "edges": [
        {
          "from": "trigger",
          "to": "create_notification_1",
          "branch": null
        }
      ]
    },
    "timezone": "Europe/London",
    "visibility": "tenant",
    "steps": [
      {
        "step_order": 1,
        "step_type": "invoicing_ar_summary",
        "step_config": {
          "date_range": "previous_month"
        }
      }
    ],
    "created_at": "2026-05-01T09:00:00.000Z",
    "updated_at": "2026-05-12T14:30:00.000Z"
  }
}