Trigger workflows via API

To send emails from a workflow, trigger the workflow and enable the ‘Send email’ action.

There are two ways to trigger workflows via Waypoint’s API:

Option 1: Trigger using a workflow ID

Trigger the workflow directly by its ID. This is the default approach. The upside over a custom key (option 2) is immediate feedback — if you trigger with an ID that doesn’t exist, you’ll know right away that nothing ran.

POST /v1/workflow_runs

Property	Description
workflowId	The id of the workflow you want to send (created on the Waypoint dashboard). You can access the workflow ID from the URL. Eg. https://dashboard.usewaypoint.com/o/platform_xxx/workflows/wf_ABc123XYZ
variables	Optional – JSON data object that is passed to the template and available as variables on the template.
metaId	Optional – can be used for internal reference or idempotent requests. Eg. ‘order_1234’.

Code examples

const authHeader =
  'Basic ' + Buffer.from(`${API_KEY_USERNAME}:${API_KEY_PASSWORD}`).toString('base64');

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: authHeader,
  },
  body: JSON.stringify({
    workflowId: 'wf_eXYHR685DrjeGEXz',
    variables: {
      user: {
        displayName: 'Jordan',
        email: 'jordan@usewaypoint.com',
      },
      product: {
        title: 'Beechers Mac & Cheese',
        id: '02934203942',
      },
    },
  }),
};

fetch('https://live.waypointapi.com/v1/workflow_runs', options)
  .then((res) => res.json())
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

curl "https://live.waypointapi.com/v1/workflow_runs" \
  -H "Content-Type: application/json" \
  -u "API_KEY_USERNAME:API_KEY_PASSWORD"  \
  -d '{
  "workflowId": "wf_eXYHR685DrjeGEXz",
  "variables": {
    "user": {
      "displayName": "Jordan",
      "email": "jordan@usewaypoint.com"
    },
    "product": {
      "title": "Beechers Mac & Cheese",
      "id": "02934203942"
    }
  }
}'

Option 2: Trigger using a custom key

You can also trigger a workflow by a custom key. To add one, open the ‘Trigger’ section of the workflow builder and use the ‘Custom workflow key’ dropdown. Custom keys let your developers reference the workflow with a more descriptive name in code.

The other upside: the workflow doesn’t have to exist before you start sending data to it. That removes a common bottleneck — a developer can start triggering a new_listing workflow before anyone has built the actual workflow on the dashboard.

POST /v1/workflow_runs

Property	Description
workflowKey	Your custom workflow key (created on Waypoint’s workflow builder). Eg. ‘abandoned_cart’.
variables	Optional – JSON data object that is passed to the template and available as variables on the template.
metaId	Optional – can be used for internal reference or idempotent requests. Eg. ‘order_1234’.

Code examples

const authHeader =
  'Basic ' + Buffer.from(`${API_KEY_USERNAME}:${API_KEY_PASSWORD}`).toString('base64');

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: authHeader,
  },
  body: JSON.stringify({
    workflowKey: 'abandoned_cart',
    variables: {
      user: {
        displayName: 'Jordan',
        email: 'jordan@usewaypoint.com',
      },
      product: {
        title: 'Beechers Mac & Cheese',
        id: '02934203942',
      },
    },
  }),
};

fetch('https://live.waypointapi.com/v1/workflow_runs', options)
  .then((res) => res.json())
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

curl "https://live.waypointapi.com/v1/workflow_runs" \
  -H "Content-Type: application/json" \
  -u "API_KEY_USERNAME:API_KEY_PASSWORD"  \
  -d '{
  "workflowKey": "abandoned_cart",
  "variables": {
    "user": {
      "displayName": "Jordan",
      "email": "jordan@usewaypoint.com"
    },
    "product": {
      "title": "Beechers Mac & Cheese",
      "id": "02934203942"
    }
  }
}'