NAV
curl ruby javascript

API overview

Welcome to the EmbedWorkflow Developer API! This API will allow you to access our backend directly through our number of interfaces.

The Embed Workflow API is a REST API client. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Getting started

You can use the Embed Workflow API using HTTP or via one of our client libraries.

Do not see the client library you need? We are actively building more. Let us know which ones you'd benefit from using!

Authentication

The Embed Workflow API uses API keys to authenticate requests. You can view and manage your API keys in the Embed Workflow dashboard.

There are two types of keys per environment: publishable key (pkey) and secret key (skey).

To access the test environment, use the keys prefixed: pk_live and sk_live.

To access the production environment, use the keys prefixed: pk_live and sk_live.

Keys must be kept secure. The publishable key is intended to be used in client-side code. Do not expose your secret key on GitHub, client-side, and so forth.

Getting set up is easy. First, login into your account and find your API Tokens in your profile settings. It will grant you access to the API.

curl 'https://embedworkflow.com/api/v1/ENDPOINT' \
--header 'Authorization: Bearer sk_live_12345'
require 'embed_workflow'
EmbedWorkflow.skey = "sk_live_12345"

Response format

Responses are always JSON. This applies to all of our APIs.

Pagination

All of our list methods accept at least these two parameters: starting_after and ending_before. These endpoints all return chronologically reversed.

Set starting_after with an object's hashid to receive a page of older objects immediately following the named object.

Set ending_before with an object's hashid to receive a page of newer objects immediately before the named object.

Objects on a page always appear in reverse chronological order.

Only one of starting_after or ending_before may be used.

Idempotency

For all POST endpoints, you can pass an idempotency key as a header.

An example header:

--header 'Idempotency-Key: YOUR_KEY_HERE'

Workflows

Think of workflows as the template. The template decides how and when things should execute. Our Workflows API allows you to manage your workflow.

The workflow object

Attribute Description Type
hashid Unique identifier string
key Human-friendly user-scoped unique identifier string
name Human-friendly label string
template_status Draft or Published string
updated_at Last updated local timestamp datetime
updated_at_utc Last updated UTC timestamp datetime
updated_at_string Last updated local time string string
executions_count The number of times this workflow has been executed integer
actions_count The number of actions this workflow has integer
template Hash defining the order of actions hash
stats Metrics for each action in the template hash
event_trigger One of the account's pre-configured event triggers string
stop_event One of the account's pre-configured stop events string
trigger_conditions Hash defining the trigger conditions hash

Endpoints

The workflow template object

Attribute Description Type
edges Array of Edge's array
nodes Array of Node's. array

The edge string

An Edge describes a connection between two nodes. The Edge is represented as a string where two node IDs are joined by a -.

An Edge joining a Node with an ID of 123 and a Node with an ID of 456 would result in an Edge of 123-456.

The node object

Attribute Description Type
id Unique identifier string
name Human-friendly label describing the action string
type A valid node type string
... see below for additional node type attributes

Node types

Type Description
Delay Wait for a duration
Webhook Any outbound HTTP request

Additional node attributes by type

Delay attributes

{
  "id": "ABC987",
  "name": "Wait 2 days",
  "type": "Delay",
  "delay_n": 2,
  "delay_unit": "day",
  "minute_of_day": 570,
}
Attribute Description Type
delay_n Number value of the delay integer
delay_unit sec, min, hour, day, week, month, year string
minute_of_day Minute of day. e.g. 570 for 9:30 AM number

minute_of_day is only used for durations of day and longer. Also, the minute of the day will be set in the configured time zone.

Webhook attributes

{
  "id": "67890",
  "name": "Webhook Notification",
  "type": "Webhook",
  "url": "https://domain.com/webhook_example",
  "headers": "X-Custom-Header: my_value",
  "params": "one: 1\ntwo: 2"
}
Attribute Description Type
url Endpoint URL string
headers Request headers. E.g. "X-Custom-Header: my_value" string
params Request body. E.g. "one: 1\ntwo: 2" string

