API Reference

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 and PUT 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",
    ...
  },
}