• Version: 1.2.0

Flows

Flows are containers for data. They are composed of one or more fields, which can be of various data types. You can add fields to any existing or custom flow.

Many of the Moltin endpoints and objects access and manipulate flows. The following can be accessed and modified using the flows system:

This list resembles the list endpoints accessible through entries. Whenever you add data to your store using the fields specified by a flow, you create an entry. For example, Customers is the flow, while John Smith would be the entry. You can change the data within a single object using entries; you can change the structure of this data for all objects of that type using flows.

Flows are composed of fields. Each field specifies the type of data - string, integer, binary, etc. - and whether it is required or must be unique across all entries. Data added to create an entry must be of the data types specified for each field.

You can perform any of the below actions on any existing or custom flows. That means you can add and modify the fields for existing flows or build entirely new data structures.

The base endpoint for flows is https://api.molt.in/v1/flows, though many of the other functions extend off of this.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

Unless otherwise indicated, successful calls of the formats specified below will return a 200 OK HTML status code.

This topic will cover the following processes:

Create a flow

While many of the tools within the Moltin API use flows, the real power of flows comes from creating your own. Custom flows allow you to store and retrieve data on external servers using premade templates. This takes care of a lot of heavy lifting, while giving you plenty of flexibility in how you construct your data structures.

To create a new flow, you need to POST the required data to the flows endpoint.

Key Type Required Unique Details
id Integer No Yes An identifying number that can be used in some endpoints to refer to this flow or its entries.
name String Yes No The internal name of the flow.
slug String Yes Yes The string used to refer to this flow, either in the methods below or in URLs.
info String No No A description of this flow.
title_column String No No Specifies the field that can be used instead of the entry ID.
has_images Choice No No Indicates whether this flow has an images field (1), which can contain an array of images to use with this flow. Defaults to 0.
enabled Choice No No Indicates whether entries in this flow can be created, accessed, or deleted (1).
entries Integer No No The number of entries that have been created with this flow.
fields Integer No No The number of fields that make up this flow.
locked Choice No No Indicates whether this flow can be edited (0) or if it has been locked to prevent further changes (1).
curl -X POST https://api.molt.in/v1/flows \
  -H "Authorization: Bearer XXXX" \
  -d "slug=gifts" \
  -d "name=Gift Cards"

On success, this call returns the flow information for the newly created flow, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "name":"Gift Cards",
    "slug":"gifts",
    "info":null,
    "title_column":null,
    "has_images":false,
    "enabled":true,
    "entries":0,
    "fields":0,
    "locked":false
  }
}

Actions that return general flow information will return it in this format. Other endpoints related to flows that return fields, data types, or field options will not.

Create a Field in a Flow

Once you have a flow that you want to add fields to, whether that flow is custom or pre-created, use a POST call with the flows/{flow slug}/fields endpoint. You’ll need to call this for each field that you want to add.

Key Type Required Unique Details
slug String Yes Yes A string used to reference this field in other endpoints, as well as the name to pass to set a value for this field in entries.
name String Yes No The display name for this field.
type String Yes No The type of data that this field accepts in entries. See below for more information on data types.
options multiple No No Additional options for this field. The specific options differ between data types. See below for more information on the options and available values for each field.
required Choice No No Indicates whether this field must be set (1) when creating an entry. If not specified, this will be set to 0 by default.
unique Choice No No Indicates whether the value stored in this field must be unique across all entries for this flow (1). If not specified, this will be set to 0 by default.
locked Choice No No Indicates whether this field can be edited (0) or if it has been locked to prevent editing (1). If not specified, this will be set to 0.
order Integer No No The order in which this field is displayed.
instructions String No No Directions for end users on how to complete this field.
available multiple No No Cannot be set. When retrieved, this field displays the available values for this field. This field only appears with some data types.
value Depends on data type No No The default value of this field.
curl -X POST https://api.molt.in/v1/flows/gifts/fields \
  -H "Authorization: Bearer XXXX" \
  -d "slug=value" \
  -d "name=Card Value" \
  -d "type=integer" \
  -d "required=1"