Each line in params and headers represent a key-value pair.

Create a workflow

Create a new workflow.

Endpoint

POST https://embedworkflow.com/api/v1/workflows

Parameters

name required

template optional

user_key optional

auto_start optional

event_trigger optional

stop_event optional

trigger_conditions optional

Request

let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_live_12345");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "name": "My First Workflow",
  "template": {
    "edges": ["a-b","a-c"],
    "nodes": [
      {"id":"a","name":"Wait 2 hours","type":"Delay","delay_n":2,"delay_unit":"hour"},
      {"id":"b","url":"https://domain.com/webhook_example_1","name":"Webhook 1","type":"Webhook","params":"one: 1\ntwo: 2","headers":"X-Custom-Header: my_value"},
      {"id":"c","url":"https://domain.com/webhook_example_2","name":"Webhook 2","type":"Webhook","params":"one: 1\ntwo: 2","headers":"X-Custom-Header: my_value"}
    ]
  }
});

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://embedworkflow.com/api/v1/workflows", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
curl 'https://embedworkflow.com/api/v1/workflows' \
--header 'Authorization: Bearer sk_live_12345' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "My First Workflow",
    "template": {
        "edges": ["a-b", "a-c"],
        "nodes": [
            {"id": "a", "name": "Wait 2 hours", "type": "Delay", "delay_n": 2, "delay_unit": "hour"},
            {"id": "b", "url": "https://domain.com/webhook_example_1", "name": "Webhook 1", "type": "Webhook", "params": "one: 1\ntwo: 2", "headers": "X-Custom-Header: my_value"},
            {"id": "c", "url": "https://domain.com/webhook_example_2", "name": "Webhook 2", "type": "Webhook", "params": "one: 1\ntwo: 2", "headers": "X-Custom-Header: my_value"}
        ]
    }
}'
template = {
  "edges": ["a-b","a-c"],
  "nodes": [
    {
      "id": "a",
      "name": "Wait 2 hours",
      "type": "Delay",
      "delay_n": 2,
      "delay_unit": "hour"
    },
    {
      "id": "b",
      "url": "https://domain.com/webhook_example_1",
      "name": "Webhook 1",
      "type": "Webhook",
      "params": "one: 1\ntwo: 2",
      "headers": "X-Custom-Header: my_value"
    },
    {
      "id": "c",
      "url": "https://domain.com/webhook_example_2",
      "name": "Webhook 2",
      "type": "Webhook",
      "params": "one: 1\ntwo: 2",
      "headers": "X-Custom-Header: my_value"
    }
  ]
}
EmbedWorkflow::Workflows.create(name: "My first workflow", template: template)

Response

{
  "hashid": "xaq8n",
  "actions_count": 3,
  "auto_start": true,
  "event_trigger": null,
  "executions_count": 0,
  "key": "my_first_workflow",
  "name": "My First Workflow",
  "stats": {},
  "stop_event": null,
  "template": {
    "nodes": [
      {
        "id": "a",
        "name": "Wait 2 hours",
        "type": "Delay",
        "delay_n": 2,
        "delay_unit": "hour"
      },
      {
        "id": "b",
        "name": "Webhook 1",
        "type": "Webhook",
        "url": "https://domain.com/webhook_example_1",
        "headers": "X-Custom-Header: my_value",
        "params": "one: 1\ntwo: 2"
      },
      {
        "id": "c",
        "name": "Webhook 2",
        "type": "Webhook",
        "url": "https://domain.com/webhook_example_2",
        "headers": "X-Custom-Header: my_value",
        "params": "one: 1\ntwo: 2"
      },
      {
        "id": "start_of_workflow",
        "name": "Start Workflow",
        "type": "Start"
      }
    ],
    "edges": [
      "a-b",
      "a-c",
      "start_of_workflow-a"
    ],
    "width": 1500,
    "height": 1200,
    "positions": {
      "start_of_workflow": {
        "x": 450,
        "y": 0
      },
      "a": {
        "x": 450,
        "y": 300
      },
      "b": {
        "x": 200,
        "y": 600
      },
      "c": {
        "x": 700,
        "y": 600
      }
    }
  },
  "template_status": "draft",
  "trigger_conditions": {},
  "updated_at": "2023-12-29T18:08:10Z",
  "updated_at_string": "Dec 29, 2023 06:08 pm UTC",
  "updated_at_utc": "2023-12-29T18:08:10Z"
}

