Update User Flow State

POST

public

flowStates

curl --request POST \
  --url https://api.frigade.com/v1/public/flowStates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "userId": "d34daa11-3745-4ac0-880e-d4b4d51fe13f",
  "groupId": "x34daa11-3745-4ac0-880e-d4b4d51fe13f",
  "flowSlug": "flow_abc",
  "stepId": "<string>",
  "data": {
    "action": "click"
  },
  "actionType": "COMPLETED_STEP"
}'

{
  "eligibleFlows": [
    {
      "flowSlug": "flow_abc",
      "flowName": "Onboarding Checklist",
      "flowType": "ANNOUNCEMENT",
      "data": {
        "steps": [
          {
            "id": "step_abc",
            "$state": {
              "completed": true,
              "skipped": true,
              "started": true,
              "visible": true,
              "blocked": true,
              "lastActionAt": "2024-09-01T00:00:00.000Z",
              "flowResponses": [
                {
                  "flowSlug": "flow_abc",
                  "actionType": "STARTED_STEP",
                  "stepId": "step-1",
                  "data": "{\"key\": \"value\"}",
                  "createdAt": "2024-01-01T00:00:00Z"
                }
              ]
            }
          }
        ]
      },
      "$state": {
        "currentStepId": "step_abc",
        "currentStepIndex": 1,
        "completed": true,
        "started": true,
        "skipped": true,
        "visible": true,
        "lastActionAt": "2024-09-01T00:00:00.000Z",
        "flowResponses": [
          {
            "flowSlug": "flow_abc",
            "actionType": "STARTED_STEP",
            "stepId": "step-1",
            "data": "{\"key\": \"value\"}",
            "createdAt": "2024-01-01T00:00:00Z"
          }
        ]
      },
      "version": 1
    }
  ],
  "ineligibleFlows": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

Authentication header of the form Bearer: <token>, where <token> is either your public or private API key. See when to use which

Body

application/json

userId

string

required

The ID of the user

Example:

"d34daa11-3745-4ac0-880e-d4b4d51fe13f"

flowSlug

string

required

The Flow Slug

Example:

"flow_abc"

actionType

enum<string>

required

The type of action the user took

Available options:

STARTED_STEP,

COMPLETED_STEP,

SKIPPED_STEP,

NOT_STARTED_STEP,

STARTED_FLOW,

COMPLETED_FLOW,

SKIPPED_FLOW,

NOT_STARTED_FLOW

Example:

"COMPLETED_STEP"

groupId

string

Optional ID of the group

Example:

"x34daa11-3745-4ac0-880e-d4b4d51fe13f"

stepId

string

The Step ID if updating a specific Step

data

string

Any optional data including the user action

Example:

{ "action": "click" }

Response

201 - application/json

The user's state in the Flow was updated

eligibleFlows

object[]

List of Flows that the user is eligible for as well as the user's state in each Flow

eligibleFlows.flowSlug

string

The Flow Slug

Example:

"flow_abc"

eligibleFlows.flowName

string

The Flow Name

Example:

"Onboarding Checklist"

eligibleFlows.flowType

string

The Flow Type

Example:

"ANNOUNCEMENT"

eligibleFlows.data

object

The Flow's metadata including the user's state in each step

eligibleFlows.data.steps

object[]

List of Steps in the Flow

eligibleFlows.data.steps.id

string

The Step ID

Example:

"step_abc"

eligibleFlows.data.steps.$state

object

The Step State

eligibleFlows.data.steps.$state.completed

boolean

Whether the Step is completed

Example:

true

eligibleFlows.data.steps.$state.skipped

boolean

Whether the Step has been skipped

Example:

true

eligibleFlows.data.steps.$state.started

boolean

Whether the Step has been started

Example:

true

eligibleFlows.data.steps.$state.visible

boolean

Whether the Step is visible (based on visibilityCriteria)

Example:

true

eligibleFlows.data.steps.$state.blocked

boolean

Whether the Step is blocked (based on startCriteria)

Example:

true

eligibleFlows.data.steps.$state.lastActionAt

string

The last time the user took an action on the Step

Example:

"2024-09-01T00:00:00.000Z"

eligibleFlows.data.steps.$state.flowResponses

object[]

The flow responses associated with the user in the Step. This is only available when using a private API key.

Example:

[
  {
    "flowSlug": "flow_abc",
    "actionType": "STARTED_STEP",
    "stepId": "step-1",
    "data": "{\"key\": \"value\"}",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

eligibleFlows.$state

object

The user's state in the Flow

eligibleFlows.$state.currentStepId

string

The current step (if any) the user is on

Example:

"step_abc"

eligibleFlows.$state.currentStepIndex

number

The index of the current step in the Flow. Will be -1 if the user has not started the Flow

Example:

1

eligibleFlows.$state.completed

boolean

Whether the Flow is completed

Example:

true

eligibleFlows.$state.started

boolean

Whether the Flow has been started

Example:

true

eligibleFlows.$state.skipped

boolean

Whether the Flow has been skipped/dismissed

Example:

true

eligibleFlows.$state.visible

boolean

Whether the Flow is visible (based on the Flow's Targeting)

Example:

true

eligibleFlows.$state.lastActionAt

string

The last time the user took an action on the Flow

Example:

"2024-09-01T00:00:00.000Z"

eligibleFlows.$state.flowResponses

object[]

The flow responses associated with the user in the Flow. This is only available when using a private API key.

Example:

[
  {
    "flowSlug": "flow_abc",
    "actionType": "STARTED_STEP",
    "stepId": "step-1",
    "data": "{\"key\": \"value\"}",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

eligibleFlows.version

number

The version number of the Flow

Example:

1

ineligibleFlows

string[]

List of Flow IDs that the user is ineligible for (for instance if a Flow is turned off)

Get User Flow State Create or update a User

curl --request POST \
  --url https://api.frigade.com/v1/public/flowStates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "userId": "d34daa11-3745-4ac0-880e-d4b4d51fe13f",
  "groupId": "x34daa11-3745-4ac0-880e-d4b4d51fe13f",
  "flowSlug": "flow_abc",
  "stepId": "<string>",
  "data": {
    "action": "click"
  },
  "actionType": "COMPLETED_STEP"
}'

{
  "eligibleFlows": [
    {
      "flowSlug": "flow_abc",
      "flowName": "Onboarding Checklist",
      "flowType": "ANNOUNCEMENT",
      "data": {
        "steps": [
          {
            "id": "step_abc",
            "$state": {
              "completed": true,
              "skipped": true,
              "started": true,
              "visible": true,
              "blocked": true,
              "lastActionAt": "2024-09-01T00:00:00.000Z",
              "flowResponses": [
                {
                  "flowSlug": "flow_abc",
                  "actionType": "STARTED_STEP",
                  "stepId": "step-1",
                  "data": "{\"key\": \"value\"}",
                  "createdAt": "2024-01-01T00:00:00Z"
                }
              ]
            }
          }
        ]
      },
      "$state": {
        "currentStepId": "step_abc",
        "currentStepIndex": 1,
        "completed": true,
        "started": true,
        "skipped": true,
        "visible": true,
        "lastActionAt": "2024-09-01T00:00:00.000Z",
        "flowResponses": [
          {
            "flowSlug": "flow_abc",
            "actionType": "STARTED_STEP",
            "stepId": "step-1",
            "data": "{\"key\": \"value\"}",
            "createdAt": "2024-01-01T00:00:00Z"
          }
        ]
      },
      "version": 1
    }
  ],
  "ineligibleFlows": [
    "<string>"
  ]
}

API

Flows

Users

Groups

Update User Flow State

Authorizations

Body

Response