# Execute the Current Workflow Version

POST https://api.smobi.com/v1/workflows/family/{workflowFamilyId}/execute/{phoneNumber}

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

Execute the current version of a workflow family for a single phone number

## Operation

```json
{
  "description": "Execute the current version of a workflow family for a single phone number",
  "operationId": "executeFamily",
  "parameters": [
    {
      "name": "workflowFamilyId",
      "required": true,
      "in": "path",
      "description": "ID of the workflow family to execute (will execute the current version)",
      "schema": {
        "example": "wf_123e4567-e89b-12d3-a456-426614174000",
        "type": "string"
      }
    },
    {
      "name": "phoneNumber",
      "required": true,
      "in": "path",
      "description": "Phone number of the customer to execute the workflow for",
      "schema": {
        "example": "15552223333",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Family workflow execution request",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ExecuteFamilyWorkflow"
        },
        "examples": {
          "withoutVariables": {
            "summary": "Without variables",
            "description": "Execute current version of workflow family",
            "value": {}
          },
          "withVariables": {
            "summary": "With variables",
            "description": "Execute current version of workflow family with variables",
            "value": {
              "variables": {
                "customerName": "John Doe",
                "orderId": "12345",
                "discountCode": "SAVE20"
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Family workflow execution result",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExecuteFamilyWorkflowResponse"
          },
          "example": {
            "executionId": "run-123",
            "success": true,
            "channel": "RCS"
          }
        }
      }
    },
    "400": {
      "description": "Bad Request - Invalid request parameters",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Invalid phone number format"
              },
              "error": {
                "type": "string",
                "example": "Bad Request"
              },
              "statusCode": {
                "type": "number",
                "example": 400
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - Invalid API key",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Invalid API key"
              },
              "error": {
                "type": "string",
                "example": "Unauthorized"
              },
              "statusCode": {
                "type": "number",
                "example": 401
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "Not Found - Workflow family not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Workflow family not found"
              },
              "error": {
                "type": "string",
                "example": "Not Found"
              },
              "statusCode": {
                "type": "number",
                "example": 404
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error - No current version set for workflow family",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "No current version set for workflow family"
              },
              "error": {
                "type": "string",
                "example": "Internal Server Error"
              },
              "statusCode": {
                "type": "number",
                "example": 500
              }
            }
          }
        }
      }
    }
  },
  "summary": "Execute the Current Workflow Version",
  "tags": [
    "Workflows"
  ],
  "security": [
    {
      "x-api-key": []
    }
  ]
}
```

## Referenced Schemas

```json
{
  "ExecuteFamilyWorkflow": {
    "type": "object",
    "properties": {
      "variables": {
        "type": "object",
        "description": "Map of workflow variable names to string values. Keys must match the selected workflow. Omit when no variables are needed.",
        "example": {
          "customerName": "John Doe",
          "orderId": "12345",
          "discountCode": "SAVE20"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "settings": {
        "description": "Workflow execution settings including channel overrides",
        "example": {
          "channelOverride": "RCS"
        },
        "allOf": [
          {
            "$ref": "#/components/schemas/WorkflowExecutionSettings"
          }
        ]
      }
    }
  },
  "WorkflowExecutionSettings": {
    "type": "object",
    "properties": {
      "channelOverride": {
        "type": "string",
        "description": "Channel override for the workflow execution",
        "enum": [
          "RCS",
          "SMS"
        ],
        "example": "RCS"
      }
    }
  },
  "ExecuteFamilyWorkflowResponse": {
    "type": "object",
    "properties": {
      "executionId": {
        "type": "string",
        "description": "Generated workflow run ID",
        "example": "run-123"
      },
      "success": {
        "type": "boolean",
        "description": "Whether the execution was successful",
        "example": true
      },
      "channel": {
        "type": "string",
        "description": "Channel that will be used for message delivery (RCS, SMS, or MMS)",
        "example": "RCS"
      },
      "error": {
        "type": "string",
        "description": "Error message if execution failed",
        "example": "Invalid phone number"
      },
      "errorCode": {
        "type": "string",
        "description": "Error code if execution failed",
        "enum": [
          "INVALID_ARGUMENT",
          "RESOURCE_EXHAUSTED",
          "WORKFLOW_ALREADY_STARTED",
          "PAYLOAD_CONVERSION",
          "UNKNOWN",
          "WORKFLOW_NOT_FOUND",
          "SAVE_FAILED",
          "PREPARATION_FAILED",
          "USER_ENGAGED"
        ]
      },
      "details": {
        "type": "object",
        "description": "Error-specific diagnostic object. Keys and value types vary by failure; no fixed set of properties is guaranteed.",
        "additionalProperties": true,
        "example": {
          "workflowStatus": "DRAFT",
          "requiredStatus": "ACTIVE"
        }
      }
    },
    "required": [
      "success"
    ]
  }
}
```