Fetch a workflow

Fetch a specific workflow.

Endpoint

GET https://embedworkflow.com/api/v1/workflows/:hashid

Parameters

id_type optional

user_key optional

Request

let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_live_12345");

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://embedworkflow.com/api/v1/workflows/xaq8n", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
curl -G 'https://embedworkflow.com/api/v1/workflows/xaq8n' \
--header 'Authorization: Bearer sk_live_12345'
EmbedWorkflow::Workflows.fetch(hashid: "xaq8n")

Response

{
  "hashid": "xaq8n",
  "actions_count": 3,
  "auto_start": true,
  "event_trigger": null,
  "executions_count": 0,
  "key": "my_first_workflow",
  "name": "My First Workflow",
  "stats": {},
  "stop_event": null,
  "template": {...},
  "template_status": "draft",
  "trigger_conditions": {},
  "updated_at": "2023-12-29T18:08:10Z",
  "updated_at_string": "Dec 29, 2023 06:08 pm UTC",
  "updated_at_utc": "2023-12-29T18:08:10Z"
}

Update a workflow

Update a workflow.

Endpoint

PUT https://embedworkflow.com/api/v1/workflows/:hashid

Parameters

name optional

key optional

template optional

user_key optional

auto_start optional

template_status optional

event_trigger optional

stop_event optional

trigger_conditions optional

Request

curl -X PUT 'https://embedworkflow.com/api/v1/workflows/nybra' \
--header 'Authorization: Bearer sk_live_12345' \
-d 'name=Updated Name'
EmbedWorkflow::Workflows.update(hashid: "nybra", name: "Updated Name")

Response

{
  "hashid": "nybra",
  "actions_count": 0,
  "auto_start": true,
  "executions_count": 0,
  "name": "Updated Name",
  "tenant_key": "default",
  "updated_at": "2022-08-21T19:09:59Z"
}

Delete a workflow

Delete a workflow.

Endpoint

DELETE https://embedworkflow.com/api/v1/workflows/:hashid

Parameters

No parameters

Request

curl -X DELETE 'https://embedworkflow.com/api/v1/workflows/7devk' \
--header 'Authorization: Bearer sk_live_12345'
EmbedWorkflow::Workflows.delete(hashid: "7devk")

Response

{
  "hashid": "7devk"
}

List all workflows

List your workflows.

Endpoint

GET https://embedworkflow.com/api/v1/workflows

Parameters

starting_after optional

ending_before optional

Request

curl -G 'https://embedworkflow.com/api/v1/workflows' \
--header 'Authorization: Bearer sk_live_12345'
EmbedWorkflow::Workflows.list
let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_live_12345");
myHeaders.append("Content-Type", "application/json");

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://embedworkflow.com/api/v1/workflows", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response

{
  "collection": [
    {
      "hashid": "794qx",
      "actions_count": 1,
      "auto_start": true,
      "event_trigger": "new_user",
      "executions_count": 2,
      "key": "new_user",
      "name": "New User",
      "stop_event": null,
      "template_status": "published",
      "trigger_conditions": {},
      "updated_at": "2024-02-03T18:53:31Z",
      "updated_at_string": "Feb 03, 2024 06:53 pm UTC",
      "updated_at_utc": "2024-02-03T18:53:31Z"
    },
  ],
  "meta": {
    "page_limit": 25,
    "has_next_page": false,
    "has_previous_page": false
  }
}

