API Specification
Last updated
Was this helpful?
Last updated
Was this helpful?
The Flow Specification is designed to be useful in both file-based and API-based data exchange. File-based usage is adequate for testing, archiving and transferring flows manually between systems. However, in many production situations, interoperable systems are likely to exchange flows and request actions on flows via API methods. When implementations provide access to Flows and Flow operations via an API, the following standardized endpoints, parameters, and envelope formats shall be used.
Two methods of authentication are supported for clients accessing Flow Results APIs. All methods should use HTTPS for security.
Implementations must support token-based authentication, via the "Authorization" HTTP header, using the Token method. An example of a complete authorization header is:
Implementations can determine the format of tokens. The issuance, expiry, and exchange of tokens is left outside the scope of the Flow Results specification.
Providing additional support for HTTPS Basic Auth is optional, but recommended.
The Flow API adheres to the specification, version 1.0, an open standard for how a client should request that resources be fetched or modified, and how a server should respond to those requests, via JSON. All API requests and responses defined below reflect the JSON API norms for query parameters and pagination. Adopting JSON API allows API clients to make use of standard .
Endpoints that paginate responses must do so consistent with the JSON API specification. The standard pagination query parameters are:
page[size]: The requested number of responses per pagination page
page[afterCursor]: The cursor to requests responses after this id, when paginating forward
page[beforeCursor]: The cursor to request responses prior to this id, when paginating in reverse.
Endpoints that paginate shall provide a links section with self, next, and previous as appropriate.
Endpoints are defined relative to a base URL chosen by the implementing system, i.e.:
This endpoint is used to publish a Container of Flows to an external system. The Container should contain all related Flows that depend on each other (e.g.: accessed via RunAnotherFlow blocks, etc.). Flows in the container with the same uuid that already exist on the system will be updated (subject to the update_mode parameter below).
The receiving system should consider how it will manage resource media referenced within the Container (i.e.: whether it makes local copies of the resource media or depends on external availability, etc.)
URL: PUT [Base URL]/flow-spec/containers
Query parameters:
update_mode (Optional): One of the following values that determine whether existing Flows are updated with the submitted definition. (most_recent is the default.) If an update would be rejected due to existing Flows under most_recent or never, the system must respond with 409 Conflict.
always: Always update existing Flows with the same uuids.
most_recent: Update existing Flows when the last_modified value is more recent than the system has already.
never: Never update existing Flows if they already exist on the system.
Request body: The request body shall specify the type of containers. It shall contain, within the attributes parameter, the JSON structure of the Container.
A server MAY accept a client-generated ID along with a request to create a resource. An ID MUST be specified with an id key, the value of which MUST be a universally unique identifier. The client SHOULD use a properly generated and formatted UUID as described in RFC 4122 [RFC4122]. A server MUST return 403 Forbidden in response to an unsupported request to create a resource with a client-generated ID.
Receiving systems need not maintain and track Container uuids; a Container is used only for encapsulation of Flows during data exchange and can be temporary. It is the uuid of individual Flows that determines Flow identity. An individual Flow can be submitted and/or updated as part of one or more different Containers.
Request example:
Response:
Response example:
This endpoint is used to request a list of the Flows available on a system for an authorized user.
(Note that Flows are submitted within Containers for efficiency when sharing resources, and to bundle dependent Flows together. However, it is still possible to examine the individual list of Flows.)
URL: GET [Base URL]/flow-spec/flows
Request body: None
Request example:
Response example:
This endpoint is used to request the JSON definition of a single Flow stored on the system.
URL: GET [Base URL]/flow-spec/flows/[id]
Query parameters: None
Request body: None
Request example:
Response example:
This endpoint is used to request a Container with a set of Flows and all dependent resources.
Systems may generate a temporary UUID for the Container.
URL: GET [Base URL]/flow-spec/containers
Query parameters: None
Request body:
with_flows (array): An array of Flow UUIDs to request to be assembled, along with dependent resources, into a Container.
Request example:
Response body: A Container assembled with the requested Flows and all required Resources.
Response example:
This endpoint is used to ask a system to run (launch) an outbound Flow against one or more Contacts.
Synchronization of Contact information between systems is a relevant (and difficult) problem to solve generally, especially when two-way synchronization and conflict resolution are required. The Flow Specification therefore leaves contact synchronization outside the scope of this API spec. However, there is a frequent requirement to ensure that systems running Flows at the request of another system have an up-to-date copy of Contact properties/parameters as of the start of a flow. This endpoint therefore includes a basic ability to transmit the current state of Contacts to populate context at the start of the Flow. Additional information can be transferred within vendor_metadata.
URL: POST [Base URL]/flow-spec/run_requests
Query parameters: None
Request body: The request body shall specify the type of run_requests. It shall contain, within the attributes parameter, the following information:
flow (uuid)
UUID of the Flow to initiate on Contacts.
contacts (array of contacts, optional)
An array of contacts that should receive the Flow. (See example below.) Contacts must have a urn to reach them at. (URNs for telephone numbers may omit the "tel:" prefix.) Contacts optionally have a set of current properties, a preferred_mode, and a preferred_language. (Systems may impose limits for the number of contacts supported in one run request.)
groups (array of group identifiers, optional)
For systems that have a synchronized contact database, an array of group identifiers. Flows will be initiated to all contacts in these groups. Only one of contacts or groups shall be provided. (Systems may impose limits for the number of groups supported in one run request.)
default_mode (string)
The default mode to run the Flow for all contacts, unless overriden by preferred_mode.
default_language (string)
The default language (as a Flow Language Identifier) to run the Flow for all contacts, unless overriden by preferred_language.
delay_until (date-time, optional)
Indicates the system must delay the start of flow runs until the specified date and time (GMT).
vendor_metadata (object, optional)
Contains additional options on Flow runs that are relevant to specific vendor systems. Vendors must use namespaces within vendor_metadata to avoid collisions. Suggested namespaces use reverse domain name notation, with periods replaced by underscores (e.g.: A vendor with domain https://my.example-flow-server.com would place entries within vendor_metadata.com_example-flow-server_my).
Request example:
Response example:
This endpoint lists all run requests
URL: GET [Base URL]/flow-spec/run_requests
Query parameters:
filter[flow]: Only include run requests for the Flow given by the specified uuid.
filter[start-timestamp]: Only show run requests that were posted after this timestamp (exclusive). (This is a timestamp in the format of RFC 3339, section 5.6, date-time.)
filter[end-timestamp]: Only show run requests that were recorded before and on this timestamp (inclusive). (This is a timestamp in the format of RFC 3339, section 5.6, date-time.)
Request body: None
Request example:
The status of run_requests shall be one of:
SCHEDULED: The request is delayed and scheduled for the future according to the delay_until parameter.
IN_PROGRESS: The system is currently executing Flow runs for this request.
COMPLETED: The system has finished executing Flow runs for this request.
Lists of contacts and their initial properties may be omitted from the response.
Response example:
This endpoint lists one run request.
URL: GET [Base URL]/flow-spec/run_requests/[id]
Query parameters: None
Request body: None
Request example:
The status of run_requests shall be one of:
SCHEDULED: The request is delayed and scheduled for the future according to the delay_until parameter.
IN_PROGRESS: The system is currently executing Flow runs for this request.
COMPLETED: The system has finished executing Flow runs for this request.
Lists of contacts and their initial properties may be omitted from the response.
Response example:
Base URL:
The uuid of the Container and each Flow can be omitted (or null) if the client wants the receiving system to assign a new UUID for these. If a uuid is provided for Flows, the client must ensure that the UUID conforms to the requirements for client-generated IDs:
The response from the server must adhere to the for POST responses. When Client-Generated IDs are provided, systems should make use of the 204 No Content response mechanism to report acceptance to clients without sending back long documents.
Query parameters:
Response body: The response from the server must adhere to the for fetching a collection of resources. The data array includes the list of flows. Implementations may decide what summary information they want to publish in the attributes for each package.
Response body: The response from the server must adhere to the for fetching a resource.
Response body: The response from the system must adhere to the for POST responses. When a Client-Generated ID is provided, systems should make use of the 204 No Content response mechanism to report acceptance to clients without sending back long documents.
Response body: The response from the server must adhere to the for fetching a resource. The type of the resource must be run_requests.
Response body: The response from the server must adhere to the for fetching a resource. The type of the resource must be run_requests.