Skip to main content
The API trigger lets you start a workflow programmatically by making an API call. This is useful when you want to trigger workflows from your own application, backend systems, or third-party integrations.

​
Configuration

When you select the API trigger, Conversion generates a workflow ID that you pass to the Trigger Workflow API endpoint. The workflow ID is displayed in the trigger configuration and can be copied directly. To trigger the workflow, make a POST request to the endpoint with the workflow ID and a contact identifier: 
curl -X POST https://pub-api.conversion.ai/api/v2/workflows/{workflowId}/trigger \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "email": "jane@example.com"
  }'
The contact can be identified by email, cnvContactId, or userId — at least one is required. The workflow must be active and set to the API trigger type.

​
Passing custom data

You can include a data object in the request body to pass custom data into the workflow. This data is accessible in Liquid as trigger.api.data: 
curl -X POST https://pub-api.conversion.ai/api/v2/workflows/{workflowId}/trigger \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "email": "jane@example.com",
    "data": {
      "source": "backend",
      "action": "onboarding_complete",
      "plan": "pro"
    }
  }'
You can then reference this data in workflow nodes that support Liquid: 
{{ trigger.api.data.source }}
{{ trigger.api.data.plan }}
For the full list of available Liquid fields, see the Trigger Context Reference.

​
Re-enrollment

By default, contacts can only enter the workflow once. When you enable re-enrollment, contacts can enter the workflow each time the API is called, the same behavior as event-based triggers.

​
Exit conditions

Exit conditions define when a contact should leave the workflow early, regardless of where they are in the sequence. You configure exit conditions using the Unified Query Engine.