# Execute a Workflow Batch

POST https://api.smobi.com/v1/workflows/{workflowDefinitionId}/execute

Authentication: x-api-key header (brand-scoped API key).

Triggers workflow execution for a batch of customers. 
    Maximum 25 executions per request.
    For larger datasets, split into multiple requests.

## Operation

```json
{
  "description": "Triggers workflow execution for a batch of customers. \n    Maximum 25 executions per request.\n    For larger datasets, split into multiple requests.",
  "operationId": "executeBatch",
  "parameters": [
    {
      "name": "workflowDefinitionId",
      "required": true,
      "in": "path",
      "description": "Workflow definition identifier to execute",
      "schema": {
        "example": "wf_123e4567-e89b-12d3-a456-426614174000",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Workflow execution batch request",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "executions"
          ],
          "properties": {
            "executions": {
              "type": "array",
              "description": "One to 25 executions. Duplicate phone-number strings in the same batch are rejected.",
              "minItems": 1,
              "maxItems": 25,
              "items": {
                "type": "object",
                "required": [
                  "phoneNumber"
                ],
                "properties": {
                  "phoneNumber": {
                    "type": "string",
                    "description": "Phone number in E.164 format (+1234567890) or digits-only format (1234567890)",
                    "pattern": "^(^\\+[1-9]\\d{1,14}$|^[1-9]\\d{1,14}$)$",
                    "examples": [
                      "+14155552222",
                      "14155552222"
                    ]
                  },
                  "variables": {
                    "type": "object",
                    "description": "Variables for the workflow execution",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "example": {
                      "customer.name": "John Doe",
                      "customer.phone": "15552223333",
                      "order.id": "12345"
                    }
                  },
                  "settings": {
                    "type": "object",
                    "description": "Accepted by request validation, but replaced with server-selected routing before the batch is queued. Omit this object. channelOverride is stripped and does not take effect for batches; use single execution for a supported override.",
                    "properties": {
                      "channel": {
                        "type": "string",
                        "enum": [
                          "SMS",
                          "RCS",
                          "MMS"
                        ],
                        "description": "Messaging channel."
                      },
                      "provider": {
                        "type": "string",
                        "enum": [
                          "VONAGE",
                          "VIBES",
                          "TWILIO"
                        ],
                        "description": "Messaging provider."
                      },
                      "agentId": {
                        "type": "string",
                        "description": "Agent identifier."
                      },
                      "agentReferenceId": {
                        "type": "string",
                        "description": "Agent reference identifier."
                      }
                    }
                  }
                }
              },
              "example": [
                {
                  "phoneNumber": "14155552222",
                  "variables": {
                    "customer.name": "John Doe",
                    "customer.phone": "15552223333",
                    "order.id": "12345"
                  }
                }
              ]
            }
          }
        },
        "examples": {
          "withoutVariables": {
            "summary": "Without variables",
            "description": "Execute workflow for multiple customers",
            "value": {
              "executions": [
                {
                  "phoneNumber": "15552223333"
                },
                {
                  "phoneNumber": "15552223334"
                }
              ]
            }
          },
          "withVariables": {
            "summary": "With variables",
            "description": "Execute workflow for multiple customers with variables",
            "value": {
              "executions": [
                {
                  "phoneNumber": "15552223333",
                  "variables": {
                    "customerName": "John Doe",
                    "orderId": "12345",
                    "discountCode": "SAVE20"
                  }
                },
                {
                  "phoneNumber": "15552223334",
                  "variables": {
                    "customerName": "Jane Smith",
                    "orderId": "67890",
                    "discountCode": "SAVE30"
                  }
                }
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Batch accepted for processing",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExecuteWorkflowBatchResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request - batch size exceeded or validation error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "statusCode": {
                "type": "number",
                "example": 400
              },
              "message": {
                "type": "string",
                "example": "Batch exceeds maximum allowed 25 executions. Split your request into smaller batches."
              },
              "error": {
                "type": "string",
                "example": "Bad Request"
              },
              "suggestion": {
                "type": "string",
                "example": "Split your request into smaller batches or use our bulk import API for large datasets."
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - Invalid API key or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Invalid API key"
              },
              "error": {
                "type": "string",
                "example": "Unauthorized"
              },
              "statusCode": {
                "type": "number",
                "example": 401
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - Insufficient permissions to access the workflow",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Access denied to workflow"
              },
              "error": {
                "type": "string",
                "example": "Forbidden"
              },
              "statusCode": {
                "type": "number",
                "example": 403
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "Not Found - Workflow not found or does not exist",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Workflow not found"
              },
              "error": {
                "type": "string",
                "example": "Not Found"
              },
              "statusCode": {
                "type": "number",
                "example": 404
              }
            }
          }
        }
      }
    },
    "422": {
      "description": "Unprocessable Entity - Workflow validation errors, circular dependencies, or invalid variable references",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Workflow validation failed"
              },
              "error": {
                "type": "string",
                "example": "Unprocessable Entity"
              },
              "statusCode": {
                "type": "number",
                "example": 422
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error - Unexpected server error during workflow execution",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Internal server error"
              },
              "error": {
                "type": "string",
                "example": "Internal Server Error"
              },
              "statusCode": {
                "type": "number",
                "example": 500
              }
            }
          }
        }
      }
    }
  },
  "summary": "Execute a Workflow Batch",
  "tags": [
    "Workflows"
  ],
  "security": [
    {
      "x-api-key": []
    }
  ]
}
```

## Referenced Schemas

```json
{
  "ExecuteWorkflowBatchResponse": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean",
        "description": "Whether the batch was successfully queued",
        "example": true
      },
      "executions": {
        "description": "List of executions with their generated IDs",
        "example": [
          {
            "phoneNumber": "15552223333",
            "executionId": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
            "phoneNumber": "15552223334",
            "executionId": "987fcdeb-51a2-43d7-8f9e-123456789abc"
          }
        ],
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/BatchExecutionResponseItem"
        }
      }
    },
    "required": [
      "success",
      "executions"
    ]
  },
  "BatchExecutionResponseItem": {
    "type": "object",
    "properties": {
      "phoneNumber": {
        "type": "string",
        "description": "Phone number for this execution",
        "example": "15552223333"
      },
      "executionId": {
        "type": "string",
        "description": "Generated execution ID for this workflow run",
        "example": "123e4567-e89b-12d3-a456-426614174000"
      },
      "channel": {
        "type": "string",
        "description": "Channel that will be used for message delivery (RCS, SMS, or MMS)",
        "example": "RCS"
      }
    },
    "required": [
      "phoneNumber",
      "executionId"
    ]
  }
}
```