Skip to main content

Action Flow API

The Action Flow API can be used to:

  • start (invoke) a new Action Flow
  • update the card variables for Action Flows that were invoked before
  • fetch details about existing Action Flow configurations.

A credential role of events is required to utilize the Action Flow API.

You can interact with the Action Flow API using Insomnia (follow the Insomnia instructions) or curl. When using curl, you'll need to set up your Authentication first.

Detailed specs and examples can be found in the Atomic API spec for the Action Flows endpoint.

Sending cards using the API​

Sending cards via the API is done by sending requests to the Action Flow API endpoint.

Request properties​

The following properties can be sent in an Action Flow start request:

  • target - this is the only required property. This target can be any combination of users, segments, tags and filters. You need to send one flow object for each target. The Customers guide describes how to create segments, tags and filters.
  • payload - this is optional and can contain variables, cardOptions, notificationDetail and metadata.

Variables contain variable names that are used in cards.

Note that any variables marked as "required" in the workbench must be included here in order for the Action Flow start request to be successful. Read more about required variables in the Card template tutorial.

cardOptions can be thought of as delivery options for the associated cards. An overview can be found in this section on card delivery options.

notificationDetail and metadata are arbitrary data passed through with push notifications and Atomic events respectively.

flowInvocationId is an optional field in the request but will always be present in the response. If none is provided in the request, a new, unique value will be provided in the response. It will be present in all analytics events associated with the created card, so it can be used to track the card’s life cycle.

Target streams are optional and can either be provided via the API call via targetStreamIds, or can be configured in the workbench using a custom Action Flow. If no target stream is defined, cards will be delivered to the default “All cards” stream only.

Invoke an Action Flow​

The start API for an Action Flow can be found in the workbench. Navigate to the card you want to send. Make sure it is published before trying to send it using the API. The Action Flow API only works for cards that are published.

Select the trigger tab. You can copy the API start trigger for sending this card. It contains the flowConfigId.

Example Action Flow requests​

Using the test endpoint​

As mentioned earlier, a credential role of events is required to use the test endpoint of the Action Flow API.

Triggering an Action Flow in test mode means only test users can be targeted and draft Action Flows are allowed to be sent.

# set Action Flow test API
TEST_API="https://${orgId}.customer-api.atomic.io/v1/${envId}/action-flow/${flowConfigId}/test"

# request payload
PAYLOAD =
{
  "flows": [
    {
      "payload": {
        "cardOptions": {
          # card delivery options, all are optional
          "priority": 2, # 1-10, controls the position of the card in the stream
          "expires": "...", # ISO8601 timestamp
          "expiresInterval": "PT30M",  # ISO8601 interval
          "embargo": "...",  # ISO8601 timestamp
          "targetStreamIds": ["BqWL1sT"]
        },
        "metadata": {
          # arbitrary data that will be passed through with resultant events
        },
        "notificationDetail": {
          # arbitrary data provided to the host app with push notification data
        },
        "variables": {
          # values used to personalise cards
          "age": "42"
        }
      },

      "target": {
        # Targets can be users, segments, tags or filters
        "type": "tag",
        "tag": "test",
        "linked": false # optional, creates linked cards if set
      }
    }
  ]
}

# send request to Atomic
curl -X POST "$TEST_API" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data "$PAYLOAD"

# response format
{
  "triggeredFlows": [
    {
      "flowInvocationId": "bade1bb1-b708-424d-bec0-7a3eed3948a1"
    }
  ]
}

Using the start endpoint​

As mentioned earlier, a credential role of events is required to use the start endpoint of the Action Flow API.

Triggering an Action Flow in using the start endpoint, means cards need to be in a published state to be sent and can target both test and live users.

# set Action Flow start API
START_API="https://${orgId}.customer-api.atomic.io/v1/${envId}/action-flow/${flowConfigId}/start"

# request payload
PAYLOAD =
{
  "flows": [
    {
      # optional, used to interact with the triggered flow/card instances
      # created by Atomic if not supplied
      "flowInvocationId": "...",

      "payload": {
        "cardOptions": {
          # card delivery options, all are optional
          "priority": 5, # 1-10, controls the position of the card in the stream
          "expires": "...", # ISO8601 timestamp
          "expiresInterval": "PT30M",  # ISO8601 interval
          "embargo": "...",  # ISO8601 timestamp
          "targetStreamIds": ["3MgBE0qK"]
        },
        "metadata": {
          # arbitrary data that will be passed through with resultant events
        },
        "notificationDetail": {
          # arbitrary data provided to the host app with push notification data
        },
        "variables": {
          # values used to personalise cards
          "name": "John Smith"
        }
      },

      "target": {
        # Targets can be users, segments, tags or filters
        "type": "user",
        "targetUserIds": ["userA", "userB"],
        "linked": true # optional, creates linked cards if set
      }
    }
  ]
}