On success, this call returns the field information for the newly created field, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "slug":"value",
    "name":"Card Value",
    "type":"integer",
    "options":
    {
      "default":0
    },
    "required":true,
    "unique":false,
    "locked":false,
    "order":null,
    "instructions":null
  }
}

List All Field Data Types

Each of the fields in a flow has a data type that affects how information passed to it is stored and managed. This can be as simple as a string or integer, or as complicated as a relationship to another flow or multiple values.

curl -X GET https://api.molt.in/v1/flows/types \
  -H "Authorization: Bearer XXXX"

This will return the list of all valid field data types. Below are how each of these field types affect the fields that they are assigned to.

  • choice - Choice fields accept one of a set of specified integers, each of which indicates a specific result. You can use this field type for true-false fields.
  • country - Accepts a standard three-letter country abbreviation.
  • date - Accepts a formatted date string.
  • decimal - Accepts a number with decimal points.
  • email - Accepts a properly formatted email address, including the @ symbol.
  • integer - Accepts a whole number without decimal values.
  • relationship - Accepts a reference to another entry, usually the ID number or slug.
  • slug - Accepts a string formatted as a slug; no capital letters or spaces allowed.
  • string - Accepts any plain text string.
  • text - Accepts HTML formatted text.
  • multiple - Accepts a JSON array.
  • tax-band - Accepts a tax band ID.
  • gateway - Accepts the slug of a valid gateway.
  • currency - Accepts the standard three letter abbreviation for a currency.
  • money - Formats the field according to the active currency. Money fields will be split into raw, formatted, and unformatted subfields.
  • file - Accepts a file upload. You will have to place the ‘@’ character before the path and name of any file that you want to upload.

Each of the fields that you add to a flow must be of one of the above types.

Retrieve a Single Field Data Type

If you just want information about a single field data type, append the slug for that type to the flows/types endpoint.

curl -X GET https://api.molt.in/v1/flows/types/decimal \
  -H "Authorization: Bearer XXXX"

This will return only the data type information for the specified slug.

List All Flows

To see what flows you can access and retrieve high-level information about them, use a GET call with the https://api.molt.in/v1/flows endpoint.

curl -X GET https://api.molt.in/v1/flows \
  -H "Authorization: Bearer XXXX"

This will return an array of flow information objects, as described in the Create a Flow section.

Retrieve a Single Flow by Slug

If you only want to see the flow information for a single flow, you can append the flow slug to the flows endpoint.

curl -X GET https://api.molt.in/v1/flows/customers \
  -H "Authorization: Bearer XXXX"

This will return high-level information about that slug in the format described in the Create a Flow section.

List All Fields for a Flow

Flows are composed of individual data fields. To see a list of all of the fields within a flow, append ‘fields’ to the flows/{flow slug} endpoint.

curl -X GET https://api.molt.in/v1/flows/customers/fields \
  -H "Authorization: Bearer XXXX"

This will return an array of all of the fields with some information about each field.

{
  "status":true,
  "result":
  {
    "first_name":
    {
      "slug":"first_name",
      "name":"First Name",
      "type":"string",
      "options":
      {
        "multilingual":false
      },
      "required":true,
      "unique":false,
      "locked":true,
      "order":null,
      "instructions":null,
      "value":null
    },
    "last_name":
    {
      "slug":"last_name",
      "name":"Last Name",
      "type":"string",
      "options":
      {
        "multilingual":false
      },
      "required":true,
      "unique":false,
      "locked":true,
      "order":null,
      "instructions":null,
      "value":null
    },
    "email":
    {
      "slug":"email",
      "name":"Email Address",
      "type":"email",
      "options":[],
      "required":true,
      "unique":true,
      "locked":true,
      "order":null,
      "instructions":null,
      "value":null
    },
    "group":
    {
      "slug":"group",
      "name":"Group",
      "type":"relationship",
      "options":
      {
        "relates_to":69
      },
      "required":false,
      "unique":false,
      "locked":true,
      "order":null,
      "instructions":null,
      "available":
      {
        "1058740804207509575":"test_group",
        "1059506796542034407":"employees",
        "1061078393216303747":"Good People"
      },
      "value":null
    }
  }
}