Execute a workflow

Execute a given workflow

Endpoint

POST https://embedworkflow.com/api/v1/workflows/:hashid/execute

Parameters

id_type optional

user_key optional

form_data optional

execution_data optional

Request

curl 'https://embedworkflow.com/api/v1/workflows/740mp/execute' \
--header 'Authorization: Bearer sk_live_12345' \
--header 'Content-Type: application/json' \
--data-raw '{ "execution_data": { "Email": "team@embedworkflow.com" } }'
EmbedWorkflow::Workflows.execute(
  key: "new_user",
  execution_data: {
    Name: "David",
    Email: "david@embedworkflow.com",
    Phone: "954-321-1234"
  }
)

Response

{
  "hashid": "n3v37",
  "actions_count": 1,
  "auto_start": true,
  "event_trigger": "new_user",
  "executions_count": 0,
  "key": "new_user",
  "name": "New User!",
  "stop_event": null,
  "template_status": "draft",
  "trigger_conditions": {},
  "updated_at": "2024-02-04T16:33:20Z",
  "updated_at_string": "Feb 04, 2024 04:33 pm UTC",
  "updated_at_utc": "2024-02-04T16:33:20Z"
}

Clone a workflow

Clone a given workflow

Endpoint

POST https://embedworkflow.com/api/v1/workflows/:hashid/clone

Parameters

No parameters

Request

curl 'https://embedworkflow.com/api/v1/workflows/nybra/clone' \
--header 'Authorization: Bearer sk_live_12345'
EmbedWorkflow::Workflows.clone(hashid: "xbydj")

Response

{
  "hashid": "xovzn",
  "actions_count": 1,
  "auto_start": true,
  "event_trigger": "new_user",
  "executions_count": 0,
  "key": "new_user_682",
  "name": "New User",
  "stop_event": null,
  "template_status": "draft",
  "trigger_conditions": {},
  "updated_at": "2024-02-04T16:50:29Z",
  "updated_at_string": "Feb 04, 2024 04:50 pm UTC",
  "updated_at_utc": "2024-02-04T16:50:29Z"
}

Fetch the workflow activities

List a workflow's activity timeline.

Endpoint

GET https://embedworkflow.com/api/v1/workflows/:hashid/activities

Parameters

starting_after optional

ending_before optional

Response

A collection of Activity objects

Request

curl -G 'https://embedworkflow.com/api/v1/workflows/xj44x/activities' \
--header 'Authorization: Bearer sk_live_12345'
EmbedWorkflow::Workflows.activities(hashid: "794qx")


Response

{
  "collection": [
    {
      "hashid": "n3av7",
      "activity_type": "created",
      "context": {
        "title": "Created workflow",
        "status": "paused",
        "description": "New User!"
      },
      "time": "2024-02-02T21:48:48Z"
    }
  ],
  "meta": {
    "page_limit": 25,
    "has_next_page": false,
    "has_previous_page": false
  }
}

Trigger

The trigger endpoint allows you to execute workflows by triggering an event, specific workflows, or all of them.

Endpoints

Endpoints

Trigger workflows

Trigger workflows to create executions.

Endpoint

POST https://embedworkflow.com/api/v1/trigger

Parameters

event optional

all_workflows optional

workflow_hashids optional

workflow_keys optional

user_key optional

execution_data optional

Request

curl 'https://embedworkflow.com/api/v1/trigger' \
--header 'Authorization: Bearer sk_live_12345' \
--header 'Content-Type: application/json' \
--data-raw '{ "event": "new_user", "user_key": "user-130", "execution_data": {"name": "David"} } '
EmbedWorkflow::Trigger.create(event: "new_user", user_key: "user-130", execution_data: { name: "David" })
let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_live_12345");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({"event":"new_user","user_key":"user-130","execution_data":{"name":"David"}});

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://embedworkflow.com/api/v1/trigger", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response

