Action Flow API

The Action Flow API can be used to:

start (invoke) a new Action Flow using the start endpoint, the test endpoint or the bulk start endpoint
update the card variables for Action Flows that were invoked before
fetch details about existing Action Flow configurations
update Action Flow metadata
publish a new version of an Action Flow
list Action Flows

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 /start, /test or csv-task endpoint.
The /start and /test endpoints accept requests that are either targeted to specific userid's (which allows the use of the linked cards feature) or are using the bulk targeting option.
The /csv-task endpoint enables you to target users in a csv file.

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, when supplied these override the default configuration of all cards in the Action Flow.
          "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"],
          "targetPlatforms": ["Web"] ## if override the card template options
        },
        "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
      }
    }
  ],
  "options": {
    "strictVariables": true # fail the request if it contains variables (in payload) that aren't present in the target Action Flow
  }
}

# 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, when supplied these override the default configuration of all cards in the Action Flow.
          "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"],
          "targetPlatforms": ["Android"]
        },
        "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"
    }
  ]
}

Request properties

Flows

The following properties can be sent in an Action Flow start or test request under the flows parameter:

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.

It is not possible to pass script variables as part of the request; if your card contains script variables, the default script you used in the template will be used when sending the card instance.

cardOptions can be thought of as delivery options for the associated cards. An overview can be found in this section on card delivery options. The request to trigger an Action Flow will fail and return an error if any of these options are invalid.

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. The request to trigger an Action Flow will fail and return an error if the target streams are invalid for the given environment.

Target platforms are optional and can either be provided via the API call via targetPlatforms, or can be configured in the workbench delivery options. If no platforms are defined, cards will be delivered to all platforms (Web, iOS & Android).

Options

The following properties can be sent in an Action Flow start request under the options parameter, the options parameter is optional:

strictVariables - When enabled the API request will fail if it contains variables not associated with the Action Flow.

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 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 Flows in an environment.

Request properties

environmentId - the environment id.

Query Parameter

name: filter Action Flows containing supplied name
status: (DRAFT | PUBLISHED | ARCHIVED) filter Action Flows by supplied status

If both parameters are supplied, both parameters will be applied.

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?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

Bulk Start Action Flow

You can start an Action Flow in which you target multiple users and provide input variables, by using a csv file. This can be done via the workbench, as explained in the Action Flow bulk send tool section.

Use the workbench to format your csv while testing

You can find a sample csv file in the tools section in the workbench. The workbench also lists what naming conventions to use in your header columns. You might need a few tries before you have perfected the csv file with all correct column headers, variable names, etc. It is easier to do this in the workbench, since it returns the job status in the UI.

You can also bulk start an Action Flow via a sequence of API requests:

Generate a URL to upload the csv by making a request to the "csv-task" endpoint. The return value provides an upload URL to upload the input data for the Action Flow. This upload URL is a type of presigned S3 upload URLs. The upload link is only valid for 5 minutes.
Send a POST request with the csv file to the presigned url.

Generate the upload URL

Request properties

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

To generate an upload URL, you need to take note of:

orgId - the id of your organisation
flowConfigId - the target ID of the Action Flow
environmentId - the id of the environment

You can generate an upload URL in Insomnia by using the "queue up Action Flow requests using CSV to provide input data" request, or by using curl. When using curl, you'll need to set up your Authentication first.

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

Responses

Success

On success, the response will contain the task information, including the task id and status url used to check on the task processing. Refer to the Atomic API Spec for full details.

Sample Response

  {"data": {
    "task": {
      "id": 123,
      "status": "pending"
    },
    "uploadUrl": "https://${bucketName}.s3.amazonaws.com/master/${atomicZone}/customer-csv-uploads/${environmentId}/${fileName}.csv",
    "statusUrl": "https://${orgId}.customer-api.atomic.io/v1/${environmentId}/action-flow/${flowConfigId}/csv-task/123/status"
  }
}

This response contains data that can be used to monitor the status of the upload, as described in the Bulk Start Action Flow Status section.

Error

400: Input validation
401: No permission to environment
404: Action Flow not found

Upload the csv file to the presigned URL

In this step, you upload your csv file to an Amazon S3 bucket. Because it is a presigned URL, you don't need to provide any of the authentication headers. It is however mandatory to provide the file type, otherwise you'll receive an error message.

A bash script in its simplest form could look something like

#!/bin/sh

CSV_FILE="insert/path/to/csv/file"
S3_LINK="https://insert_upload.url.com"

curl -X PUT -T $CSV_FILE -L --header “Content-type: text/csv” "$S3_LINK"

Bulk Start Action Flow Status

Related to the Bulk Start Action Flow endpoint above, the status endpoint is used to monitor the status of a task.

The output of the above endpoint provides a status URL. This is the URL to use when checking the Bulk Start Action Flow task.

Request properties

flowConfigId - the target ID of the Action Flow.
environmentId - the environment id.
taskId - the task id, from the initial call of the Bulk Start Action Flow call.

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

Success

The response will contain the task information, Refer to the Atomic API Spec for full details

Sample Response

If the job is still in pending state, the upload URL will be returned as well.

{
  "data": {
    "task": {
      "id": 123,
      "status": "completed"
    },
    "statusUrl": "https://${orgId}.customer-api.atomic.io/v1/${environmentId}/action-flow/${flowConfigId}/csv-task/123/status"
  }
}

Error

400: Input validation
401: No permission to environment
404: Action Flow not found

Action Flow API

Sending cards using the API​

Invoke an Action Flow​

Example Action Flow requests​

Using the test endpoint​

Using the start endpoint​

Request properties​

Flows​

Options​

Linked cards option when targeting specific users​

Bulk targeting​

Update variables for previously invoked Action Flows​

Get Action Flow configuration​

Request properties​

Responses​

Update Action Flow metadata​

Request properties​

Responses​

Publish new version of an Action Flow​

Request properties​

Responses​

List Action Flows​

Request properties​

Query Parameter​

Response​

Bulk Start Action Flow​

Generate the upload URL​

Request properties​

Responses​

Upload the csv file to the presigned URL​

Bulk Start Action Flow Status​

Request properties​

Sending cards using the API

Invoke an Action Flow

Example Action Flow requests

Using the test endpoint

Using the start endpoint

Request properties

Flows

Options

Linked cards option when targeting specific users

Bulk targeting

Update variables for previously invoked Action Flows

Get Action Flow configuration

Request properties

Responses

Update Action Flow metadata

Request properties

Responses

Publish new version of an Action Flow

Request properties

Responses

List Action Flows

Request properties

Query Parameter

Response

Bulk Start Action Flow

Generate the upload URL

Request properties

Responses

Upload the csv file to the presigned URL

Bulk Start Action Flow Status

Request properties