Each of these fields - for example, first_name above - returns the current field settings as shown in the Create a Field in a Flow section.

Retrieve a Single Field by Slug

If you just want information about a specific field in a flow, append the field slug to the flows/{flow slug}/fields endpoint.

curl -X GET https://api.molt.in/v1/flows/customers/fields/first_name \
  -H "Authorization: Bearer XXXX"

This will return only the field information for the specified slug.

List Options for a Single Field Data Type

Some field data types have additional options or require a specific value from a list of available values. To see those, you need send a GET call using a complicated endpoint: flows/{flow slug}/types/{type slug}/options. This call needs to include a specific flow slug because some field data types, like relationship, will have available options that differ between flows.

curl -X GET https://api.molt.in/v1/flows/customers/types/string/options \
  -H "Authorization: Bearer XXXX"

This will return a list of options for that data type, information about these options, and - depending on the data type - a list of available values.

{
  "status":true,
  "result":
  {
    "multilingual":
    {
      "slug":"multilingual",
      "name":"Multilingual",
      "type":"choice",
      "options":
      {
        "choices":
        [
          "No",
          "Yes"
        ],
        "default":0
      },
      "required":true,
      "unique":false,
      "locked":true,
      "order":null,
      "value":
      {
        "value":"No",
        "data":
        {
          "key":0,
          "value":"No"
        }
      }
    }
  }
}

Other flow/type combinations will return information in this format.

List Options for a Single Field Within a Flow

If you want to see the options for a specific field in a flow instead of a type, send a GET call using the flows/{flow slug}/fields/{field slug}/options endpoint.

curl -X GET https://api.molt.in//v1/flows/customers/fields/first_name/options \
  -H "Authorization: Bearer XXXX"

This will return option information in the same format as the previous section.

Update a Flow

To change the settings of an existing flow, use a PUT call on the flows/{flow slug} endpoint.

curl -X PUT https://api.molt.in/v1/flows/gifts \
  -H "Authorization: Bearer XXXX" \
  -d "has_images=1"

This will modify the existing flow and return that flow’s current information.

A special case happens when you update the enabled field to 0. This disables the flow and prevents it and all entries from being returned without deleting any of the data from your store. Any relationship fields that point to that flow will be ignored.

Update a Field Within a Flow

Like flows, you can update an existing field’s settings. Use a PUT call with the flows/{flow slug}/fields/{field slug} endpoint.

curl -X POST https://api.molt.in/v1/flows/gifts/fields/value \
  -H "Authorization: Bearer XXXX" \
  -d "value=10"

On success, this returns that field’s updated information.

A special case happens when you update the enabled field to 0. This disables the field and prevents it from being returned in all entries without deleting any of the data from your store.

Delete a Field from a Flow

If you want to permanently remove a field from a flow, use a DELETE call with the flows/{flow slug}/fields/{field slug} endpoint.

curl -X POST https://api.molt.in/v1/flows/gifts/fields/value \
  -H "Authorization: Bearer XXXX"

This will delete the field values from all existing flows, as well as prevent all future flows from setting this field.

Delete a Flow

If you want to permanently remove a flow and all entries from your store, use a DELETE call on the flows/{flow slug} endpoint.

curl -X DELETE https://api.molt.in/v1/flows/gifts \
  -H "Authorization: Bearer XXXX"

This will permanently remove that flow, all existing entries in that flow, and all relationship fields in other flows that point to the deleted flow. This cannot be undone. If you only want to temporarily remove a flow, update the enabled field for that flow to 0.


