Flows

A flow is a reusable reminder schedule. It defines which messages to send and when, relative to a record's dates, for example a message when an event is created, another 7 days before the event date, and another on the day. Events and payments each reference a flow, and when a record is processed its flow's steps become the scheduled reminder messages sent to the client's contacts.

This page assumes the shared API Conventions for pagination, filtering, lifecycle actions, and references. All endpoints use your region's base URL and a Bearer token.

Endpoints

Method	Path	Description
GET	/v1/flows	List flows
GET	/v1/flows/total	Count flows matching filters
GET	/v1/flows/{uuid}	Get a single flow (by UUID or flow_reference)
POST	/v1/flows	Create a flow, optionally with its message steps
PATCH	/v1/flows/{uuid}	Update a flow
POST	/v1/flows/sync/{uuid}	Reschedule this flow's events and payments
POST	/v1/flows/{uuid}/sync	Reschedule only this flow's events
POST	/v1/flows/{uuid}/sync/payments	Reschedule only this flow's payments
POST	/v1/flows/{uuid}/validate	Validate this flow's event messages
PUT	/v1/flows/{uuid}/archive	Archive a flow
PUT	/v1/flows/{uuid}/restore	Restore an archived or deleted flow
DELETE	/v1/flows/{uuid}	Delete a flow (soft delete)

The Flow Object

Field	Type	Description
uuid	string	Unique identifier, generated when the flow is created.
name	string	Display name. Defaults to New Flow.
flow_reference	string	Your identifier for the flow. Defaults to a slug of the name.
status	string	Agency-defined status.
type	string	The record type the flow applies to, such as event or payment.
types	string	Additional types associated with the flow.
default	integer	1 when this flow is the agency's default flow.
simulate	integer	1 when the flow runs in simulate mode.
virtual	integer	1 when the flow is for virtual events.
phone	string	Sender phone number for the flow's messages.
email	string	Sender email for the flow's messages.
portal	string	UUID of the portal linked to the flow.
geolocation	string	Geolocation linked to the flow.
locations	array	Locations the flow applies to.
created_by	string	Email or UUID of the creator.
created_at	string	Creation timestamp, UTC.
updated_at	string	Last update timestamp, UTC.
archived_at	string	Set when the flow is archived, otherwise null.
deleted_at	string	Set when the flow is deleted, otherwise null.

A single-flow response also includes messages (the flow's message steps) and portal_link (the linked portal's URL).

Message Steps

A flow's messages are its steps: each one is a message to schedule, along with the rule for when to send it. A step is stored as a flow message and has these fields:

Field	Description
trigger	What schedules the message. Date triggers include event_date, payment_due_date, and payment_issue_date; status triggers include event_status, payment_status, case_status, and event_appearance; a creation trigger such as event_created sends when the record is created. The trigger value is stored as provided; the platform's flow builder defines the full set of supported triggers.
templates	An object of message body templates, keyed by language, for example {"en": "Your hearing is on [EventDate]."}. Merge tags resolve when the message is scheduled.
subjects	An object of email subjects, keyed the same way as templates.
difference	For a date trigger, how many units away from the date to send.
unit	The unit for difference, such as days or hours.
operation	- to send before the trigger date, + to send after.
status	For a status trigger, the status value that fires the step.
send_time	Time of day to send, for date-based steps.
notify	Whether the step notifies.
delay_business	Restrict scheduling to business days.
delay_min	Minimum delay before sending.
file_url	A media URL, which sends the step as MMS.

For example, a step with trigger: event_date, difference: 7, unit: days, operation: - sends 7 days before the event date.

Create a Flow

POST /v1/flows

You can create the flow on its own, or include a messages array to create its steps in the same request.

Request:

curl -X POST "$BASE_URL/v1/flows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hearing Reminders",
    "type": "event",
    "messages": [
      {
        "trigger": "event_created",
        "templates": {"en": "You have a hearing on [EventDate]. Reply YES to confirm."}
      },
      {
        "trigger": "event_date",
        "difference": 7,
        "unit": "days",
        "operation": "-",
        "templates": {"en": "Reminder: your hearing is on [EventDate] at [EventTime]."}
      }
    ]
  }'

Response (201): the flow, including the messages that were created.

Create Behavior

