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.

Base URL

1
https://embedworkflow.com/api/v1

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.

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 id to receive a page of older objects immediately following the named object.

Set ending_before with an object's id 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-"

Idempotency header

1
--header 'Idempotency-Key: YOUR_KEY_HERE'

Expanding Resources

A response may contain a unique identifier of a related object. If the property is "expandable," then you can pass that field name to expand[] to receive the entire object. For example, a Workflow might have an associated event_trigger. Unexpanded, it will equal a string. But expanding it will return the entire object, including the id, event, etc.

Expand resource

1
  -d "expand[]"="event_trigger" \

Response

1
2
3
4
5
6
7
{
  "event_trigger": {
    "id": "abc123",
    "event": "form_submission",
    ...
  },
}

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.

Endpoints

POST/api/v1/workflows

GET/api/v1/workflow/:id

PUT/api/v1/workflows/:id

DELETE/api/v1/workflows/:id

GET/api/v1/workflows

POST/api/v1/workflows/:id/execute

POST/api/v1/workflows/:id/clone

The workflow object

Attribute	Description	Type
id	Unique identifier	string
key	Human-friendly user-scoped unique identifier	string
name	Human-friendly label	string
template_status	Draft or Published	string
created_at	Created local timestamp	datetime
created_at_utc	Created UTC timestamp	datetime
created_at_string	Created local time string	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
last_published_at	Last published local timestamp	datetime
last_published_at_utc	Last published UTC timestamp	datetime
last_published_at_string	Last published 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 action orchestration	hash
template_draft	Hash defining the action orchestration	hash
stats	Metrics for each action in the template	hash
event_trigger	The workflow's published trigger	string (expandable)
event_trigger_draft	The workflow's unpublished trigger	string (expandable)
stop_event	The workflow's published stop event	string
stop_event_draft	The workflow's unpublished stop event	string
trigger_conditions	Hash defining the published trigger conditions	hash
trigger_conditions_draft	Hash defining the unpublished trigger conditions	hash

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
  "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": [],
    "edges": [],
  },
  "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"
}

The workflow template object

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
  "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
      }
    }
  }
}

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

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.

Response

1
2
3
4
5
6
7
8
{
  "id": "ABC987",
  "name": "Wait 2 days",
  "type": "Delay",
  "delay_n": 2,
  "delay_unit": "day",
  "minute_of_day": 570,
}

Webhook attributes

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.

Response

1
2
3
4
5
6
7
8
{
  "id": "67890",
  "name": "Webhook Notification",
  "type": "Webhook",
  "url": "https://domain.com/webhook_example",
  "headers": "X-Custom-Header: my_value",
  "params": "one: 1\ntwo: 2"
}

Create a workflow

Create a new workflow.

Endpoint

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

Parameters

name string, required

Human-friendly string describing the workflow.

template object, 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 string, 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 boolean, optional, default: true

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 string, optional

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

stop_event string, optional

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

trigger_conditions object, optional

Hash defining the trigger conditions

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
  "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/:id

Parameters

id_type string, optional, default: 'id'

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

user_key string, optional. default: 'main'

This string is defaulted to 'main'.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
  "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/:id

Parameters

name string, optional

Human-friendly string describing the workflow.

key string, optional

Human-friendly unique string identifier scoped per user.

template object, optional

user_key string, optional, default: 'main'

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 boolean, optional, default: true

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 string, optional, default: 'draft'

A string either 'published' or 'draft'.

event_trigger string, optional

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

stop_event string, optional

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

trigger_conditions object, optional

Hash defining the trigger conditions.

Response

1
2
3
4
5
6
7
8
9
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
  "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/:id

Parameters

No parameters

Response

1
2
3
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12"
}

List all workflows

List your workflows.

Endpoint

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

Parameters

starting_after string, optional

A cursor for pagination. starting_after is an object id 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 string, optional