# send request to Atomic
curl -X POST "$START_API" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data "$PAYLOAD"

# response format
{
  "triggeredFlows": [
    {
      "flowInvocationId": "ccb23280-79a7-4224-86d3-2ece85e3832a"
    }
  ]
}

Linked cards option when targeting specific users​

The above example shows direct user id targeting - this creates a single action flow instance with a card sent to each target user. A linked parameter set to true will remove the card from other people's feeds once it has been completed by one card recipient.

Bulk targeting​

Cards can also be created in bulk using segments, tags and filters - this creates a separate card instance per user associated with the segment, tag or filter.

Note: the linked option is not available for bulk-targeted cards.

Update variables for previously invoked Action Flows​

It is possible to update variables in cards that are already displayed in customers' streams. This can be achieved by passing the flowInvocationId in the POST request.

As mentioned before, a credential role of events is required to utilize the Action Flow API.

The example below shows how to change the value for the variable discount in cards that were already published.

# set Action Flow start API
START_API="https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/action-flow/$FLOW_ID/start"

PAYLOAD='{
    "flows": [
        {
            "target": {
                "type": "segment",
                "targetSegmentId": "wglJ8vBv"
            },
            "payload": {
                "variables": {
                    "discount": "20 %"
                }
            },
            "flowInvocationId": "ccb23280-79a7-4224-86d3-2ece85e3832a"
        }
    ]
}'

# send request to Atomic
curl -X POST "$START_API" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data "$PAYLOAD"

Response format:

{
    "triggeredFlows": [
        {
            "flowInvocationId": "ccb23280-79a7-4224-86d3-2ece85e3832a"
        }
    ]
}

Get Action Flow configuration​

Fetch a specific or latest version of an Action Flow configuration.

Request properties​

  • flowConfigId - the target ID of the Action Flow.
  • environmentId - the environment id.
  • flowConfigVersion - the version of the target Action Flow. This can be the version number or 'latest' for the most recent.

As mentioned before, a credential role of events is required to utilize the Action Flow API.

# send request to Atomic
curl -X GET "https://${orgId}.customer-api.atomic.io/v1/${environmentId}/action-flow/${flowConfigId}/config/${flowConfigVersion}" \
    --header "Authorization: Bearer $TOKEN"

Responses​

The full Action Flow config for the requested version

Sample Response
{
  "data": {
    "status": "PUBLISHED",
    "config": {
      "type": "card",
      "steps": {
        "create-card": {
          "id": "create-card",
          "next": [],
          "type": "create-card",
          "properties": {
            "output": {
              "type": "default"
            },
            "cardTemplateId": "3"
          }
        }
      },
      "version": "2",
      "variables": {
        "age": {
          "type": "number",
          "source": "event",
          "default": 42
        },
        "name": {
          "type": "string",
          "source": "static",
          "default": "John Smith"
        },
        "birthday": {
          "type": "date",
          "source": "event",
          "default": "1980-01-01T08:00",
          "defaultFormatter": "date",
          "defaultFormatterOption": "dd/MM/Y h:mma"
        }
      },
      "initialSteps": [
        "create-card"
      ],
      "cardTemplates": {
        "3": {
          "metadata": {
            "cardName": "Published card",
            "delivery": {
              "priority": 5
            },
            "cardDescription": "Test card"
          },
          "subviews": {},
          "variables": {
            "age": {
              "type": "number",
              "source": "event",
              "default": 42
            },
            "name": {
              "type": "string",
              "source": "static",
              "default": "John Smith"
            },
            "birthday": {
              "type": "date",
              "source": "event",
              "default": "1980-01-01T08:00",
              "defaultFormatter": "date",
              "defaultFormatterOption": "dd/MM/Y h:mma"
            }
          },
          "defaultView": {
            "actions": [
              {
                "key": "t3Mn4ltPGuA3la0bECKYC",
                "type": "submitButton",
                "attributes": {
                  "text": "Submit",
                  "values": {},
                  "responseDefinition": ""
                }
              }
            ],
            "content": [
              {
                "key": "E1g1Bzxvw8cf3OK9ojq0k",
                "type": "headline",
                "attributes": {
                  "text": "Hello %{name}"
                }
              },
              {
                "key": "TgUT6rqy54ERErqG5D8Fm",
                "type": "image",
                "attributes": {
                  "src": "%{assetv1:atomic.png}",
                  "label": "Test image",
                  "format": "inline",
                  "thumbnailSrc": "%{assetv1:atomic.png}"
                }
              },
              {
                "key": "TmJdg3jiViCRHNdeBrABC",
                "type": "text",
                "attributes": {
                  "text": "Your birthday is %{birthday} "
                }
              }
            ]
          },
          "notification": {
            "attributes": {
              "body": "A card has arrived for %{name}"
            }
          }
        }
      }
    },
    "created": "2023-02-21T02:17:32.216Z",
    "updated": "2023-02-21T02:17:32.216Z",
    "version": 1
  }
}

