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_test and sk_test.

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_test_12345'

require 'embed_workflow'
EmbedWorkflow.skey = "sk_test_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.

keys are only valid for 24 hours
keys are scoped for a specific path
you can prevent expiration of a key if you prepend the key with "life-"

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

POST

/api/v1/workflows

GET

/api/v1/workflow/:hashid

PUT

/api/v1/workflows/:hashid

GET

/api/v1/workflows

POST

/api/v1/workflows/:hashid/execute

POST

/api/v1/workflows/:hashid/clone

POST

/api/v1/workflows/:hashid/run

GET

/api/v1/workflows/:hashid/activities

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

Human-friendly string describing the workflow.

template optional

A workflow template object is a structured hash of the following key-value pairs: edges and nodes. The Node object contains the action's attributes including a unique id. An Edge string is a string of two action ID's joined by a string (1-2, actionA-actionB)

user_key optional

The user_key string determines which user this workflow should be scoped to and what data should be used. The default value is main, however, that is the admin user.

auto_start optional

Workflow by default the boolean will be true. You can disable this behavior so form submissions do not kick off the execution actions and wait for a manual start.

event_trigger optional

A string of one of the account's pre-configured event triggers.

stop_event optional

A string of one of the account's pre-configured stop events.

trigger_conditions optional

Hash defining the trigger conditions

Request

let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_test_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_test_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

This string is defaulted to "hashid". Alternatively, you can you set it's value to "key" and use the workflow's key (e.g. my_first_workflow).

user_key optional

The user_key string determines which user should be scoped. The default value is main.

Request

let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_test_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_test_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

Human-friendly string describing the workflow.

key optional

Human-friendly unique string identifier scoped per user.

template optional

A workflow template object is a structured hash of the following key-value pairs: edges and nodes. The Node object contains the action's attributes including a unique id. An Edge string is a string of two action ID's joined by a string (1-2, actionA-actionB)

user_key optional

The user_key string determines which user this workflow should be scoped to and what data should be used. The default value is main, however, that is the admin user.

auto_start optional

Workflow by default the boolean will be true. You can disable this behavior so form submissions do not kick off the execution actions and wait for a manual start.

template_status optional

A string either "published" or "draft".

event_trigger optional

A string of one of the account's pre-configured event triggers.

stop_event optional

A string of one of the account's pre-configured stop events.

trigger_conditions optional

Hash defining the trigger conditions

Request

curl -X PUT 'https://embedworkflow.com/api/v1/workflows/nybra' \
--header 'Authorization: Bearer sk_test_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_test_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

A cursor for pagination. starting_after is an object hashid that defines your place in the list. For instance, if you make a list request and receive 25 objects, ending with 123abc, your subsequent call can include starting_after=123abc to fetch the next page of the list.

ending_before optional

A cursor for pagination. ending_before is an object hashid that defines your place in the list. For instance, if you make a list request and receive 25 objects, starting with 123abc, your subsequent call can include ending_before=123abc to fetch the previous page of the list.

Request

curl -G 'https://embedworkflow.com/api/v1/workflows' \
--header 'Authorization: Bearer sk_test_12345'

EmbedWorkflow::Workflows.list

let myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_test_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

The id_type is either key or hashid. The default value is hashid.

user_key optional

The user key you want to scope the workflows to. The default value is the user you authenticated as which is most likely the main user.

form_data optional

Set of key-value pairs that you can attach to an object. This can be useful for referencing your actions. First template data is applied, followed by execution data, and finally the form data. If all three define name, the form's name value will be used.

execution_data optional

Set of key-value pairs that you can attach to an object. This can be useful for referencing your actions. First template data is applied, followed by execution data, and finally the form data. If all three define name, the form's name value will be used.

Request

curl 'https://embedworkflow.com/api/v1/workflows/740mp/execute' \
--header 'Authorization: Bearer sk_test_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_test_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

A cursor for pagination. starting_after is an object hashid that defines your place in the list. For instance, if you make a list request and receive 25 objects, ending with 123abc, your subsequent call can include starting_after=123abc to fetch the next page of the list.

ending_before optional

A cursor for pagination. ending_before is an object hashid that defines your place in the list. For instance, if you make a list request and receive 25 objects, starting with 123abc, your subsequent call can include ending_before=123abc to fetch the previous page of the list.

Response

A collection of Activity objects

Request

curl -G 'https://embedworkflow.com/api/v1/workflows/xj44x/activities' \
--header 'Authorization: Bearer sk_test_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

POST

/api/v1/trigger

Trigger workflows

Trigger workflows to create executions.

Endpoint

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

Parameters

event optional

The event name you want to trigger.

all_workflows optional

Set to true (boolean) if you want to execute all of a given user's workflows. The default value is false .

workflow_hashids optional

A comma-separated string of workflow_hashid's. E.g. 123abc,456def.

workflow_keys optional

A comma-separated string of workflow_key's. E.g. onboarding,new_lead.

user_key optional

The user key you want to scope the workflows to. The default value is the user you authenticated as which is most likely the main user.

execution_data optional

Set of key-value pairs that you can attach to an object. This can be useful for referencing your actions. First template data is applied, followed by execution data, and finally the form data. If all three define name, the form's name value will be used.

Request

curl 'https://embedworkflow.com/api/v1/trigger' \
--header 'Authorization: Bearer sk_test_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_test_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

POST

/api/v1/executions/stop

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

The stop event name.

user_key optional

The user key you want to scope the workflows to. The default value is the user you authenticated as which is most likely the main user.

filters optional

Set of key-value pairs that must match in the execution.

Request

curl 'https://embedworkflow.com/api/v1/executions/stop' \
--header 'Authorization: Bearer sk_test_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_test_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

GET

/api/v1/actions/:hashid/activites

GET

/api/v1/workflows/:hashid/activites

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

PUT

/api/v1/users/:key

GET

/api/v1/users/:key

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_test_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_test_12345' \

EmbedWorkflow::Users.fetch(key: "main")

Response

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