Process Runs

Process runs are active or completed instances of a process template. Each run contains its own copy of the tasks with independent completion status and form field values.

List Runs


GET /api/v1/process-runs

Returns a paginated list of process runs, newest first.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (1-100)
`cursor`	string	—	Cursor for pagination
`template_id`	string	—	Filter by template ID
`status`	string	—	Filter by status: `active` or `completed`

Example Request


# List active runs for a specific template
curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs?status=active&template_id=CcIJXVzRuiP5HvI26FTE"

Example Response


{
  "data": [
    {
      "id": "CWpVWwuj7Jkvl3Smlyxb",
      "template_id": "CcIJXVzRuiP5HvI26FTE",
      "title": "Employee Onboarding - Jane Smith",
      "status": "active",
      "started_by": "user123",
      "team_id": "team_abc",
      "timezone": "Pacific/Auckland",
      "due_date": null,
      "is_shared": false,
      "sections": [
        { "id": "sec_abc", "title": "First Week", "order": 0, "color": "#EC4899" }
      ],
      "created_at": "2026-03-27T02:08:05.224Z",
      "updated_at": null,
      "completed_at": null
    }
  ],
  "pagination": {
    "next_cursor": "CWpVWwuj7Jkvl3Smlyxb",
    "has_more": false
  }
}

Create a Run


POST /api/v1/process-runs

Start a new process run from a template. The template must be published. A run is a frozen snapshot — it copies the template’s tasks and form fields at creation time, so later template edits never affect existing runs.

Request Body

Field	Type	Required	Description
`template_id`	string	Yes	ID of the template to run
`name`	string	No	Custom title for the run (defaults to template title). `title` is accepted as an alias.
`due_date`	string	No	ISO 8601 due date
`actor_email`	string	No	Email of an active team member to attribute the run to (see below)
`custom_elements`	array	No	Pre-fill form field values (see below)

Attributing the run to a person

By default, API-created runs are attributed to "api" and appear only under the Team tab in the app — not in any individual’s Personal tab. To make a run show up in a specific person’s Personal tab, pass their email as actor_email. The email must belong to an active member of the team; if it doesn’t match a member, the run falls back to "api". When attributed, any tasks assigned to the “workflow runner” are also assigned to that person, and they receive assignment notification emails.

actor_email is for team members (people with accounts). To share a run with an external customer, create the run first, then use Share a Run with a Guest below.

Custom elements (form fields) are inherited from the template only at run-creation time. custom_elements can pre-fill the values of fields that already exist on the template, but cannot add new fields. To change which fields a run has, edit the template and republish: unpublish it (POST /process-templates/:id/publish with { "published": false }), make your edits, then publish again. New runs pick up the changes; existing runs are unaffected.

Pre-filling Form Fields

You can set initial values for form fields when creating a run:


{
  "template_id": "CcIJXVzRuiP5HvI26FTE",
  "name": "Onboarding - Jane Smith",
  "custom_elements": [
    {
      "task_id": "Y9Rxzi3uDOvGAYojkHti",
      "element_id": "elem_001",
      "value": "Jane Smith"
    },
    {
      "task_id": "Y9Rxzi3uDOvGAYojkHti",
      "element_id": "elem_002",
      "value": "jane@company.com"
    }
  ]
}

Use the List Template Tasks endpoint to discover task IDs and element IDs for pre-filling.

Example Request


curl -X POST \
  -H "Authorization: Bearer nxs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "CcIJXVzRuiP5HvI26FTE", "name": "Onboarding - Jane Smith"}' \
  "https://getnextstep.io/api/v1/process-runs"

Example Response (201 Created)


{
  "data": {
    "id": "new_run_id",
    "template_id": "CcIJXVzRuiP5HvI26FTE",
    "title": "Onboarding - Jane Smith",
    "status": "active",
    "started_by": "api",
    "team_id": "team_abc",
    "timezone": "Pacific/Auckland",
    "created_at": "2026-04-07T10:00:00.000Z",
    "completed_at": null
  }
}


POST /api/v1/process-runs/:id/invite

Share an existing run with an external customer (a guest — someone without a NextStep account). This always enables link sharing on the run (is_shared: true, so the guest can open it without signing in) and returns the guest-accessible share_url.

The email field is optional and controls whether we send an invitation:

With email — we send a branded invitation email (the same one the app’s Share via Email sends) with the link, and record the guest against the run.
Without email — we just enable sharing and return the share_url, sending nothing. Use this when you deliver the link yourself (e.g. from your own email or system).

Create the run first (with Create a Run), then share it.

This is for external customers only. A run can have one guest. To bring a team member into a run, attribute it to them with actor_email on Create a Run instead — passing a team member’s email here returns an error.

Request Body

Field	Type	Required	Description
`email`	string	No	The guest’s email. If provided, we send a branded invitation email. Omit to just get the `share_url` back without sending anything.
`enable_reminders`	boolean	No	Email the guest a reminder if they haven’t engaged. Only applies when `email` is provided (default `false`).
`reminder_days`	integer	No	Days to wait before reminding (default `7`)

Example — get a share link only (no email sent)


curl -X POST \
  -H "Authorization: Bearer nxs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/invite"


{
  "data": {
    "run_id": "CWpVWwuj7Jkvl3Smlyxb",
    "invited_email": null,
    "is_shared": true,
    "share_url": "https://yourteam.getnextstep.io/instance/CWpVWwuj7Jkvl3Smlyxb",
    "sent_process_run_id": null
  }
}

Example — send an invitation email


curl -X POST \
  -H "Authorization: Bearer nxs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@client.com"}' \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/invite"


{
  "data": {
    "run_id": "CWpVWwuj7Jkvl3Smlyxb",
    "invited_email": "customer@client.com",
    "is_shared": true,
    "share_url": "https://yourteam.getnextstep.io/instance/CWpVWwuj7Jkvl3Smlyxb",
    "sent_process_run_id": "abc123"
  }
}

Anyone with the share_url can open the run — the link itself is the access.

Notifying the guest at each stage

Stage-by-stage emails (a task becoming ready, a step to complete) are driven by task assignment, not by sharing. To have the guest notified about specific steps, assign those tasks to their email address — see Update a Task.

Get a Run


GET /api/v1/process-runs/:id

Returns a single process run by ID.

Example Request


curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb"

List Run Tasks


GET /api/v1/process-runs/:id/tasks

Returns all tasks in a process run, ordered by position. Each task includes its current completion status and form field values.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (1-100)
`cursor`	string	—	Cursor for pagination

Example Request


curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/tasks"

Example Response


{
  "data": [
    {
      "id": "POPXQSSPZnYNjUz7QBbn",
      "instance_id": "CWpVWwuj7Jkvl3Smlyxb",
      "template_task_id": "Y9Rxzi3uDOvGAYojkHti",
      "title": "Review employee details",
      "completed": true,
      "completed_at": "2026-04-07T02:29:18.865Z",
      "completed_by": "user123",
      "order": 0,
      "section_id": "sec_abc",
      "assignee": "user123",
      "is_essential": false,
      "type": "task",
      "custom_elements": [
        {
          "id": "elem_001",
          "type": "shortText",
          "label": "Employee Name",
          "value": "Jane Smith",
          "required": true,
          "display_only": false
        },
        {
          "id": "elem_002",
          "type": "email",
          "label": "Employee Email",
          "value": "jane@company.com",
          "required": true,
          "display_only": false
        }
      ],
      "created_at": "2026-03-27T02:08:05.224Z"
    }
  ],
  "pagination": {
    "next_cursor": "POPXQSSPZnYNjUz7QBbn",
    "has_more": true
  }
}