Error

  • 401: No permission to environment
  • 404: Flow version not found

Update Action Flow metadata​

Updates the name and/or description of an Action Flow.

Request properties​

  • flowConfigId - the target ID of the Action Flow.
  • environmentId - the environment id.

As mentioned before, a credential role of events is required to utilize the Action Flow API.

PAYLOAD='{"actionFlow": {"name": "My First Action Flow"}}'

# send request to Atomic
curl -X PUT "https://${orgId}.customer-api.atomic.io/v1/${environmentId}/action-flow/${flowConfigId}" \
    --data "$PAYLOAD"
    --header "Authorization: Bearer $TOKEN"

Responses​

On success, the updated Action Flow details are returned

Sample Response
{
  "data": {
    "id": "rkEdVXl5",
    "name": "My First Action Flow",
    "description": "Default action flow for card template 3",
    "status": "active",
    "created": "2023-02-21T02:17:32.216Z",
    "updated": "2023-02-23T23:02:39.487Z",
    "variables": {
      "age": {
        "type": "number",
        "source": "event",
        "default": 42
      },
      "name": {
        "type": "string",
        "source": "static",
        "default": "John Smith"
      },
      "birthday": {
        "type": "date",
        "source": "event",
        "default": "1980-01-01T08:00",
        "defaultFormatter": "date",
        "defaultFormatterOption": "dd/MM/Y h:mma"
      }
    },
    "invocationUrl": "http://localhost:6005/v1/4dkLrv/action-flow/rkEdVXl5/start"
  }
}

Publish new version of an Action Flow​

Publishes a new version of an Action Flow configuration.

Request properties​

  • flowConfigId - the target ID of the Action Flow.
  • environmentId - the environment id.

As mentioned before, a credential role of events is required to utilize the Action Flow API.


PAYLOAD='{
      "type": "card",
      "steps": {
        "create-card": {
          "id": "create-card",
          "next": [],
          "type": "create-card",
          "properties": {
            "output": {
              "type": "default"
            },
            "cardTemplateId": "3"
          }
        }
      },
      "version": "2",
      "variables": {
        "age": {
          "type": "number",
          "source": "event",
          "default": 42
        },
        "name": {
          "type": "string",
          "source": "static",
          "default": "John Smith"
        },
        "birthday": {
          "type": "date",
          "source": "event",
          "default": "1980-01-01T08:00",
          "defaultFormatter": "date",
          "defaultFormatterOption": "dd/MM/Y h:mma"
        }
      },
      "initialSteps": [
        "create-card"
      ],
      "cardTemplates": {
        "3": {
          "metadata": {
            "cardName": "Published card",
            "delivery": {
              "priority": 5
            },
            "cardDescription": "Test card"
          },
          "subviews": {},
          "variables": {
            "age": {
              "type": "number",
              "source": "event",
              "default": 42
            },
            "name": {
              "type": "string",
              "source": "static",
              "default": "John Smith"
            },
            "birthday": {
              "type": "date",
              "source": "event",
              "default": "1980-01-01T08:00",
              "defaultFormatter": "date",
              "defaultFormatterOption": "dd/MM/Y h:mma"
            }
          },
          "defaultView": {
            "actions": [
              {
                "key": "t3Mn4ltPGuA3la0bECKYC",
                "type": "submitButton",
                "attributes": {
                  "text": "Submit",
                  "values": {},
                  "responseDefinition": ""
                }
              }
            ],
            "content": [
              {
                "key": "E1g1Bzxvw8cf3OK9ojq0k",
                "type": "headline",
                "attributes": {
                  "text": "Hello %{name}"
                }
              },
              {
                "key": "TgUT6rqy54ERErqG5D8Fm",
                "type": "image",
                "attributes": {
                  "src": "%{assetv1:atomic.png}",
                  "label": "Test image",
                  "format": "inline",
                  "thumbnailSrc": "%{assetv1:atomic.png}"
                }
              },
              {
                "key": "TmJdg3jiViCRHNdeBrABC",
                "type": "text",
                "attributes": {
                  "text": "Your birthday is %{birthday} "
                }
              }
            ]
          },
          "notification": {
            "attributes": {
              "body": "A card has arrived for %{name}"
            }
          }
        }
      }
    }'

# send request to Atomic
curl -X POST "https://${orgId}.customer-api.atomic.io/v1/${environmentId}/action-flow/${flowConfigId}/config/publish" \
    --data '$PAYLOAD'
    --header "Authorization: Bearer $TOKEN"

