NAV
curl ruby

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.

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

Endpoints
POST
GET
PUT
GET
POST
POST
POST
GET

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
Email 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

template optional

tenant_key optional

auto_start optional

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

template optional

tenant_key optional

auto_start optional

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

ending_before optional

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

user_key optional

form_data optional

execution_data optional

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

ending_before optional

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

Endpoints
POST

Trigger workflows

Trigger workflows to create executions.

Endpoint

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

Parameters

event optional

all_workflows optional

workflow_hashids optional

workflow_keys optional

user_key optional

form_data optional

execution_data optional

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
Endpoints
POST
GET
PUT
DELETE

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

Field Parameters

field[type] required

field_key[name] required

field_key[required] optional

field_key[id] optional

field_key[data] optional

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

name required

required optional

id optional

data optional

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

Endpoints
GET
GET

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
Endpoints
POST
GET
PUT
DELETE
GET
POST

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

layout optional

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

ending_before optional

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 Email address string
name Display name string
Endpoints
PUT
GET

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
Endpoints
PUT
GET
DELETE
GET

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

ending_before optional

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
Endpoints
PUT
GET
DELETE
GET

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

ending_before optional

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,
  }
}
curl ruby