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
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 |
name | Human-friendly label | string |
updated_at | Last updated timestamp | datetime |
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 |
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 |
Send an email | |
Text | Send a text message via your integration SMS service |
Webhook | Any outbound HTTP request |
Slack | Slack notification |
OpenAi | OpenAI V1 Completions API |
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.
Email attributes
{
"id": "12345",
"name": "Notification Email",
"type": "Email",
"subject": "New Submission",
"body": "New submission from {{Name}} - {{Email}} - {{Phone}}.",
"recipient": "{{Account Email}}"
}
Attribute | Description | Type |
---|---|---|
subject | Email's subject line | string |
recipient | Recipient's email address | string |
body | Email's message body | string |
subject, recipient, and body all accept dynamic placeholders. You may want to set the recipient to "{{Email}}"
or the subject to "Welcome {{Name}}!"
.
Text attributes
{
"id": "54321",
"name": "Welcome Text",
"type": "Text",
"subject": "New Submission",
"message": "Hi {{Name}}",
"recipient": "+1-954-555-5555"
}
Attribute | Description | Type |
---|---|---|
message | Text message body | string |
recipient | Recipient's phone number | string |
phone_number is auto-formatted to E.164 and limited to only US phone numbers. We will be expanding this soon. Reach out if you need text support outside of the US!
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.
Slack attributes
{
"id": "09876",
"name": "Slack Notification",
"type": "Slack",
"url": "https://hooks.slack.com/services/ABC123/ZYX12345/Az19abcdef123456AzBy0987654321",
"message": "**New submission** from {{Name}} - {{Email}} - {{Phone}}."
}
Attribute | Description | Type |
---|---|---|
url | Webhook URL | string |
message | string |
Message can be include Slack formatting.
OpenAi attributes
{
"id": "31131",
"name": "Blog Post Request",
"type": "OpenAi",
"message": "Please write me a blog about {{topic}}: \nIn-Depth Guide with Tools, Strategies and Examples.",
"outcome_field": "sample_content"
Attribute | Description | Type |
---|---|---|
outcome_field | Field you want to store the result | string |
message | Content sent to OpenAI | string |
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
)
tenant_key optional
- The tenant key determines which settings this workflow should use. For instance: colors for emails, integration setup, and recipient names. The default value is
default
.
auto_start optional
- Workflow by default will
auto_start
. You can disable this behavior so form submissions do not kick off the workflow actions and wait for a manual start.
Request
curl 'https://embedworkflow.com/api/v1/workflows' \
--header 'Authorization: Bearer sk_test_12345' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "My First Workflow",
"auto_start": true,
"tenant_key": "default",
"template": {
"edges": ["a-b", "a-c"],
"nodes": [
{"id": "a", "name": "Wait 2 hours", "type": "Delay", "delay_n": 2, "delay_unit": "hour"},
{"id": "b", "name": "Email", "type": "Email", "recipient": "john@doe.com", "subject": "New Submission", "body": "New submission from {{Name}} - {{Email}} - {{Phone}}."},
{"id": "c", "url": "https://domain.com/webhook_example", "name": "Webhook", "type": "Webhook", "params": "one: 1\ntwo: 2", "headers": "X-Custom-Header: my_value"}
]
}
}'
template = {
"edges": ["1-2", "1-3", "4-5"],
"nodes": [
{"id": "1", "name": "Wait 5 hours", "type": "Delay", "delay_n": 5, "delay_unit": "hour"},
{"id": "2", "name": "Wait 2 secs", "type": "Delay", "delay_n": 2, "delay_unit": "sec"},
{"id": "3", "url": "https://yourdomain.com/incoming-webhook", "name": "daf", "type": "Webhook", "params": "one:1\ntwo:2", "headers": "X-Custom-Header: my_value"},
{"id": "4", "name": "Say Hi", "type": "Text", "message": "Hey {{Name}}!", "recipient": "+1954-555-5555"},
{"id": "5", "url": "https://hooks.slack.com/services/ABC123/ZYX12345/Az19abcdef123456AzBy0987654321", "name": "Slack Notification", "type": "Slack", "message": "New submission from {{Name}} - {{Email}} - {{Phone}}."}
]
}
EmbedWorkflow::Workflows.create(name: "My first workflow", template: template, auto_start: true, tenant_key: "default")
Response
{
"hashid": "xrvry",
"actions_count": 3,
"auto_start": true,
"executions_count": 0,
"name": "My First Workflow",
"stats": {},
"template": {
"nodes": [
{
"id": "a",
"name": "Wait 2 hours",
"type": "Delay",
"delay_n": 2,
"delay_unit": "hour"
},
{
"id": "b",
"name": "Email",
"type": "Email",
"subject": "New Submission",
"body": "New submission from {{Name}} - {{Email}} - {{Phone}}.",
"recipient": "john@doe.com"
},
{
"id": "c",
"name": "Webhook",
"type": "Webhook",
"url": "https://domain.com/webhook_example",
"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
}
}
},
"tenant_key": "default",
"updated_at": "2022-10-16T16:14:43Z"
}
Fetch a workflow
Fetch a specific workflow.
Endpoint
GET https://embedworkflow.com/api/v1/workflows/:hashid
Parameters
No parameters
Request
curl -G 'https://embedworkflow.com/api/v1/workflows/740mp' \
--header 'Authorization: Bearer sk_test_12345'
EmbedWorkflow::Workflows.fetch(hashid: "nybra")
Response
{
"hashid": "nybra",
"actions_count": 0,
"auto_start": true,
"executions_count": 0,
"name": "My first workflow",
"stats": {},
"template": {
"nodes": [
{
"id": "start_of_workflow",
"element_type": "start_of_workflow",
"data": {},
"position": {
"x": 450,
"y": 0
}
}
],
"edges": [],
"width": 1500,
"height": 600
},
"tenant_key": "default",
"updated_at": "2022-08-21T18:20:51Z"
}
Update a workflow
Update a workflow.
Endpoint
PUT https://embedworkflow.com/api/v1/workflows/:hashid
Parameters
name required
- Human-friendly
string
describing the workflow.
template optional
- A structured
hash
of the following key-value pairs:edges
andnodes
. ANode
contains the action's attributes including a uniqueid
. Anedge
is a string of two action ID's joined by a string (1-2
,actionA-actionB
)
tenant_key optional
- The tenant key determines which settings this workflow should use. For instance: colors for emails, integration setup, and recipient names. The default value is
default
.
auto_start optional
- Workflow by default will
auto_start
. You can disable this behavior so form submissions do not kick off the workflow actions and wait for a manual start.
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 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_test_12345'
EmbedWorkflow::Workflows.list
Response
{
"collection": [
{
"hashid": "nybra",
"actions_count": 0,
"auto_start": true,
"executions_count": 0,
"name": "My first workflow",
"tenant_key": "default",
"updated_at": "2022-08-21T18:20:51Z"
},
],
"meta": {
"page_limit": 25,
"has_next_page": true,
"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_test_12345' \
--header 'Content-Type: application/json' \
--data-raw '{ "execution_data": { "Email": "team@embedworkflow.com" }, "form_data": { "Email": "david@embedworkflow.com" } }'
EmbedWorkflow::Workflows.execute(
hashid: "79zeo",
execution: {"Account Email": "mail@embedworkflow.com" },
form: {
Name: "David",
Email: "david@embedworkflow.com",
Phone: "954-321-1234"
}
)
Response
{
"hashid": "xbydj",
"actions_count": 0,
"auto_start": true,
"executions_count": 0,
"name": "Updated Name",
"tenant_key": "default",
"updated_at": "2022-08-21T19:14:13Z"
}
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": "79zeo",
"actions_count": 0,
"auto_start": true,
"executions_count": 0,
"name": "Name",
"tenant_key": "default",
"updated_at": "2022-08-21T19:20:24Z"
}
Run a workflow
Run a given workflow
Endpoint
POST https://embedworkflow.com/api/v1/workflows/:hashid/run
Parameters
No parameters
Request
curl 'https://embedworkflow.com/api/v1/workflows/79zjd/run' \
--header 'Authorization: Bearer sk_test_12345'
workflow = EmbedWorkflow::Workflows.create(name: "Manual Start Workflow", auto_start: false)
EmbedWorkflow::Workflows.run(hashid: workflow["hashid"])
Response
{
"hashid": "75qeb",
"actions_count": 0,
"auto_start": false,
"executions_count": 0,
"name": "Manual Start Workflow",
"tenant_key": "default",
"updated_at": "2022-08-21T19:25:36Z"
}
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_test_12345'
EmbedWorkflow::Workflows.activities(hashid: "nybra")
Response
{
"collection": [
{
"hashid": "nyjg5",
"activity_type": "created",
"context": {
"title": "Created workflow",
"status": "paused",
"description": "My first workflow"
},
"time": "2022-08-21T18:20:51Z"
}
]
}
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.
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/trigger' \
--header 'Authorization: Bearer sk_test_12345'
EmbedWorkflow::Trigger.create(event: "Manual Start Workflow", user_key: "user-128")
Response
{
}
Fields
The field object
{
"hashid": "nybra",
"actions_count": 2,
"auto_start": true,
"executions_count": 10,
"name": "Updated workflow name",
"stats": {},
"template": {},
"tenant_key": "default",
"updated_at": "2021-10-21T00:36:21Z"
}
Attribute | Description | Type |
---|---|---|
id | Unique identifier | string |
name | Human-friendly identifier | string |
required | Required for submissions | boolean |
type | TextField/TextArea/Select/Number/Email/Phone | string |
data | key-value pairs for type-specific data | object |
Create the fields
Create the workflow fields. Provide all of the fields and set them in one request.
Endpoint
POST https://embedworkflow.com/api/v1/workflows/:hashid/fields
Parameters
fields[] required
- An
array
of fields.
Field Parameters
field[type] required
- Valid types are:
TextField
,TextArea
,Select
,Number
,Email
, andPhone
field_key[name] required
- Human-friendly
string
describing the field. This value can be used as a dynamic placeholder in actions. For instance: set your email subject to "Welcome {{ Name }}!".
field_key[required] optional
- A true or false value indicating if this field is required in a form/api submission.
field_key[id] optional
- A unique identifier. The system will generate a random value if one isn't given.
field_key[data] optional
data
are key-value pairs:label
: the default label for the form field.placeholder
: the default placeholder for the form field.selectOptions
: only used forSelect
. A comma-separatedstring
for each option. E.g.'Red,Blue,Orange,Yellow
Request
curl 'https://embedworkflow.com/api/v1/workflows/75qeb/fields' \
--header 'Authorization: Bearer sk_test_12345'
fields = [
{"id": "10001", "data": {}, "name": "Name", "type": "TextField", "required": true},
{"id": "10002", "data": {}, "name": "Email", "type": "Email", "required": true},
{"id": "10003", "data": {}, "name": "Phone", "type": "Phone", "required": false}
]
EmbedWorkflow::Fields.create(workflow_hashid: "n83kp", fields: fields)
Response
[
{
"id": "10001",
"data": {},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "10002",
"data": {},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "10003",
"data": {},
"name": "Phone",
"type": "Phone",
"required": "false"
}
]
Fetch the fields
Retrieve the workflow's fields. Notice this is not a list
endpoint and does not return a paginated collection.
Endpoint
GET https://embedworkflow.com/api/v1/workflows/:hashid/fields
Parameters
No parameters
Request
curl -G 'https://embedworkflow.com/api/v1/workflows/740mp/fields' \
--header 'Authorization: Bearer sk_test_12345'
fields = [
{"id": "10001", "data": {}, "name": "Name", "type": "TextField", "required": true},
{"id": "10002", "data": {}, "name": "Email", "type": "Email", "required": true},
{"id": "10003", "data": {}, "name": "Phone", "type": "Phone", "required": false}
]
EmbedWorkflow::Fields.fetch(workflow_hashid: "n83kp")
Response
[
{
"id": "10001",
"data": {},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "10002",
"data": {},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "10003",
"data": {},
"name": "Phone",
"type": "Phone",
"required": "false"
}
]
Upsert a field
Create or update a workflow field. Provide the existing field's id
to update. If no existing id
is given, they will be auto-generated.
Endpoint
PUT https://embedworkflow.com/api/v1/workflows/:hashid/fields
Parameters
type required
- Valid types are:
TextField
,TextArea
,Select
,Number
,Email
, andPhone
name required
- Human-friendly
string
describing the field. This value can be used as a dynamic placeholder in actions. For instance: set your email subject to "Welcome {{ Name }}!".
required optional
- A true or false value indicating if this field is required in a form/api submission.
id optional
- A unique identifier. The system will generate a random value if one isn't given.
data optional
data
are key-value pairs:label
: the default label for the form field.placeholder
: the default placeholder for the form field.selectOptions
: only used forSelect
. A comma-separatedstring
for each option. E.g.'Red,Blue,Orange,Yellow
Request
curl -X PUT 'https://embedworkflow.com/api/v1/workflows/75qeb/fields' \
--header 'Authorization: Bearer sk_test_12345'
# Adding a new field
field = EmbedWorkflow::Fields.update(hashid: "n83kp", name: "Zip", type: "TextField", required: false)
# Updating a field
EmbedWorkflow::Fields.update(hashid: "n83kp", id: field["id"], name: "Postal Code", type: "TextField", required: true)
Response
[
{
"id": "10001",
"data": {},
"name": "Name",
"type": "TextField",
"required": true
},
{
"id": "10002",
"data": {},
"name": "Email",
"type": "Email",
"required": true
},
{
"id": "10003",
"data": {},
"name": "Phone",
"type": "Phone",
"required": false
},
{
"id": "gRaG",
"data": {},
"name": "Zip",
"type": "TextField",
"required": false
}
]
Delete a field
Delete a workflow field. Provide the existing field's id
or name
by setting the query parameter field_key
to remove the field.
Endpoint
DELETE https://embedworkflow.com/api/v1/workflows/:hashid/fields
Parameters
No parameters
Request
curl -X DELETE 'https://embedworkflow.com/api/v1/workflows/75qeb/fields?field_key=Zip' \
--header 'Authorization: Bearer sk_test_12345'
EmbedWorkflow::Fields.delete(hashid: "n83kp", field_key: "Zip")
Response
[
{
"id": "10001",
"data": {},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "10002",
"data": {},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "10003",
"data": {},
"name": "Phone",
"type": "Phone",
"required": "false"
}
]
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
Forms
The form object
Attribute | Description | Type |
---|---|---|
id | Unique identifier | string |
name | Name of the form | string |
layout | Form layout object | object |
fields | List fields available in the workflow (auth required) | array |
The form layout object
Attribute | Description | Type |
---|---|---|
blocks | Array of form Block's | array |
The block object
Attribute | Description | Type |
---|---|---|
id | Unique identifier | string |
name | Human-friendly label describing the action | string |
type | A valid block type | string |
required | Is this a required field? true or false | boolean |
data | A valid node type | string |
Block types
Type | Description |
---|---|
Header | Header text |
Text | Plain text |
Image | Image displayer |
Submit | Submit button |
TextField | Short text input |
TextArea | Long text input |
Select | Dropdown |
Number | Number input field |
Email input field | |
Phone | Phone number input field |
Data attributes by type
Header data attributes
{
"data": {
"value": "Signup Form"
}
}
Attribute | Description | Type |
---|---|---|
value | Header text to display | string |
Text data attributes
{
"data": {
"value": "Help us get to know you better by filling out the questions below."
}
}
Attribute | Description | Type |
---|---|---|
value | Plain text to display | string |
Image data attributes
{
"data": {
"url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png"
}
}
Attribute | Description | Type |
---|---|---|
url | Image URL | string |
Submit data attributes
{
"data": {
"label": "Submit",
"textColor": "#ffffff",
"backgroundColor": "#65211f"
}
}
Attribute | Description | Type |
---|---|---|
label | Image URL | string |
textColor | HEX text button color | string |
backgroundColor | HEX background button color | string |
TextField data attributes
{
"data": {
"label": "Full name",
"placeholder": "Enter your full name"
}
}
Attribute | Description | Type |
---|---|---|
label | Label displayed above the input | string |
placeholder | Input placeholder text | string |
TextArea data attributes
{
"data": {
"label": "Message",
"placeholder": "Enter your message"
}
}
Attribute | Description | Type |
---|---|---|
label | Label displayed above the input | string |
placeholder | Input placeholder text | string |
Select data attributes
{
"data": {
"label": "Favorite color",
"placeholder": "Enter your favorite color",
"selectOptions": "red,white,blue"
}
}
Attribute | Description | Type |
---|---|---|
label | Label displayed above the input | string |
placeholder | Input placeholder text | string |
selectOptions | Comma separated options | string |
Number data attributes
{
"data": {
"label": "Years of experience",
"placeholder": "Enter your years of experience",
"min": 0,
"max": 90,
}
}
Attribute | Description | Type |
---|---|---|
label | Label displayed above the input | string |
placeholder | Input placeholder text | string |
min | Input minimum value | integer |
max | Input maximum value | integer |
Email data attributes
{
"data": {
"label": "Email address",
"placeholder": "Enter your email address",
}
}
Attribute | Description | Type |
---|---|---|
label | Label displayed above the input | string |
placeholder | Input placeholder text | string |
Phone data attributes
{
"data": {
"label": "Phone number",
"placeholder": "Enter your phone number",
}
}
Attribute | Description | Type |
---|---|---|
label | Label displayed above the input | string |
placeholder | Input placeholder text | string |
Create a form
Create a form for your workflow. The form can be submitted through the web or by API.
Endpoint
POST https://embedworkflow.com/api/v1/workflows/:workflow_hashid/forms
Parameters
name required
- Human-friendly
string
describing the form.
layout optional
- A structured
hash
of the following key-value pairs:blocks
.blocks
is an array representing the ordered parts of the form. Ablock
is comprised of:id
,name
,type
, anddata
.
Request
EmbedWorkflow::Forms.create(name: "New Form")
curl 'https://embedworkflow.com/api/v1/workflows/740mp/forms/' \
--header 'Authorization: Bearer sk_test_12345' \
-d 'name=New Form'
Response
{
"id": "d3eda167-7fb3-48c3-8b89-30fb19301c20",
"fields": [
{
"id": "10001",
"data": {},
"name": "Name",
"type": "TextField",
"required": true
},
{
"id": "10002",
"data": {},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "10003",
"data": {},
"name": "Phone",
"type": "Phone",
"required": false
},
{
"id": "Zn3Z",
"data": {}
}
],
"layout": null,
"name": "David"
}
Fetch a form
Use this endpoint to load a form.
Endpoint
GET https://embedworkflow.com/api/v1/forms/:id
Parameters
No parameters
Request
curl -G 'https://embedworkflow.com/api/v1/forms/c6faa926-8345-438a-b177-3265f1df3799' \
EmbedWorkflow::Forms.fetch(id: "c6faa926-8345-438a-b177-3265f1df3799")
Response
{
"id": "c6faa926-8345-438a-b177-3265f1df3799",
"fields": null,
"layout": {
"blocks": [
{
"id": "429087",
"data": {
"value": "Contact Form",
"placeholder": "Enter undefined"
},
"type": "Header",
"description": "Header"
},
{
"id": "536344",
"data": {
"value": "Someone will reach out within 24 hours!",
"placeholder": "Enter undefined"
},
"type": "Text",
"description": "Text"
},
{
"id": "577544",
"data": {
"url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"placeholder": "Enter undefined"
},
"type": "Image",
"description": "Image"
},
{
"id": "925721",
"data": {
"label": "Name",
"placeholder": "Enter Name"
},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "680667",
"data": {
"label": "Email",
"placeholder": "Enter Email"
},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "766360",
"data": {
"label": "Phone",
"placeholder": "Enter Phone"
},
"name": "Phone",
"type": "Phone"
},
{
"id": "Submit",
"data": {
"label": "Submit",
"textColor": "#ffffff",
"backgroundColor": "#4f46e5"
},
"type": "Submit"
}
]
},
"name": "Form"
}
HTTP Request with Authentication
GET https://embedworkflow.com/api/v1/forms/:id
If authenticated, the response will include the workflow's fields
.
Request with Authentication
curl -G 'https://embedworkflow.com/api/v1/forms/2e9ff742-ef90-4470-b518-774b6579166e' \
--header 'Authorization: Bearer sk_test_12345'
Response
{
"id": "c6faa926-8345-438a-b177-3265f1df3799",
"fields": [
{
"id": "10001",
"data": {},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "10002",
"data": {},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "10003",
"data": {},
"name": "Phone",
"type": "Phone"
}
],
"layout": {
"blocks": [
{
"id": "429087",
"data": {
"value": "Contact Form",
"placeholder": "Enter undefined"
},
"type": "Header",
"description": "Header"
},
{
"id": "536344",
"data": {
"value": "Someone will reach out within 24 hours!",
"placeholder": "Enter undefined"
},
"type": "Text",
"description": "Text"
},
{
"id": "577544",
"data": {
"url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"placeholder": "Enter undefined"
},
"type": "Image",
"description": "Image"
},
{
"id": "925721",
"data": {
"label": "Name",
"placeholder": "Enter Name"
},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "680667",
"data": {
"label": "Email",
"placeholder": "Enter Email"
},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "766360",
"data": {
"label": "Phone",
"placeholder": "Enter Phone"
},
"name": "Phone",
"type": "Phone"
},
{
"id": "Submit",
"data": {
"label": "Submit",
"textColor": "#ffffff",
"backgroundColor": "#4f46e5"
},
"type": "Submit"
}
]
},
"name": "Form"
}
Update a form
Updating a form requires the auth token.
Endpoint
PUT https://embedworkflow.com/api/v1/forms/:id
Request
EmbedWorkflow::Forms.update(id: "436f1012-8d3f-4695-ac52-ffa343747301", name: "Update Form!")
curl -X PUT 'https://embedworkflow.com/api/v1/forms/c6faa926-8345-438a-b177-3265f1df3799' \
--header 'Authorization: Bearer sk_test_12345' \
-d 'name=Updated Form Name'
Response
{
"id": "c6faa926-8345-438a-b177-3265f1df3799",
"fields": "null",
"layout": {
"blocks": [
{
"id": "429087",
"data": {
"value": "Contact Form",
"placeholder": "Enter undefined"
},
"type": "Header",
"description": "Header"
},
{
"id": "536344",
"data": {
"value": "Someone will reach out within 24 hours!",
"placeholder": "Enter undefined"
},
"type": "Text",
"description": "Text"
},
{
"id": "577544",
"data": {
"url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"placeholder": "Enter undefined"
},
"type": "Image",
"description": "Image"
},
{
"id": "925721",
"data": {
"label": "Name",
"placeholder": "Enter Name"
},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "680667",
"data": {
"label": "Email",
"placeholder": "Enter Email"
},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "766360",
"data": {
"label": "Phone",
"placeholder": "Enter Phone"
},
"name": "Phone",
"type": "Phone"
},
{
"id": "Submit",
"data": {
"label": "Submit",
"textColor": "#ffffff",
"backgroundColor": "#4f46e5"
},
"type": "Submit"
}
]
},
"name": "Update Form!"
}
Delete a form
Deleting a form requires the auth token.
Endpoint
DELETE https://embedworkflow.com/api/v1/forms/:id
Request
curl -X DELETE 'https://embedworkflow.com/api/v1/forms/2e9ff742-ef90-4470-b518-774b6579166e' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Forms.delete(id: "436f1012-8d3f-4695-ac52-ffa343747301")
Response
{
"id": "436f1012-8d3f-4695-ac52-ffa343747301"
}
List all forms
List your forms.
Endpoint
GET https://embedworkflow.com/api/v1/workflows/:workflow_hashid/forms
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/nybra/forms' \
--header 'Authorization: Bearer sk_test_12345'
EmbedWorkflow::Forms.list(workflow_hashid: "nybra")
Response
{
"collection": [
{
"id": "c6faa926-8345-438a-b177-3265f1df3799",
"fields": "null",
"layout": {
"blocks": [
{
"id": "429087",
"data": {
"value": "Contact Form",
"placeholder": "Enter undefined"
},
"type": "Header",
"description": "Header"
},
{
"id": "536344",
"data": {
"value": "Someone will reach out within 24 hours!",
"placeholder": "Enter undefined"
},
"type": "Text",
"description": "Text"
},
{
"id": "577544",
"data": {
"url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"placeholder": "Enter undefined"
},
"type": "Image",
"description": "Image"
},
{
"id": "925721",
"data": {
"label": "Name",
"placeholder": "Enter Name"
},
"name": "Name",
"type": "TextField",
"required": "true"
},
{
"id": "680667",
"data": {
"label": "Email",
"placeholder": "Enter Email"
},
"name": "Email",
"type": "Email",
"required": "true"
},
{
"id": "766360",
"data": {
"label": "Phone",
"placeholder": "Enter Phone"
},
"name": "Phone",
"type": "Phone"
},
{
"id": "Submit",
"data": {
"label": "Submit",
"textColor": "#ffffff",
"backgroundColor": "#4f46e5"
},
"type": "Submit"
}
]
},
"name": "Update Form!"
}
],
"meta": {
"total_count": 1,
"page_limit": 25,
"total_pages": 1,
"current_page": 1,
}
}
Submit a form
Submit a form.
Endpoint
POST https://embedworkflow.com/api/v1/forms/:id/submissions
Request
curl 'https://embedworkflow.com/api/v1/forms/55a1bb06-9386-4ded-a5b9-a578ec0a542a/submissions' \
-d 'submission[name]=david'
EmbedWorkflow::Forms.submit(id: "c6faa926-8345-438a-b177-3265f1df3799", submission: { Name: "David", Email: "david@embedworkflow.com" })
Response
{}
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 |
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"
}
Tenants
The tenant object
Attribute | Description | Type |
---|---|---|
key | User created unique identifier | string |
hashid | System generated unique identifier | string |
config | Email address | hash |
config[primary_color] | Branding primary color | string |
config[logo_url] | Branding logo URL | string |
config[email_address] | 'From' email address | string |
config[email_name] | 'From' email name | string |
config[sms_number] | 'From' sms phone number | string |
Upsert a tenant
Update a tenant. Only the attributes provided will be updated. If the tenant does not exist, it will create the tenant.
Endpoint
PUT https://embedworkflow.com/api/v1/tenants/:key
Request
EmbedWorkflow::Tenants.upsert(
key: "main",
email_integration_key: "email-production",
sms_integration_key: "sms-production",
config: {
primary_color: "#333333",
logo_url: "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
email_name: "Embed Workflow",
email_address: "support@embedworkflow.com",
sms_number: ""
}
)
curl -X PUT 'https://embedworkflow.com/api/v1/tenants/account-1' \
--header 'Authorization: Bearer sk_test_12345' \
-d 'sms_integration_key=test' \
-d 'email_integration_key=default' \
-d 'config[logo_url]=https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png' \
-d 'config[primary_color]=#333333' \
-d 'config[email_name]=Embed Workflow' \
-d 'config[email_address]=support@embedworkflow.com' \
-d 'config[sms_number]='
Response
{
"key": "account-1",
"hashid": "474y7",
"config": {
"primary_color": "#333333",
"logo_url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"email_address": "support@embedworkflow.com",
"email_name": "Embed Workflow",
"sms_number": null
}
}
Fetch a tenant
Use this endpoint to load a tenant.
Endpoint
GET https://embedworkflow.com/api/v1/tenants/:key
Request
curl -G 'https://embedworkflow.com/api/v1/tenants/account-1' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Tenants.fetch(key: "account-1")
Response
{
"key": "account-1",
"hashid": "474y7",
"email_integration_key": "default",
"sms_integration_key": "test",
"config": {
"primary_color": "#333333",
"logo_url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"email_address": "support@embedworkflow.com",
"email_name": "Embed Workflow",
"sms_number": null
}
}
Delete a tenant
Delete a tenant.
Endpoint
DELETE https://embedworkflow.com/api/v1/tenants/:key
Request
curl -X DELETE 'https://embedworkflow.com/api/v1/tenants/account-1' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Tenants.delete(key: "account-1")
Response
{
"key": "account-1"
}
List all tenants
List your tenants.
Endpoint
GET https://embedworkflow.com/api/v1/tenants
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/tenants' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Tenants.list
Response
{
"collection": [
{
"key": "default",
"hashid": "474y7",
"config": {
"primary_color": "#333333",
"logo_url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"email_address": "support@embedworkflow.com",
"email_name": "Embed Workflow",
"sms_number": null
}
}
],
"meta": {
"total_count": 1,
"page_limit": 25,
"total_pages": 1,
"current_page": 1,
}
}
Integrations
The integration object
Attribute | Description | Type |
---|---|---|
key | User created unique identifier | string |
hashid | System generated unique identifier | string |
integration_type | A valid integration type | string |
integration_data | The integration data values | hash |
Integration types
Type | Description |
---|---|
email_sendgrid | Sendgrid |
email_amazon | Amazon Simple Email Service |
email_mandrill | Mandrill |
email_postmark | Postmark |
sms_twilio | Twilio |
sms_telnyx | Telnyx |
Integration data
email_sendgrid
Hash key | Example Value |
---|---|
domain | embedworkflow.com |
api_key | SG.123456789ABCDEF-ABC321.HABCDEIsu11EmjIe6fJJaaaaaaa4QcOp4DUxc512345 |
email_amazon
Hash key | Example Value |
---|---|
domain | embedworkflow.com |
password | super-secret-iam-user-password |
host_name | email-smtp.us-east-1.amazonaws.com |
user_name | yourIAMusername |
email_mandrill
Hash key | Example Value |
---|---|
domain | embedworkflow.com |
api_key | md-1234ABC123ZYX9021DEFA1 |
user_name | Embed Workflow (any username will work) |
email_postmark
Hash key | Example Value |
---|---|
api_key | 123ABC12-ZXCV-3211-12AB-ABCABC333111 |
sms_twilio
Hash key | Example Value |
---|---|
account_sid | AAa1234567AAa1234567AAa1234567abcdef |
auth_token | 1234535abc123DEF1234567890123456 |
sms_telnyx
Hash key | Example Value |
---|---|
api_key | KEY1234535abc123DEF1234567890123456_123DEF1234567890123456 |
Upsert an Integration
Create or update an integration. Only the attributes provided will be updated.
Endpoint
PUT https://embedworkflow.com/api/v1/integrations/:key
Request
EmbedWorkflow::Integrations.upsert(
key: "main",
status: "on",
integration_type: "email_sendgrid",
integration_data: {
domain: "embedworkflow.com",
api_key: "123ABC456def"
}
)
curl -X PUT 'https://embedworkflow.com/api/v1/integrations/email_sendgrid' \
--header 'Authorization: Bearer sk_test_12345' \
-d 'integration_type=email_sendgrid' \
-d 'integration_data[domain]=embedworkflow.com' \
-d 'integration_data[api_key]=123ABC456def'
Response
{
"key": "email_sendgrid",
"hashid": "pxajx",
"integration_data": {
"domain": "embedworkflow.com",
"api_key": "123ABC456def"
},
"integration_type": "email_sendgrid",
"status": "on"
}
Fetch an integration
Use this endpoint to load an integration.
Endpoint
GET https://embedworkflow.com/api/v1/integrations/:key
Request
curl -G 'https://embedworkflow.com/api/v1/integrations/email-production' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Integrations.fetch(key: "email-production")
Response
{
"key": "email-production",
"integration_type": "email-sengrid",
"integration_data": {
"domain": "embedworkflow.com",
"api_key": "ABC123XYZ",
}
}
Delete an integration
Delete an integration.
Endpoint
DELETE https://embedworkflow.com/api/v1/integrations/:key
Request
curl -X DELETE 'https://embedworkflow.com/api/v1/integrations/sendgrid-production' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Tenants.delete(key: "sendgrid-production")
Response
{
"key": "sendgrid-production"
}
List all integrations
List your integrations.
Endpoint
GET https://embedworkflow.com/api/v1/integrations
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/integrations/' \
--header 'Authorization: Bearer sk_test_12345' \
EmbedWorkflow::Integrations.list
Response
{
"collection": [
{
"key": "default",
"config": {
"primary_color": "#333333",
"logo_url": "https://embedworkflow.com/assets/logo-dark-ac3f24918e46816034763925e7e2272381c18907601677ffa9e842f46555e80d.png",
"email_address": "support@embedworkflow.com",
"email_name": "Embed Workflow",
"sms_number": null
}
}
],
"meta": {
"total_count": 1,
"page_limit": 25,
"total_pages": 1,
"current_page": 1,
}
}