> ## 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
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
Update Workflow Status changes whether a workflow is running, paused, or inactive. 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.
* Use `deactivate` when an active workflow should stop accepting new execution work.
* Use `pause` when a running workflow needs a temporary stop.
* Use `resume` when a paused workflow should continue.
## Status Actions
Each action moves the workflow to a specific status:
| Action | Status before | Status after | Result |
| ------------ | ------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `activate` | `draft` or `paused` | `active` | Validates the workflow, then starts execution for leads that do not already have execution records. |
| `deactivate` | `active` | `paused` | Stops future lead movement. Leads already inside an active call step can finish. |
| `pause` | `active` | `paused` | Pauses a running workflow. |
| `resume` | `paused` | `active` | Continues lead processing from each lead's current node. |
See [Workflow Statuses](/docs/workflows/workflow-statuses) 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 `data.status`. Confirm that the status matches the requested transition, then call [Get Workflow Details](/docs/api-reference/v1/workflows/get) if your integration needs to refresh the full workflow record.
## Common Errors
* `400 Bad Request` means the action is invalid, the workflow status does not allow the transition, or workflow validation failed.
* `403 Forbidden` means the workflow does not belong to the authenticated workspace.
* `404 Not Found` means the workflow ID was not found.
See [Errors](/docs/api-reference/errors) for the standard error format.
## Related Endpoints
* [List Workflows](/docs/api-reference/v1/workflows/list): find workflows in your workspace.
* [Get Workflow Details](/docs/api-reference/v1/workflows/get): fetch a workflow by ID.
* [Workflow Leads](/docs/api-reference/v1/workflow-leads/list): inspect leads attached to a workflow.
## OpenAPI
````yaml PATCH /v1/workflows/{id}/status
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/workflows/{id}/status:
patch:
tags:
- Workflows V1
- V1
summary: Update Workflow Status
description: >-
Changes a workflow status. Use `activate` to start execution for all
leads, `deactivate` to pause a currently active workflow, `pause` to
pause a running workflow, or `resume` to continue a paused workflow.
operationId: WorkflowsV1Controller_updateStatus
parameters:
- name: id
required: true
in: path
description: Workflow ID
schema:
type: string
example: workflow_abc123
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
properties:
action:
type: string
enum:
- activate
- deactivate
- pause
- resume
example: activate
description: The workflow status transition to apply.
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:
statusCode: 200
message: Workflow activated successfully
data:
id: workflow_abc123
title: Q3 Outreach Workflow
status: active
description: Automated follow-up sequence
createdAt: '2026-07-03T10:30:00.000Z'
updatedAt: '2026-07-03T10:45:00.000Z'
schema:
type: object
properties:
statusCode:
type: number
example: 200
message:
type: string
example: Workflow activated successfully
data:
type: object
properties:
id:
type: string
example: workflow_abc123
title:
type: string
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
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
'400':
description: >-
Invalid action, invalid workflow status, or workflow validation
failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: >-
Invalid action. Must be one of: activate, deactivate,
pause, resume
error: Bad Request
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden - workflow does not belong to your organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this resource
error: Forbidden
'404':
description: Workflow not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 404 Not Found
value:
statusCode: 404
message: Workflow not found
error: Not Found
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````