{}

Executions

Executions are running workflows.

The execution object

Reference the workflow object.

Endpoints

Endpoints

Stop

Stop executions. This is useful and dependent on your account settings stop_events. When an account has stop_events (i.e. new_lead, signed_up, is_inactive) defined then your end-user will have a drop down selector in their workflow start node. These endpoint allows you to halt executions for a given stop_event and user_key. You can optional filter further key/value pairs you expect in the execution.

Endpoint

POST https://embedworkflow.com/api/v1/executions/stop

Parameters

stop_event required

user_key optional

filters optional

Request

curl 'https://embedworkflow.com/api/v1/executions/stop' \
--header 'Authorization: Bearer sk_live_12345'
EmbedWorkflow::Executions.stop(event: "inactive", user_key: "user-128")

Response

{

}

Actions

Fetch the action activities

Endpoint

GET https://embedworkflow.com/api/v1/actions/:hashid/activities

Response

A collection of Activity objects

Request

curl -G 'https://embedworkflow.com/api/v1/workflows/xj44x/activities' \
--header 'Authorization: Bearer sk_live_12345' \
EmbedWorkflow::Actions.activities(hashid: "7l0al")

Response

{
  "collection": [
    {
      "hashid": "xrqyy",
      "activity_type": "completed",
      "context": {
        "title": "Completed action",
        "status": "completed",
        "action_type": "Email",
        "description": "Email"
      },
      "time": "2022-08-21T19:40:39Z"
    },
    {
      "hashid": "xoqpa",
      "activity_type": "started",
      "context": {
        "title": "Ran action",
        "status": "running",
        "action_type": "Email",
        "description": "Email"
      },
      "time": "2022-08-21T19:40:37Z"
    },
    {
      "hashid": "xjk4d",
      "activity_type": "created",
      "context": {
        "title": "Created action",
        "status": "idle",
        "action_type": "Email",
        "description": "Email"
      },
      "time": "2022-08-21T19:40:37Z"
    }
  ]
}

Activities

The activity object

Activity Object

{
  "hashid": "75qqe",
  "context": {
    "title": "Completed action",
    "status": "completed",
    "action_type": "Email",
    "description": "Welcome"
  },
  "time": "2021-10-21T00:57:38Z"
}
Attribute Description Type
hashid Unique identifier string
time Timestamp datetime
context Key-value attributes object

Endpoints

Users

The user object

{
  "key": "main",
  "email": "hello@embedworkflow.com",
  "name": "Embed Workflow"
}
Attribute Description Type
key Unique identifier string
email Email address string
name Display name string
config User configuration hash
config[primary_color] Branding primary color string
config[logo_url] Branding logo URL string
config[user_data] Custom user data used in workflows hash

Upsert a user

Create or update a user. Only the attributes provided will be updated.

Endpoint

PUT https://embedworkflow.com/api/v1/users/:key

Request

EmbedWorkflow::Users.upsert(key: "main", name: "Updated Name", email: "hello_again@embedworkflow.com")
curl -X PUT 'https://embedworkflow.com/api/v1/users/user-1' \
--header 'Authorization: Bearer sk_live_12345' \
-d 'name=David A' \
-d 'email=davamr+user-1@gmail.com'

Response

{
  "key": "main",
  "email": "hello_again@embedworkflow.com",
  "name": "Updated Name"
}

Fetch a user

Use this endpoint to load a user.

Endpoint

GET https://embedworkflow.com/api/v1/users/:key

Request

curl -G 'https://embedworkflow.com/api/v1/users/main' \
--header 'Authorization: Bearer sk_live_12345' \
EmbedWorkflow::Users.fetch(key: "main")

Response

{
  "key": "main",
  "email": "hello@embedworkflow.com",
  "name": "Embed Workflow"
}