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.
- 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
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
andnodes
. The Node object contains the action's attributes including a uniqueid
. 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 ismain
, 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_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
- 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 ismain
.
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
- 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
andnodes
. The Node object contains the action's attributes including a uniqueid
. 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 ismain
, 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_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
- A cursor for pagination.
starting_after
is an objecthashid
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 objecthashid
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_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
- The id_type is either
key
orhashid
. The default value ishashid
.
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'sname
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'sname
value will be used.
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
- A cursor for pagination.
starting_after
is an objecthashid
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 objecthashid
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_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
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 isfalse
.
workflow_hashids optional
- A comma-separated
string
ofworkflow_hashid
's. E.g.123abc,456def
.
workflow_keys optional
- A comma-separated
string
ofworkflow_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'sname
value will be used.
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
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_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 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"
}