A cursor for pagination. ending_before is an object id 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "collection": [
    {
      "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
      "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/:id/execute

Parameters

id_type string, optional, default: 'id'

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

user_key string, optional, default: 'main'

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 object, optional, default: 'main'

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.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
  "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/:id/clone

Parameters

No parameters

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "id": "0194090d-3b19-78d3-9882-b1283a5f4e12",
  "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"
}

Triggers

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 string, optional

The event name you want to trigger

all_workflows string, optional, default: false

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

workflow_ids string, optional

A comma-separated string of workflow_id's. E.g. 0194090d-3b19-78d3-9882-b1283a5f4e12,2134090e-3b19-78d5-4812-b1283a5f4e44.

workflow_keys string, optional

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

user_key string, 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 object, optional

Response

1
{}

Executions

Executions are running workflows.

Endpoints

POST/api/v1/executions/stop

The execution object

Reference the workflow object.

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 string, required

The stop event name.

user_key string, optional, default: 'main'

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 object, optional

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

Response

1
{}

Users

Embed Workflow users are your workflow creators. Typically, they are your application's users. Users can be auto-discovered when you load the UI, so there is no need to create users ahead of time.

Endpoints

PUT/api/v1/users/:key

GET/api/v1/users/:key

DELETE/api/v1/users/:id

Attribute	Description	Type
key	Client created unique identifier
id	Auto-generated unique identifier	string
email	Optional 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
user_data_schema	User data schema with mapped values	array of objects (DataType)
created_at	Created at timestamp in configured timezone	datetime
created_at_utc	Created at timestamp in UTC	datetime
created_at_string	Created at timestamp in configured timezone as formatted string	string

The user object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "key": "main",
    "object": "user",
    "id": "019409cc-f708-77ce-a9a2-d82037f474fb",
    "name": "Embed Workflow",
    "created_at": "2024-12-27T20:26:55Z",
    "created_at_string": "Dec 27, 2024 08:26 pm UTC",
    "created_at_utc": "2024-12-27T20:26:55Z",
    "email": "no-reply+n1e70yi1awjnwhx732f9oqpf@embedworkflow.com",
    "groups": ["admin"],
    "config": {
        "primary_color": null,
        "logo_url": null,
        "user_data": {}
    },
    "user_data_schema": []
}

Upsert a user

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

Endpoint

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "key": "user-1",
    "object": "user",
    "id": "019409cc-f708-77ce-a9a2-d82037f474fb",
    "name": "Updated Name",
    "created_at": "2024-12-27T20:26:55Z",
    "created_at_string": "Dec 27, 2024 08:26 pm UTC",
    "created_at_utc": "2024-12-27T20:26:55Z",
    "email": "no-reply+n1e70yi1awjnwhx732f9oqpf@embedworkflow.com",
    "groups": ["admin"],
    "config": {
      "primary_color": null,
      "logo_url": null,
      "user_data": {
        "places": [
          { "label": "Place ABC", "value": 54321 },
          { "label": "Place DEF", "value": 12345 }
        ],
        "foo": "bar"
      }
    },
    "user_data_schema": []
}

Fetch a user

Use this endpoint to load a user.

Endpoint

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "key": "main",
    "object": "user",
    "id": "019409cc-f708-77ce-a9a2-d82037f474fb",
    "name": "Embed Workflow",
    "created_at": "2024-12-27T20:26:55Z",
    "created_at_string": "Dec 27, 2024 08:26 pm UTC",
    "created_at_utc": "2024-12-27T20:26:55Z",
    "email": "no-reply+n1e70yi1awjnwhx732f9oqpf@embedworkflow.com",
    "groups": ["admin"],
    "config": {
        "primary_color": null,
        "logo_url": null,
        "user_data": {}
    },
    "user_data_schema": []
}

Delete a user

Use this endpoint to delete a user.

Endpoint

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "key": "ARCHIVED__user-abc",
    "object": "user",
    "id": "019409cc-f708-77ce-a9a2-d82037f474fb",
    "name": "Embed Workflow",
    "created_at": "2024-12-27T20:26:55Z",
    "created_at_string": "Dec 27, 2024 08:26 pm UTC",
    "created_at_utc": "2024-12-27T20:26:55Z",
    "email": "no-reply+n1e70yi1awjnwhx732f9oqpf@embedworkflow.com",
    "groups": ["admin"],
    "config": {
        "primary_color": null,
        "logo_url": null,
        "user_data": {}
    },
    "user_data_schema": []
}