API Explorer
Flow Starts Endpoint

This endpoint allows you to list manual flow starts in your account, and add or start contacts in a flow.

Listing Flow Starts

By making a GET request you can list all the manual flow starts on your organization, in the order of last modified. Each flow start has the following attributes:

  • uuid - the UUID of this flow start (string)
  • flow - the flow which was started (object)
  • contacts - the list of contacts that were started in the flow (objects)
  • groups - the list of groups that were started in the flow (objects)
  • restart_participants - whether the contacts were restarted in this flow (boolean)
  • exclude_active - whether the active contacts in other flows were excluded in this flow start (boolean)
  • status - the status of this flow start
  • params - the dictionary of extra parameters passed to the flow start (object)
  • created_on - the datetime when this flow start was created (datetime)
  • modified_on - the datetime when this flow start was modified (datetime)

Example:

GET /api/v2/flow_starts.json

Response is the list of flow starts on your organization, most recently modified first:

{
    "next": "http://example.com/api/v2/flow_starts.json?cursor=cD0yMDE1LTExLTExKzExJTNBM40NjQlMkIwMCUzRv",
    "previous": null,
    "results": [
        {
            "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
            "flow": {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Thrift Shop"},
            "groups": [
                 {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Ryan & Macklemore"}
            ],
            "contacts": [
                 {"uuid": "f5901b62-ba76-4003-9c62-fjjajdsi15553", "name": "Wanz"}
            ],
            "restart_participants": true,
            "exclude_active": false,
            "status": "complete",
            "params": {
                "first_name": "Ryan",
                "last_name": "Lewis"
            },
            "created_on": "2013-08-19T19:11:21.082Z",
            "modified_on": "2013-08-19T19:11:21.082Z"
        },
        ...
    ]
}

Starting contacts down a flow

By making a POST request with the contacts, groups and URNs you want to start down a flow you can trigger a flow start. Note that that contacts will be added to the flow asynchronously, you can use the runs endpoint to monitor the runs created by this start.

  • flow - the UUID of the flow to start contacts in (required)
  • groups - the UUIDs of the groups you want to start in this flow (array of up to 100 strings, optional)
  • contacts - the UUIDs of the contacts you want to start in this flow (array of up to 100 strings, optional)
  • urns - the URNs you want to start in this flow (array of up to 100 strings, optional)
  • restart_participants - whether to restart participants already in this flow (optional, defaults to true)
  • exclude_active - whether to exclude contacts currently in other flow (optional, defaults to false)
  • params - a dictionary of extra parameters to pass to the flow start (accessible via @trigger.params in your flow)

Example:

POST /api/v2/flow_starts.json
{
    "flow": "f5901b62-ba76-4003-9c62-72fdacc1b7b7",
    "groups": ["f5901b62-ba76-4003-9c62-72fdacc15515"],
    "contacts": ["f5901b62-ba76-4003-9c62-fjjajdsi15553"],
    "urns": ["twitter:sirmixalot", "tel:+12065551212"],
    "params": {"first_name": "Ryan", "last_name": "Lewis"}
}

Response is the created flow start:

{
    "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
    "flow": {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Thrift Shop"},
    "groups": [
         {"uuid": "c24813d2-3bc7-4467-8916-255b6525c6be", "name": "Ryan & Macklemore"}
    ],
    "contacts": [
         {"uuid": "f1ea776e-c923-4c1a-b3a3-0c466932b2cc", "name": "Wanz"}
    ],
    "restart_participants": true,
    "status": "complete",
    "params": {
        "first_name": "Ryan",
        "last_name": "Lewis"
    },
    "created_on": "2013-08-19T19:11:21.082Z",
    "modified_on": "2013-08-19T19:11:21.082Z"
}