> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Workflow Status

> Activate, pause, deactivate, or resume a v1 workflow.

Changes state - verify before retry
Update Workflow Status changes whether a workflow is running or paused. Use this endpoint instead of the older action-specific workflow endpoints when integrating with `/v1`.

## When To Use Update Workflow Status

* Use `activate` when a validated workflow should start execution for its leads. It is also the action to use after uploading leads to a paused workflow.
* Use `deactivate` or `pause` when an active workflow should stop starting new leads. The two are the same operation.
* Use `resume` when a paused workflow should be active again and every lead it should process already has an execution.

## Status Actions

Each action moves the workflow to a specific status:

| Action | Status before | Status after | Result |
| - | - | - | - |
| `activate` | `draft` or `paused` | `active` | Runs the pre-activation checks, then starts execution for every lead that does not already have one, including leads uploaded while the workflow was paused. |
| `deactivate` | `active` | `paused` | Same as `pause`. |
| `pause` | `active` | `paused` | Stops new leads from starting, including through an inbound call, and holds queued calls until the workflow is active again. Leads already inside a step keep advancing (see below). |
| `resume` | `paused` | `active` | Sets the workflow active again. It does not start leads that were uploaded while the workflow was paused; use `activate` for those. |

## What pausing does not stop

Pausing changes the workflow status only. A lead that is already inside the workflow is not frozen:

* When a lead's wait step expires, the lead moves on to the next node, even in a paused workflow.
* When a call placed by a Voice Call node finishes, the lead is routed along that call's outcome.
* If either moves the lead into a Voice Call node, a call is queued. It is not dialed while the workflow is paused, and it is dialed once the workflow is active again after `resume` or `activate`.
* Application and Custom Function nodes the lead reaches still run.
* An inbound call from a lead that is already inside the workflow is still routed to the matching Voice Call node. A lead without an active execution (not started yet, or already finished) is not routed while the workflow is paused.