• name: defaults to New Flow. flow_reference: defaults to a slug of the name.
• Uniqueness: a flow whose name or flow_reference matches an existing active flow returns 409 with Flow name must be unique. Sending an empty name returns the same 409, so provide a name (or omit it to accept the New Flow default).
• Message steps: each entry in messages needs a trigger and a non-empty templates object; entries missing either are skipped.
• simulate: set to a truthy value to create the flow in simulate mode.

List Flows

GET /v1/flows

Response (200): a JSON array of flow objects.

Query Parameters

Parameter	Description
search	Partial match on the flow name.
name	Exact match on the flow name.
flow_reference	Exact match on the flow reference.
type	Exact match on type.
status	Exact match on status.
portal	Filter by linked portal.
phone	Filter by sender phone.
email	Filter by sender email.
default	Set to 1 to return only the default flow.
virtual	Set to 1 to return only virtual flows.
simulate	Set to 1 to return only simulate-mode flows.
created_by	Filter by the creator.

Pagination and shaping (limit, skip, sort, sortDirection, fields) follow the shared conventions.

Get a Flow

GET /v1/flows/{uuid}

The path value accepts a flow UUID or a flow_reference. Returns the flow with its messages and portal_link. Returns 404 with a message of Flow {uuid} not found when no flow matches.

Update a Flow

PATCH /v1/flows/{uuid}

Send only the fields you want to change. Setting default: true marks this flow as the agency's default flow. Returns 404 with Flow {uuid} not found when no flow matches.

curl -X PATCH "$BASE_URL/v1/flows/{flow_uuid}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default": true}'

flow_reference is set at create time and cannot be changed through PATCH by a standard API client, so choose it when you create the flow. To change a flow's steps, manage its flow messages through the /v1/flow_messages endpoints rather than PATCH /v1/flows.

Sync a Flow

Editing a flow does not by itself change reminders already scheduled from it. To apply a flow's current steps to the records that use it, sync the flow:

POST /v1/flows/sync/{uuid}

Reschedules the reminder messages for both the events and the payments that reference the flow. Returns 202 with {"message": "Syncing Flow Messages"}.

Two narrower variants are available:

• POST /v1/flows/{uuid}/sync reschedules only the flow's events. Returns 202 with {"message": "Syncing Events"}. By default it targets upcoming events; passing past=y switches it to past and current events instead, and max_days={n} limits how far ahead to reach.
• POST /v1/flows/{uuid}/sync/payments reschedules only the flow's payments. Returns 202 with {"message": "Syncing Payments"}.

Validate a Flow

POST /v1/flows/{uuid}/validate

Queues a validation pass over the flow's event messages, useful for checking a flow's steps produce the messages you expect.

Response (202):

{"message": "Validating event messages"}

Archive, Restore, and Delete

PUT /v1/flows/{uuid}/archive
PUT /v1/flows/{uuid}/restore
DELETE /v1/flows/{uuid}

These follow the standard lifecycle conventions: archive and delete remove the flow from default lists, and restore brings it back.

FAQs

What is a flow, and how does it relate to events and payments?

A flow is a reminder schedule. An event or payment references a flow, and when the record is processed, the flow's steps become the scheduled reminder messages. Set an event's or payment's flow on create, or rely on the agency's default flow.

How do I define when each reminder goes out?

Each message step has a trigger and, for date triggers, a difference, unit, and operation. For example trigger: event_date, difference: 3, unit: days, operation: - sends 3 days before the event date. Status triggers such as event_status fire when the record reaches the step's status.

I edited a flow. Why did existing reminders not change?

Editing a flow does not retroactively change reminders already scheduled. Run POST /v1/flows/sync/{uuid} to reschedule the events and payments that use the flow with the flow's current steps.

How do I set the default flow?

PATCH /v1/flows/{uuid} with {"default": true} marks the flow as the agency's default. New events and payments created with no flow specified use the default flow.

Why did creating a flow return a 409?

The name or flow_reference matches an existing active flow, or the name was empty. Flow names and references must be unique within the agency, and a name is required; choose a different, non-empty name or update the existing flow.

How do I add or change a flow's message steps?

Include a messages array when creating the flow, or manage steps individually through the /v1/flow_messages endpoints. After changing steps, sync the flow so records using it pick up the change.

Related Documentation

• API Conventions: shared listing, filtering, and lifecycle behavior
• Events: records that a flow schedules reminders for
• Payments: balances that a flow schedules reminders for
• Merge Tags: dynamic content in step templates
• Error Handling: status codes and error responses