--- title: "Create a Workflow Run" method: POST path: "/workflows/{workflow-id}/trigger" tags: ["workflows"] --- # Create a Workflow Run `POST /workflows/{workflow-id}/trigger` ## Request - Base URL: `https://api.withpersona.com/api/v1` - URL: `https://api.withpersona.com/api/v1/workflows/{workflow-id}/trigger` - Auth: HTTP bearer Creates a new Workflow Run. Note: The payload is arbitrary and defined by the Workflow version trigger schema. ## Path parameters - `workflow-id` string, required ## Query parameters - `include` string - `fields` object ## Headers - `Key-Inflection` 'camel' | 'kebab' | 'snake' - `Idempotency-Key` string - `Persona-Version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning). ## Request body - object - `data` WorkflowsWorkflowIdTriggerPostRequestBodyContentApplicationJsonSchemaData, required - `attributes` object, required: JSON key-value pairs of field name to field value. Schema is defined by the trigger payload schema on your Workflow Version. - `meta` WorkflowsWorkflowIdTriggerPostRequestBodyContentApplicationJsonSchemaMeta - `params` object: JSON key-value pairs of field name to field value. Schema is defined by the trigger payload schema on your Workflow Version. ## Response `200` This endpoint returns a Workflow object. - WorkflowsCreateAWorkflowRunResponse200 - `data` WorkflowRun, required: A Workflow Run object - `id` string - `attributes` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunAttributes - `completed-at` string, date-time, nullable - `created-at` string, date-time - `status` string - `relationships` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationships - `creator` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsCreator - `data` union - InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsCreatorData0 - `type` 'administrator' - `id` string - InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsCreatorData1 - `type` 'user' - `id` string - InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsCreatorData2 - `type` 'event' - `id` string - InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsCreatorData3 - `type` 'scheduled-run' - `id` string - `workflow` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsWorkflow - `data` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsWorkflowData - `type` 'workflow' - `id` string - `workflow-version` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsWorkflowVersion - `data` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunRelationshipsWorkflowVersionData - `type` 'workflow-version' - `id` string - `meta` InquiryIncludedObjectsItemsDiscriminatorMappingWorkflowRunMeta - `processing-time-seconds` number, double, nullable - `included` WorkflowRunIncludedObjectsItems[] - union - object: A Workflow object - `type` 'workflow', required: Discriminator value: workflow - `id` string - `attributes` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowAttributes - `status` string: The status of the Workflow Possible values: - paused - running - archived Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `name` string - `created-at` string, date-time - `relationships` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowRelationships - `latest-published-version` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowRelationshipsLatestPublishedVersion: latest published version - `data` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowRelationshipsLatestPublishedVersionData - … - `active-deployment` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowRelationshipsActiveDeployment: latest active deployment - `data` WorkflowDeployment: A Workflow Deployment object - … - object: A Workflow Version object - `type` 'workflow-version', required: Discriminator value: workflow-version - `id` string - `attributes` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowVersionAttributes - `workflow-name` string, nullable: The name of the Workflow this version belongs to. - `description` string, nullable: A description of the changes in this version. Draft versions have no description until one is set. - `status` string: The status of the Workflow Version Possible values: - draft - published - archived Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `trigger-type` string, nullable: What starts a run of this version. Null until a trigger is attached. Possible values: - trigger-account - trigger-api - trigger-case - trigger-direct - trigger-event - trigger-recurring - trigger-schedule - trigger-verification Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `live` boolean: Whether this version is running in the environment of the requesting API key or delivering webhook. While a Workflow is being rolled out, two versions are live at once; both report true. Always false while the Workflow itself is paused or archived. - `rollout-label` string, nullable: Which side of a rollout this version serves. Null when the version is not live — including while the Workflow is paused or archived — and for organizations whose deployments do not model a per-version traffic share. Possible values: - treatment - control Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `rollout-percentage` integer, nullable: The share of traffic this version receives in the environment of the requesting API key or delivering webhook. Null when the version is not live — including while the Workflow is paused or archived — and for organizations whose deployments do not model a per-version traffic share. - `last-updater` string, nullable: The email address of the User who last updated this version. Null when the version was last updated by Persona rather than by a member of your organization. - `inputs` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowVersionAttributesInputsItems[]: The values a run of this version accepts when it is started. - `name` string - `type` string, nullable: The JSON type accepted for this input. - `required` boolean - `outputs` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowVersionAttributesOutputsItems[]: The values a completed run of this version returns. - `name` string, nullable - `created-at` string, date-time - `updated-at` string, date-time: When this version was last edited. Does not cover edits to `inputs` or `outputs`; poll those values directly rather than this timestamp to detect input-contract changes. - `published-at` string, date-time, nullable - `relationships` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowVersionRelationships - `workflow` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowVersionRelationshipsWorkflow - `data` WorkflowRunIncludedObjectsItemsDiscriminatorMappingWorkflowVersionRelationshipsWorkflowData - … - object: An Event object - `type` 'event', required: Discriminator value: event - `id` string - `attributes` WorkflowRunIncludedObjectsItemsDiscriminatorMappingEventAttributes - `name` string - `payload` WorkflowRunIncludedObjectsItemsDiscriminatorMappingEventAttributesPayload: For a Persona-defined event, the entire serialized entity that triggered it. For a custom event, the arbitrary body you supplied when creating it, returned exactly as sent -- its keys are never re-cased. - `data` WorkflowRunIncludedObjectsItemsDiscriminatorMappingEventAttributesPayloadData - … - `created-at` string, date-time - `context` object: Additional context populated for some event types. For a custom event, the context you supplied when creating it, or empty if you supplied none. - object: A User object - `type` 'user', required: Discriminator value: user - `id` string - `attributes` WorkflowRunIncludedObjectsItemsDiscriminatorMappingUserAttributes - `email-address` string - `name-first` string - `name-last` string - object: A Scheduled Run object - `type` 'scheduled-run', required: Discriminator value: scheduled-run - `id` string - `attributes` WorkflowRunIncludedObjectsItemsDiscriminatorMappingScheduledRunAttributes - `status` string - `scheduled-at` string, date-time - `started-at` string, date-time, nullable - `finished-at` string, date-time, nullable - `errored-at` string, date-time, nullable - `canceled-at` string, date-time, nullable ## Other responses - `400`: The request was unacceptable, often due to invalid parameters. - `401`: An invalid API key was provided. - `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded. - `404`: The requested resource doesn’t exist. - `409`: The request conflicts with another request, often due to attempting to create a duplicate resource. - `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter. - `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests. --- [API](https://skmtc.dev/withpersona/apis/withpersona-2.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-2/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-2/revisions/f1c78133b3b2?raw)