List of endpoints for flows

GET /v1/flows

List all flows

GET /v1/flows/types

List all the types of flows

GET /v1/flows/types/:slug

Get a flow type by slug

GET /v1/flows/types/:slug/fields

Get all the fields for that flow by slug

POST /v1/flows

Create a new flow


GET /v1/flows/:slug

Get a single flow by slug

DELETE /v1/flows/:slug

Delete a flow by its slug

PUT /v1/flows/:slug

Update a flow by slug

GET /v1/flows/:slug/types/:typeSlug/options

Get a list of options for the flow type from the flow slug - yikes, confusing!

GET /v1/flows/:slug/fields

Get a list of fields for a flow

GET /v1/flows/:slug/fields/:fieldSlug

Get a single field for a flow

GET /v1/flows/:slug/fields/:fieldSlug/options

Get single field options for a flow

PUT /v1/flows/:slug/fields/:fieldSlug

Update a single field by slug for a flow

DELETE /v1/flows/:slug/fields/:fieldSlug

Delete a single field by slug for its flow

POST /v1/flows/:slug/fields

Create a field on a single flow


GET /v1/flows/:slug/entries

Get an entry from a flow

GET /v1/flows/:slug/entries/search

Search for an entry from a flow

POST /v1/flows/:slug/entries

Create an entry on a flow

GET /v1/flows/:slug/entries/:id

Get an entry on a flow by id

GET /v1/flows/:slug/entries/:id/fields

Get an entries fields by id from a flow

DELETE /v1/flows/:slug/entries/:id

Delete an entry from a flow by id

PUT /v1/flows/:slug/entries/:id

Update an entry on a flow by id


Flows are like containers. Types are the type of data you can hold. These are like strings, text, email, integer, money, and these each have the ability to have options. So for example, text can have a multi-lingual option being true or false.

Fields are the types of things the container can hold. For example, a flow could have a field of email and be a type email. That would mean it would validate the data going into it like an email should.

Entries are the records you can add to the flows. The actual data. Customers, products, orders, etc are all entries on flows.


A practical example:

  • flows/types

Gives us a list of types we can use in flows

  • flows/customers

Is the customers flow

  • flows/customers/fields

Gives us a list of the available fields on that flow like so:

{ "status": true, "result": { "first_name": { "slug": "first_name", "name": "First Name", "type": "string", "options": { "multilingual": false }, "required": true, "unique": false, "locked": true, "order": null, "instructions": null, "value": null }, "last_name": { "slug": "last_name", "name": "Last Name", "type": "string", "options": { "multilingual": false }, "required": true, "unique": false, "locked": true, "order": null, "instructions": null, "value": null }, "email": { "slug": "email", "name": "Email Address", "type": "email", "options": [], "required": true, "unique": true, "locked": true, "order": null, "instructions": null, "value": null }, "group": { "slug": "group", "name": "Group", "type": "relationship", "options": { "relates_to": 69 }, "required": false, "unique": false, "locked": true, "order": null, "instructions": null, "available": { "2926": "Test" }, "value": null }, "gender": { "slug": "gender", "name": "Gender", "type": "choice", "options": { "choices": { "m": "Male", "f": "Female" }, "default": "m" }, "required": false, "unique": false, "locked": false, "order": null, "instructions": null, "value": null } } }

  • flows/customers/fields/first_name/options

Gives us the options available on that field. For example, text fields can have multi-lingual enabled and so on.

  • flows/customers/entries

Is a list of the entries in that flow


Disable a flow

Disabling a flow will prevent it being returned for any requests whilst retaining all flow fields and data. Any relationship fields pointing at the deleted flow will be ignored.

To disable a flow, set the enabled value to 0 when updating the flow.

Delete a flow

Deleting a flow will remove it from your site permanently. Deletions always cascade, meaning any relationships fields pointing to the deleted flow from other flows will also be removed.