Responses​

Success

On success, the response will contain the processed config object. Refer to the [Atomic API Spec](https://01.customer-api.atomic.io/spec.yaml for full details

Sample Response
{
  "data": {
    "status": "PUBLISHED",
    "config": {
      "type": "card",
      "steps": {
        "create-card": {
          "id": "create-card",
          "next": [],
          "type": "create-card",
          "properties": {
            "output": {
              "type": "default"
            },
            "cardTemplateId": "3"
          }
        }
      },
      "version": "2",
      "variables": {
        "age": {
          "type": "number",
          "source": "event",
          "default": 42
        },
        "name": {
          "type": "string",
          "source": "static",
          "default": "John Smith"
        },
        "birthday": {
          "type": "date",
          "source": "event",
          "default": "1980-01-01T08:00",
          "defaultFormatter": "date",
          "defaultFormatterOption": "dd/MM/Y h:mma"
        }
      },
      "initialSteps": [
        "create-card"
      ],
      "cardTemplates": {
        "3": {
          "metadata": {
            "cardName": "Published card",
            "delivery": {
              "priority": 5
            },
            "cardDescription": "Test card"
          },
          "subviews": {},
          "variables": {
            "age": {
              "type": "number",
              "source": "event",
              "default": 42
            },
            "name": {
              "type": "string",
              "source": "static",
              "default": "John Smith"
            },
            "birthday": {
              "type": "date",
              "source": "event",
              "default": "1980-01-01T08:00",
              "defaultFormatter": "date",
              "defaultFormatterOption": "dd/MM/Y h:mma"
            }
          },
          "defaultView": {
            "actions": [
              {
                "key": "t3Mn4ltPGuA3la0bECKYC",
                "type": "submitButton",
                "attributes": {
                  "text": "Submit",
                  "values": {},
                  "responseDefinition": ""
                }
              }
            ],
            "content": [
              {
                "key": "E1g1Bzxvw8cf3OK9ojq0k",
                "type": "headline",
                "attributes": {
                  "text": "Hello %{name}"
                }
              },
              {
                "key": "TgUT6rqy54ERErqG5D8Fm",
                "type": "image",
                "attributes": {
                  "src": "%{assetv1:atomic.png}",
                  "label": "Test image",
                  "format": "inline",
                  "thumbnailSrc": "%{assetv1:atomic.png}"
                }
              },
              {
                "key": "TmJdg3jiViCRHNdeBrABC",
                "type": "text",
                "attributes": {
                  "text": "Your birthday is %{birthday} "
                }
              }
            ]
          },
          "notification": {
            "attributes": {
              "body": "A card has arrived for %{name}"
            }
          }
        }
      }
    },
    "created": "2023-02-21T02:17:32.216Z",
    "updated": "2023-02-21T02:17:32.216Z",
    "version": 2
  }
}

Error

There are several types of validation errors that can be returned.

  • 400: Validation error with config payload
  • 401: No permission to environment
  • 403: No permission to publish because approvals are enabled for environment
  • 409: Current draft exists for action flow

List Action Flows​

List all Actions Flow for environment

Request properties​

  • flowConfigId - the target ID of the Action Flow.
  • environmentId - the environment id.

Query Parameter​

  • name: filter Action Flows containing supplied name
  • status: (active|inactive) filter Action Flows by supplied status

If both parameters supplied the both parameters will be applied, ie. name && status.

As mentioned before, a credential role of events is required to utilize the Action Flow API.

# send request to Atomic
curl -X GET "https://${orgId}.customer-api.atomic.io/v1/${environmentId}/action-flow/${flowConfigId}?name=My%0First" \
    --header "Authorization: Bearer $TOKEN"

Response​

A list of action flows for the environment are returned.

Sample Response
{
  "data": [
    {
      "id": "rkEdVXl5",
      "name": "My First Action Flow",
      "description": "Default action flow for card template 3",
      "status": "active",
      "created": "2023-02-21T02:17:32.216Z",
      "updated": "2023-02-23T23:02:39.487Z",
      "variables": {
        "age": {
          "type": "number",
          "source": "event",
          "default": 42
        },
        "name": {
          "type": "string",
          "source": "static",
          "default": "John Smith"
        },
        "birthday": {
          "type": "date",
          "source": "event",
          "default": "1980-01-01T08:00",
          "defaultFormatter": "date",
          "defaultFormatterOption": "dd/MM/Y h:mma"
        }
      },
      "invocationUrl": "http://localhost:6005/v1/4dkLrv/action-flow/rkEdVXl5/start"
    }
  ]
}

Errors

  • 401: No permission to environment
Last updated on