Pausing therefore holds outbound calls but does not cancel them: they go out when the workflow is active again. Removing a lead with [Delete Workflow Lead](https://dialnexa.com/docs/api-reference/v1/workflow-leads/delete.md) does not cancel its scheduled steps either.

See [Workflow Statuses](https://dialnexa.com/docs/workflows/workflow-statuses.md) for the full status model, activation validation rules, and how lead-level statuses differ from the workflow container status.

## Verify The Result

The response includes the full workflow record in `data.data`, and `data.message` names the action, for example `Workflow activated successfully`. Confirm that `data.data.status` matches the requested transition, then call [Get Workflow Details](https://dialnexa.com/docs/api-reference/v1/workflows/get.md) if your integration needs to refresh the workflow record later.

## Common Errors

* `400 Bad Request` means the action is invalid or the workflow status does not allow the transition.
* `422 Unprocessable Entity` means `activate` ran the pre-activation checks and the workflow failed them; the body lists what to fix.
* `401 Unauthorized` means the API key is missing or invalid.
* `404 Not Found` means the workflow ID was not found in this workspace. A workflow that belongs to another workspace is reported the same way.

See [API errors](https://dialnexa.com/docs/api-reference/api-fundamentals.md#handle-dialnexa-api-errors) for the standard error format.

## Related Endpoints

* [List Workflows](https://dialnexa.com/docs/api-reference/v1/workflows/list.md): find workflows in your workspace.
* [Get Workflow Details](https://dialnexa.com/docs/api-reference/v1/workflows/get.md): fetch a workflow by ID.
* [Workflow Leads](https://dialnexa.com/docs/api-reference/v1/workflow-leads/list.md): inspect leads attached to a workflow.


## OpenAPI

````yaml PATCH /v1/workflows/{id}/status
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/workflows/{id}/status:
    patch:
      tags:
        - Workflows
      summary: Update Workflow Status
      description: >-
        Changes a workflow status. `activate` (from `draft` or `paused`) runs
        the pre-activation checks, sets the workflow `active` and starts every
        lead that has no execution yet. `deactivate` and `pause` (from `active`)
        set it `paused`: no new lead starts, including through an inbound call,
        and queued calls are not dialed. Leads already inside a step keep
        advancing: an expiring time hold or a finished call can still move a
        lead into a Voice Call node, whose call is queued and dialed once the
        workflow is active again, and an inbound call from such a lead is still
        routed into the workflow. `resume` (from `paused`) sets it `active`
        again without starting leads that were uploaded while it was paused; use
        `activate` for those.
      operationId: updateWorkflowStatus
      parameters:
        - name: id
          required: true
          in: path
          description: Workflow ID
          schema:
            type: string
            example: workflow_abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowStatusRequest'
            examples:
              activate:
                summary: Activate a workflow
                value:
                  action: activate
              deactivate:
                summary: Deactivate a workflow
                value:
                  action: deactivate
              pause:
                summary: Pause a workflow
                value:
                  action: pause
              resume:
                summary: Resume a workflow
                value:
                  action: resume
      responses:
        '200':
          description: Workflow status updated successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    success: true
                    error: false
                    statusCode: 200
                    message: Success
                    data:
                      statusCode: 200
                      message: Workflow activated successfully
                      data:
                        id: workflow_abc123
                        title: Q3 Outreach Workflow
                        status: active
                        description: Automated follow-up sequence
                        organization_id: o14XKPP84rt22g
                        is_deleted: false
                        fallback_variables: []
                        createdAt: '2026-07-03T10:30:00.000Z'
                        updatedAt: '2026-07-03T10:45:00.000Z'
                    timestamp: '2026-09-07T06:00:00.000Z'
              schema:
                type: object
                required:
                  - success
                  - error
                  - statusCode
                  - message
                  - data
                  - timestamp
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  error:
                    type: boolean
                    enum:
                      - false
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      statusCode:
                        type: number
                        example: 200
                      message:
                        type: string
                        example: Workflow activated successfully
                        description: >-
                          Workflow activated, deactivated, paused or resumed
                          successfully.
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            example: workflow_abc123
                          title:
                            type: string
                            maxLength: 100
                            example: Q3 Outreach Workflow
                          status:
                            type: string
                            enum:
                              - draft
                              - active
                              - paused
                              - completed
                              - cancelled
                            example: active
                          description:
                            type: string
                            nullable: true
                            example: Automated follow-up sequence
                          organization_id:
                            type: string
                            description: Owning organization (raw ID).
                            example: o14XKPP84rt22g
                          is_deleted:
                            type: boolean
                            example: false
                          fallback_variables:
                            type: array
                            nullable: true
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                default_value:
                                  type: string
                            description: >-
                              Fallback values for lead variables missing from an
                              uploaded lead.
                          createdAt:
                            type: string
                            format: date-time
                          updatedAt:
                            type: string
                            format: date-time
                  timestamp:
                    type: string
                    format: date-time
        '400':
          description: >-
            Invalid action, or the action is not allowed for the workflow's
            current status (for example pausing a workflow that is not active,
            resuming one that is not paused, or activating one that is already
            active, completed or cancelled).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    error: true
                    success: false
                    data: []
                    message: >-
                      action must be one of the following values: activate,
                      deactivate, pause, resume
                    errors:
                      - >-
                        action must be one of the following values: activate,
                        deactivate, pause, resume
                alreadyActive:
                  summary: Activate an active workflow
                  value:
                    statusCode: 400
                    error: true
                    success: false
                    data: []
                    message: Workflow is already active
                    errors:
                      - Workflow is already active
                cannotActivate:
                  summary: Activate a completed workflow
                  value:
                    statusCode: 400
                    error: true
                    success: false
                    data: []
                    message: 'Cannot activate workflow with status: completed'
                    errors:
                      - 'Cannot activate workflow with status: completed'
                cannotPause:
                  summary: Pause a workflow that is not active
                  value:
                    statusCode: 400
                    error: true
                    success: false
                    data: []
                    message: 'Cannot pause workflow with status: draft'
                    errors:
                      - 'Cannot pause workflow with status: draft'
                cannotResume:
                  summary: Resume a workflow that is not paused
                  value:
                    statusCode: 400
                    error: true
                    success: false
                    data: []
                    message: 'Cannot resume workflow with status: active'
                    errors:
                      - 'Cannot resume workflow with status: active'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    error: true
                    success: false
                    data: []
                    message: Invalid API key
                    errors: []
        '404':
          description: Workflow not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    error: true
                    success: false
                    data: []
                    message: Workflow with ID Hk3pW9zQe1LmRt not found
                    errors: []
        '422':
          description: >-
            Unprocessable: `activate` ran the pre-activation checks and the
            workflow failed them. data.errors lists what to fix; data.warnings
            lists non-blocking issues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                activationChecksFailed:
                  summary: 422 Unprocessable Entity
                  value:
                    statusCode: 422
                    error: true
                    success: false
                    data:
                      errors:
                        - type: PHONE_NUMBER_MISSING
                          node_id: Rt5vN8kQ2wLz7x
                          node_label: Call lead
                          detail: >-
                            VoiceCall node "Call lead" has no phone number
                            configured
                      warnings: []
                    message: >-
                      Workflow cannot be activated due to validation errors.
                      Please fix the issues listed and try again.
                    errors: []
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    error: true
                    success: false
                    data: []
                    message: Internal server error
                    errors: []
      security:
        - bearer: []
components:
  schemas:
    UpdateWorkflowStatusRequest:
      type: object
      properties:
        action:
          type: string
          enum:
            - activate
            - deactivate
            - pause
            - resume
          description: >-
            activate validates the workflow, sets it active and starts leads
            without an execution; deactivate and pause set it paused, which
            stops new lead starts and holds queued calls until it is active
            again, but does not stop leads already in a step from advancing;
            resume sets a paused workflow active without starting leads added
            while paused.
          example: activate
      required:
        - action
    ErrorResponse:
      type: object
      description: Error body on endpoints without response filtering.
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: boolean
          enum:
            - true
        success:
          type: boolean
          enum:
            - false
        data:
          oneOf:
            - type: object
              properties:
                code:
                  type: string
                  description: Machine-readable refusal code.
            - type: array
              items: {}
          description: >-
            For a coded refusal, an object with code and the details listed for
            that code. Otherwise an empty array.
        message:
          type: string
        errors:
          type: array
          items:
            type: string
          description: Validation messages for a 400. Empty for other errors.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - statusCode
        - error
        - success
        - data
        - message
        - errors
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.