Contacts - Flownally API Docs

post/contacts

Create contact#

Creates a customer profile that can be matched to messages and events.

Authorization

Scheme

bearerAuth

Required scopes

contact:create

Allowed roles

owner
admin
agent

Create a contact in the workspace.

Request body

Send a application/json body. The body is required for this operation.

Optional attributes

Name
name
Type
string
Description
Optional request attribute.
Name
phone
Type
string
Description
Phone number in E.164 format (e.g., +48123456789)
Name
customFields
Type
object
Description
Optional request attribute.

Responses

Name
201
Type
application/json
Description
Contact created
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/contacts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Anna Kowalska",
  "phone": "+48123456789",
  "customFields": {
    "lifecycleStage": "lead",
    "preferredStore": "Krakow"
  }
}'

Response

201application/json

{
  "id": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
  "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
  "name": "Anna Kowalska",
  "createdAt": "2026-04-30T09:20:00Z",
  "updatedAt": "2026-04-30T10:10:00Z",
  "conversations": [
    {
      "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
      "channel": "whatsapp",
      "metadata": {
        "phoneNumber": "+48123456789"
      }
    }
  ],
  "tagIds": [
    "tag_01HV8Y9R3Q4J6A7M8N9P0Q2S4"
  ],
  "customFields": {
    "lifecycleStage": "customer",
    "preferredStore": "Krakow"
  },
  "archivedAt": null
}

post/contacts/search

Search contacts#

Returns contact summaries matching one canonical conjunction of filter conditions.

Authorization

Scheme

bearerAuth

Required scopes

contact:list

Allowed roles

owner
admin
agent

Search contacts in the caller's contact scope.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
filter
Type
ContactFilter
Description
Required request attribute.

Optional attributes

Name
sort
Type
ContactSort
Description
Optional request attribute.
Name
limit
Type
integer
Description
Optional request attribute.
Name
cursor
Type
string
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Contacts matching the filter
Name
default
Type
application/json
Description
Error

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/contacts/search" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  },
  "sort": {
    "field": "createdAt",
    "direction": "asc"
  },
  "limit": 0,
  "cursor": "string"
}'

Response

200application/json

{
  "items": [
    {
      "id": "string",
      "name": "order_ready",
      "email": "name@example.com",
      "phone": "+48123456789",
      "tags": [
        {
          "id": "string",
          "name": "order_ready"
        }
      ],
      "channels": [
        "whatsapp"
      ],
      "hasConversations": true,
      "createdAt": "2026-04-27T00:00:00.000Z",
      "updatedAt": "2026-04-27T00:00:00.000Z",
      "archivedAt": "2026-04-27T00:00:00.000Z"
    }
  ],
  "nextCursor": "string",
  "hasMore": true
}

get/contacts/count

Count contacts#

Returns the tenant's contact count for a navigation/dashboard badge. This is independent of any list filters; the archived query parameter selects which bucket to count.

Authorization

Scheme

bearerAuth

Required scopes

contact:list

Allowed roles

owner
admin
agent

Count contacts in the caller's contact scope.

Optional parameters

Name
archived
Type
query boolean
Description
Omit or pass false for non-archived count; pass true for archived-bucket count.

Responses

Name
200
Type
application/json
Description
Contact count
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -G "https://api.flownally.com/v1/contacts/count" \
  -H "Authorization: Bearer {token}" \
  -d archived="{archived}"

Response

200application/json

{
  "totalSize": 0
}

get/contacts/{id}

Get contact by ID#

Returns one customer profile with conversations, tags, custom fields, and archive state.

Authorization

Scheme

bearerAuth

Required scopes

contact:read

Allowed roles

owner
admin
agent

Read a contact in the caller's contact scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
200
Type
application/json
Description
Contact found
Name
404
Type
application/json
Description
Contact not found
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/contacts/{id}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "id": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
  "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
  "name": "Anna Kowalska",
  "createdAt": "2026-04-30T09:20:00Z",
  "updatedAt": "2026-04-30T10:10:00Z",
  "conversations": [
    {
      "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
      "channel": "whatsapp",
      "metadata": {
        "phoneNumber": "+48123456789"
      }
    }
  ],
  "tagIds": [
    "tag_01HV8Y9R3Q4J6A7M8N9P0Q2S4"
  ],
  "customFields": {
    "lifecycleStage": "customer",
    "preferredStore": "Krakow"
  },
  "archivedAt": null
}

patch/contacts/{id}

Update contact#

Updates mutable contact fields. Fields omitted from the body are left unchanged.

Authorization

Scheme

bearerAuth

Required scopes

contact:update

Allowed roles

owner
admin
agent

Update a contact in the caller's contact scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Optional attributes

Name
name
Type
string
Description
New contact name. Omit the field to leave the name unchanged.

Responses

Name
200
Type
application/json
Description
Contact updated
Name
404
Type
application/json
Description
Contact not found
Name
default
Type
application/json
Description
Error

Related schemas

Request

PATCHRequest

curl -X PATCH "https://api.flownally.com/v1/contacts/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_ready"
}'

Response

200application/json

{
  "id": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
  "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
  "name": "Anna Kowalska",
  "createdAt": "2026-04-30T09:20:00Z",
  "updatedAt": "2026-04-30T10:10:00Z",
  "conversations": [
    {
      "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
      "channel": "whatsapp",
      "metadata": {
        "phoneNumber": "+48123456789"
      }
    }
  ],
  "tagIds": [
    "tag_01HV8Y9R3Q4J6A7M8N9P0Q2S4"
  ],
  "customFields": {
    "lifecycleStage": "customer",
    "preferredStore": "Krakow"
  },
  "archivedAt": null
}

delete/contacts/{id}

Delete contact#

Soft deletes a contact. Use archive when you only want to hide the contact from active lists.

Authorization

Scheme

bearerAuth

Required scopes

contact:delete

Allowed roles

owner
admin
agent

Delete a contact in the caller's contact scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Contact deleted
Name
404
Type
application/json
Description
Contact not found
Name
default
Type
application/json
Description
Error

Related schemas

Request

DELETERequest

curl -X DELETE "https://api.flownally.com/v1/contacts/{id}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Contact deleted

post/contacts/import

Import contacts from CSV#

Uploads a CSV file and starts a background contact import. Poll the returned import ID to review completion counts and row-level errors.

Authorization

Scheme

bearerAuth

Required scopes

contact:create

Allowed roles

owner
admin
agent

Import contacts into the workspace.

Request body

Send a multipart/form-data body. The body is required for this operation.

Responses

Name
202
Type
application/json
Description
Import initiated
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTUpload file

curl -X POST "https://api.flownally.com/v1/contacts/import" \
  -H "Authorization: Bearer {token}" \
  -F "file=@invoice.pdf"

Response

202application/json

{
  "importId": "import_01HV8Z92S0R7M4E5P6Q8T1A2B3"
}

get/contacts/imports/{id}

Get import status#

Returns progress and row-level failures for a contact import.

Authorization

Scheme

bearerAuth

Required scopes

contact:list

Allowed roles

owner
admin
agent

Read contact import status.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
200
Type
application/json
Description
Import status
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/contacts/imports/{id}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "importId": "import_01HV8Z92S0R7M4E5P6Q8T1A2B3",
  "status": "completed",
  "totalRows": 1200,
  "successCount": 1194,
  "failedCount": 6,
  "errors": [
    {
      "row": 17,
      "column": "phone",
      "message": "must be a valid E.164 phone number"
    }
  ]
}

post/contacts/{id}/archive

Archive contact#

Hides a contact from active lists without deleting its history.

Authorization

Scheme

bearerAuth

Required scopes

contact:update

Allowed roles

owner
admin
agent

Archive a contact in the caller's contact scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Contact archived
Name
404
Type
application/json
Description
Contact not found
Name
409
Type
application/json
Description
Contact is already archived
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/contacts/{id}/archive" \
  -H "Authorization: Bearer {token}"

Response

204

204 Contact archived

post/contacts/{id}/unarchive

Unarchive contact#

Restores an archived contact to active lists.

Authorization

Scheme

bearerAuth

Required scopes

contact:update

Allowed roles

owner
admin
agent

Unarchive a contact in the caller's contact scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Contact unarchived
Name
404
Type
application/json
Description
Contact not found
Name
409
Type
application/json
Description
Contact is not archived
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/contacts/{id}/unarchive" \
  -H "Authorization: Bearer {token}"

Response

204

204 Contact unarchived

put/contacts/{contactId}/custom-fields/{customFieldId}

Set contact field value#

Sets or clears one custom field value on a contact. Send an empty string to clear the value while keeping the field definition available for future use.

Authorization

Scheme

bearerAuth

Required scopes

contact:update

Allowed roles

owner
admin
agent

Set a custom field value on a contact in scope.

Required parameters

Name
contactId
Type
path string
Description
Required parameter.
Name
customFieldId
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
value
Type
string
Description
Field value for this contact.

Responses

Name
204
Description
Contact field value set
Name
default
Type
application/json
Description
Error

Related schemas

Request

PUTRequest

curl -X PUT "https://api.flownally.com/v1/contacts/{contactId}/custom-fields/{customFieldId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "Krakow"
}'

Response

204

204 Contact field value set

post/contacts/{contactId}/tags/{tagId}

Add tag to contact#

Adds a label to the contact for segmentation, routing, or reporting.

Authorization

Scheme

bearerAuth

Required scopes

contact:update

Allowed roles

owner
admin
agent

Tag a contact in scope.

Required parameters

Name
contactId
Type
path string
Description
Required parameter.
Name
tagId
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Tag added
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/contacts/{contactId}/tags/{tagId}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Tag added

delete/contacts/{contactId}/tags/{tagId}

Remove tag from contact#

Removes a label from the contact.

Authorization

Scheme

bearerAuth

Required scopes

contact:update

Allowed roles

owner
admin
agent

Remove a tag from a contact in scope.

Required parameters

Name
contactId
Type
path string
Description
Required parameter.
Name
tagId
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Tag removed
Name
default
Type
application/json
Description
Error

Related schemas

Request

DELETERequest

curl -X DELETE "https://api.flownally.com/v1/contacts/{contactId}/tags/{tagId}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Tag removed

get/segments

List saved contact segments#

Returns tenant-scoped saved contact filters without evaluating member counts.

Authorization

Scheme

bearerAuth

Required scopes

segment:list

Allowed roles

owner
admin
agent

List saved contact segments.

Optional parameters

Name
limit
Type
query integer
Description
Optional parameter.
Name
cursor
Type
query string
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
Saved segments
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -G "https://api.flownally.com/v1/segments" \
  -H "Authorization: Bearer {token}" \
  -d limit="{limit}" \
  -d cursor="{cursor}"

Response

200application/json

{
  "items": [
    {
      "id": "string",
      "name": "order_ready",
      "description": "string",
      "createdBy": "string",
      "filter": {
        "match": "all",
        "conditions": [
          {
            "type": "searchText",
            "text": "string"
          }
        ]
      },
      "revision": 0,
      "createdAt": "2026-04-27T00:00:00.000Z",
      "updatedAt": "2026-04-27T00:00:00.000Z"
    }
  ],
  "nextCursor": "string",
  "hasMore": true
}

post/segments

Create a saved contact segment#

Authorization

Scheme

bearerAuth

Required scopes

segment:create

Allowed roles

owner
admin

Create a saved contact segment.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Required request attribute.
Name
filter
Type
ContactFilter
Description
Required request attribute.

Optional attributes

Name
description
Type
string
Description
Optional request attribute.

Responses

Name
201
Type
application/json
Description
Segment created
Name
default
Type
application/json
Description
Error

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/segments" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_ready",
  "description": "string",
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  }
}'

Response

201application/json

{
  "id": "string",
  "name": "order_ready",
  "description": "string",
  "createdBy": "string",
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  },
  "revision": 0,
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

get/segments/{segmentId}

Get a saved contact segment#

Authorization

Scheme

bearerAuth

Required scopes

segment:read

Allowed roles

owner
admin
agent

Read a saved contact segment.

Responses

Name
200
Type
application/json
Description
Saved segment
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/segments/{segmentId}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "id": "string",
  "name": "order_ready",
  "description": "string",
  "createdBy": "string",
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  },
  "revision": 0,
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

patch/segments/{segmentId}

Update a saved contact segment#

Replaces any supplied filter atomically. The If-Match header must contain the current segment ETag.

Authorization

Scheme

bearerAuth

Required scopes

segment:update

Allowed roles

owner
admin

Update a saved contact segment.

Request body

Send a application/json body. The body is required for this operation.

Optional attributes

Name
name
Type
string
Description
Optional request attribute.
Name
description
Type
string
Description
Optional request attribute.
Name
filter
Type
ContactFilter
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Segment updated
Name
412
Type
application/json
Description
The supplied ETag is stale.
Name
428
Type
application/json
Description
If-Match is required.
Name
default
Type
application/json
Description
Error

Request

PATCHRequest

curl -X PATCH "https://api.flownally.com/v1/segments/{segmentId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_ready",
  "description": "string",
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  }
}'

Response

200application/json

{
  "id": "string",
  "name": "order_ready",
  "description": "string",
  "createdBy": "string",
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  },
  "revision": 0,
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

delete/segments/{segmentId}

Delete a saved contact segment#

Authorization

Scheme

bearerAuth

Required scopes

segment:delete

Allowed roles

owner
admin

Delete a saved contact segment.

Responses

Name
204
Description
Segment deleted
Name
412
Type
application/json
Description
The supplied ETag is stale.
Name
428
Type
application/json
Description
If-Match is required.
Name
default
Type
application/json
Description
Error

Related schemas

Request

DELETERequest

curl -X DELETE "https://api.flownally.com/v1/segments/{segmentId}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Segment deleted

post/segments/{segmentId}/contacts/search

Search contacts matching a saved segment#

Applies the current saved definition and any temporary filters using AND semantics.

Authorization

Scheme

bearerAuth

Required scopes

contact:list
segment:read

Allowed roles

owner
admin
agent

Search contacts matching a saved segment in the caller's contact scope.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
filter
Type
ContactFilter
Description
Required request attribute.

Optional attributes

Name
sort
Type
ContactSort
Description
Optional request attribute.
Name
limit
Type
integer
Description
Optional request attribute.
Name
cursor
Type
string
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Current segment members
Name
default
Type
application/json
Description
Error

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/segments/{segmentId}/contacts/search" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "searchText",
        "text": "string"
      }
    ]
  },
  "sort": {
    "field": "createdAt",
    "direction": "asc"
  },
  "limit": 0,
  "cursor": "string"
}'

Response

200application/json

{
  "items": [
    {
      "id": "string",
      "name": "order_ready",
      "email": "name@example.com",
      "phone": "+48123456789",
      "tags": [
        {
          "id": "string",
          "name": "order_ready"
        }
      ],
      "channels": [
        "whatsapp"
      ],
      "hasConversations": true,
      "createdAt": "2026-04-27T00:00:00.000Z",
      "updatedAt": "2026-04-27T00:00:00.000Z",
      "archivedAt": "2026-04-27T00:00:00.000Z"
    }
  ],
  "nextCursor": "string",
  "hasMore": true
}

get/campaigns

List campaigns#

Authorization

Scheme

bearerAuth

Required scopes

campaign:list

Allowed roles

owner
admin
agent

List campaigns in the workspace.

Optional parameters

Name
status
Type
query CampaignStatus
Description
Optional parameter.
Name
limit
Type
query integer
Description
Optional parameter.
Name
cursor
Type
query string
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
Campaigns
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -G "https://api.flownally.com/v1/campaigns" \
  -H "Authorization: Bearer {token}" \
  -d status="{status}" \
  -d limit="{limit}" \
  -d cursor="{cursor}"

Response

200application/json

{
  "items": [
    {
      "id": "string",
      "name": "order_ready",
      "status": "draft",
      "segmentId": "string",
      "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
      "channel": "string",
      "content": {
        "type": "text",
        "text": {
          "body": "Hi Anna, your order is ready for pickup."
        }
      },
      "revision": 0,
      "scheduledAt": "2026-04-27T00:00:00.000Z",
      "evaluatedAt": "2026-04-27T00:00:00.000Z",
      "sentAt": "2026-04-27T00:00:00.000Z",
      "audienceCount": 0,
      "dispatchError": "string",
      "createdAt": "2026-04-27T00:00:00.000Z",
      "updatedAt": "2026-04-27T00:00:00.000Z"
    }
  ],
  "nextCursor": "string",
  "hasMore": true
}

post/campaigns

Create a draft campaign#

Authorization

Scheme

bearerAuth

Required scopes

campaign:create

Allowed roles

owner
admin

Create a draft campaign.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Required request attribute.

Responses

Name
201
Type
application/json
Description
Campaign created
Name
default
Type
application/json
Description
Error

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/campaigns" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_ready"
}'

Response

201application/json

{
  "id": "string",
  "name": "order_ready",
  "status": "draft",
  "segmentId": "string",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "channel": "string",
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  },
  "revision": 0,
  "scheduledAt": "2026-04-27T00:00:00.000Z",
  "evaluatedAt": "2026-04-27T00:00:00.000Z",
  "sentAt": "2026-04-27T00:00:00.000Z",
  "audienceCount": 0,
  "dispatchError": "string",
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

get/campaigns/{campaignId}

Get a campaign#

Authorization

Scheme

bearerAuth

Required scopes

campaign:read

Allowed roles

owner
admin
agent

Read a campaign.

Responses

Name
200
Type
application/json
Description
Campaign
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/campaigns/{campaignId}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "id": "string",
  "name": "order_ready",
  "status": "draft",
  "segmentId": "string",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "channel": "string",
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  },
  "revision": 0,
  "scheduledAt": "2026-04-27T00:00:00.000Z",
  "evaluatedAt": "2026-04-27T00:00:00.000Z",
  "sentAt": "2026-04-27T00:00:00.000Z",
  "audienceCount": 0,
  "dispatchError": "string",
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

patch/campaigns/{campaignId}

Update a draft campaign#

Only draft campaigns are editable. If-Match is optional; when supplied, it must contain the current campaign ETag.

Authorization

Scheme

bearerAuth

Required scopes

campaign:update

Allowed roles

owner
admin

Update a draft campaign.

Request body

Send a application/json body. The body is required for this operation.

Optional attributes

Name
name
Type
string
Description
Optional request attribute.
Name
segmentId
Type
string
Description
Optional request attribute.
Name
inboxId
Type
string
Description
Optional request attribute.
Name
content
Type
OutboundMessageContent
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Campaign updated
Name
412
Type
application/json
Description
The supplied ETag is stale.
Name
default
Type
application/json
Description
Error

Request

PATCH/campaigns/{campaignId}

curl -X PATCH "https://api.flownally.com/v1/campaigns/{campaignId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_ready",
  "segmentId": "string",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  }
}'

Response

200application/json

{
  "id": "string",
  "name": "order_ready",
  "status": "draft",
  "segmentId": "string",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "channel": "string",
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  },
  "revision": 0,
  "scheduledAt": "2026-04-27T00:00:00.000Z",
  "evaluatedAt": "2026-04-27T00:00:00.000Z",
  "sentAt": "2026-04-27T00:00:00.000Z",
  "audienceCount": 0,
  "dispatchError": "string",
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

post/campaigns/{campaignId}/schedule

Schedule a draft campaign#

Set sendAt to now to dispatch immediately, or supply an RFC 3339 timestamp. If-Match is optional.

Authorization

Scheme

bearerAuth

Required scopes

campaign:schedule

Allowed roles

owner
admin

Schedule a draft campaign.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
sendAt
Type
string
Description
The literal now or an RFC 3339 timestamp.

Responses

Name
200
Type
application/json
Description
Campaign scheduled
Name
412
Type
application/json
Description
The supplied ETag is stale.
Name
default
Type
application/json
Description
Error

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/campaigns/{campaignId}/schedule" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "sendAt": "2026-04-27T00:00:00.000Z"
}'

Response

200application/json

{
  "id": "string",
  "name": "order_ready",
  "status": "draft",
  "segmentId": "string",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "channel": "string",
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  },
  "revision": 0,
  "scheduledAt": "2026-04-27T00:00:00.000Z",
  "evaluatedAt": "2026-04-27T00:00:00.000Z",
  "sentAt": "2026-04-27T00:00:00.000Z",
  "audienceCount": 0,
  "dispatchError": "string",
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

post/campaigns/{campaignId}/unschedule

Return a scheduled campaign to draft#

If-Match is optional. A campaign cannot be unscheduled after dispatch starts.

Authorization

Scheme

bearerAuth

Required scopes

campaign:schedule

Allowed roles

owner
admin

Return a scheduled campaign to draft.

Responses

Name
200
Type
application/json
Description
Campaign returned to draft
Name
412
Type
application/json
Description
The supplied ETag is stale.
Name
default
Type
application/json
Description
Error

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/campaigns/{campaignId}/unschedule" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "id": "string",
  "name": "order_ready",
  "status": "draft",
  "segmentId": "string",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "channel": "string",
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  },
  "revision": 0,
  "scheduledAt": "2026-04-27T00:00:00.000Z",
  "evaluatedAt": "2026-04-27T00:00:00.000Z",
  "sentAt": "2026-04-27T00:00:00.000Z",
  "audienceCount": 0,
  "dispatchError": "string",
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}

get/campaigns/{campaignId}/recipients

List campaign recipients#

Authorization

Scheme

bearerAuth

Required scopes

campaign:recipients
contact:list

Allowed roles

owner
admin

List campaign recipients.

Optional parameters

Name
status
Type
query CampaignRecipientStatus
Description
Optional parameter.
Name
limit
Type
query integer
Description
Optional parameter.
Name
cursor
Type
query string
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
Campaign recipients
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -G "https://api.flownally.com/v1/campaigns/{campaignId}/recipients" \
  -H "Authorization: Bearer {token}" \
  -d status="{status}" \
  -d limit="{limit}" \
  -d cursor="{cursor}"

Response

200application/json

{
  "items": [
    {
      "id": "string",
      "contactId": "ctc_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
      "status": "pending",
      "messageId": "string",
      "sentAt": "2026-04-27T00:00:00.000Z",
      "deliveredAt": "2026-04-27T00:00:00.000Z",
      "readAt": "2026-04-27T00:00:00.000Z",
      "failedAt": "2026-04-27T00:00:00.000Z",
      "failureCode": "string"
    }
  ],
  "nextCursor": "string",
  "hasMore": true
}

get/campaigns/{campaignId}/analytics

Get campaign delivery analytics#

Authorization

Scheme

bearerAuth

Required scopes

campaign:read

Allowed roles

owner
admin
agent

Read campaign delivery analytics.

Responses

Name
200
Type
application/json
Description
Campaign analytics
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/campaigns/{campaignId}/analytics" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "audienceCount": 0,
  "pending": 0,
  "unknown": 0,
  "sent": 0,
  "delivered": 0,
  "read": 0,
  "failed": 0,
  "sentStage": 0,
  "deliveredStage": 0,
  "readStage": 0,
  "failedStage": 0,
  "deliveryRate": 0,
  "readRate": 0
}

get/tags

List tags#

Returns the labels available for organizing contacts.

Authorization

Scheme

bearerAuth

Required scopes

tag:list

Allowed roles

owner
admin
agent

List contact tags in the workspace.

Responses

Name
200
Type
application/json
Description
List of tags
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/tags" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "tags": [
    {
      "id": "string",
      "name": "order_ready",
      "createdAt": "2026-04-27T00:00:00.000Z",
      "createdBy": "string",
      "labeledCount": 0
    }
  ]
}

post/tags

Create tag#

Creates a label that can be attached to contacts.

Authorization

Scheme

bearerAuth

Required scopes

tag:create

Allowed roles

owner
admin
agent

Create a contact tag in the workspace.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Required request attribute.

Responses

Name
201
Type
application/json
Description
Tag created
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/tags" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP"
}'

Response

201application/json

{
  "id": "string",
  "name": "order_ready",
  "createdAt": "2026-04-27T00:00:00.000Z",
  "createdBy": "string",
  "labeledCount": 0
}

delete/tags/{id}

Delete tag#

Authorization

Scheme

bearerAuth

Required scopes

segment:update
tag:delete

Allowed roles

owner
admin

Delete a contact tag and update any referencing segments.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Tag deleted
Name
default
Type
application/json
Description
Error

Related schemas

Request

DELETERequest

curl -X DELETE "https://api.flownally.com/v1/tags/{id}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Tag deleted

get/contacts/custom-fields

List contact field definitions#

Returns the reusable custom fields that can store structured customer context on contacts, such as lifecycle stage, preferred store, or renewal date.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:list

Allowed roles

owner
admin
agent

List contact field definitions.

Responses

Name
200
Type
application/json
Description
Contact field definitions
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/contacts/custom-fields" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "customFields": [
    {
      "id": "cf_lifecycle_stage",
      "name": "Lifecycle stage",
      "type": "text",
      "createdAt": "2026-04-30T09:00:00Z",
      "createdBy": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
      "predefined": false,
      "entityType": "contact"
    }
  ]
}

post/contacts/custom-fields

Create contact field definition#

Creates a reusable custom field for storing customer context on contacts.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:create

Allowed roles

owner
admin
agent

Create a contact field definition.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Human-readable label for the field.
Name
type
Type
enum
Description
Value type accepted by the field.Allowed: text, date

Responses

Name
201
Type
application/json
Description
Contact field definition created
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTLifecycle stage

curl -X POST "https://api.flownally.com/v1/contacts/custom-fields" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Lifecycle stage",
  "type": "text"
}'

Response

201application/json

{
  "id": "cf_lifecycle_stage",
  "name": "Lifecycle stage",
  "type": "text",
  "createdAt": "2026-04-30T09:00:00Z",
  "createdBy": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "predefined": false,
  "entityType": "contact"
}

patch/contacts/custom-fields/{id}

Update contact field definition#

Renames a contact field definition.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:update

Allowed roles

owner
admin
agent

Update a contact field definition.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Human-readable label for the field.

Responses

Name
200
Type
application/json
Description
Contact field definition updated
Name
default
Type
application/json
Description
Error

Related schemas

Request

PATCHRequest

curl -X PATCH "https://api.flownally.com/v1/contacts/custom-fields/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Region"
}'

Response

200application/json

{
  "id": "cf_region",
  "name": "Region",
  "type": "text",
  "createdAt": "2026-04-30T09:00:00Z",
  "createdBy": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "predefined": false,
  "entityType": "property"
}

delete/contacts/custom-fields/{id}

Delete contact field definition#

Deletes a contact field definition that is no longer needed.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:delete
segment:update

Allowed roles

owner
admin

Delete a contact field definition and update any referencing segments.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Contact field definition deleted
Name
default
Type
application/json
Description
Error

Related schemas

Request

DELETERequest

curl -X DELETE "https://api.flownally.com/v1/contacts/custom-fields/{id}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Contact field definition deleted

get/properties/custom-fields

List property field definitions#

Returns the reusable custom fields that can store structured context on property records, such as region, tier, or renewal date.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:list

Allowed roles

owner
admin
agent

List property field definitions.

Responses

Name
200
Type
application/json
Description
Property field definitions
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/properties/custom-fields" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "customFields": [
    {
      "id": "cf_region",
      "name": "Region",
      "type": "text",
      "createdAt": "2026-04-30T09:00:00Z",
      "createdBy": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
      "predefined": false,
      "entityType": "property"
    }
  ]
}

post/properties/custom-fields

Create property field definition#

Creates a reusable custom field for storing context on property records.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:create

Allowed roles

owner
admin
agent

Create a property field definition.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Human-readable label for the field.
Name
type
Type
enum
Description
Value type accepted by the field.Allowed: text, date

Responses

Name
201
Type
application/json
Description
Property field definition created
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRegion

curl -X POST "https://api.flownally.com/v1/properties/custom-fields" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Region",
  "type": "text"
}'

Response

201application/json

{
  "id": "cf_region",
  "name": "Region",
  "type": "text",
  "createdAt": "2026-04-30T09:00:00Z",
  "createdBy": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "predefined": false,
  "entityType": "property"
}

patch/properties/custom-fields/{id}

Update property field definition#

Renames a property field definition.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:update

Allowed roles

owner
admin
agent

Update a property field definition.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
name
Type
string
Description
Human-readable label for the field.

Responses

Name
200
Type
application/json
Description
Property field definition updated
Name
default
Type
application/json
Description
Error

Related schemas

Request

PATCHRequest

curl -X PATCH "https://api.flownally.com/v1/properties/custom-fields/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Region"
}'

Response

200application/json

{
  "id": "cf_region",
  "name": "Region",
  "type": "text",
  "createdAt": "2026-04-30T09:00:00Z",
  "createdBy": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "predefined": false,
  "entityType": "property"
}

delete/properties/custom-fields/{id}

Delete property field definition#

Deletes a property field definition that is no longer needed.

Authorization

Scheme

bearerAuth

Required scopes

custom_field:delete

Allowed roles

owner
admin
agent

Delete a property field definition.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
204
Description
Property field definition deleted
Name
default
Type
application/json
Description
Error

Related schemas

Request

DELETERequest

curl -X DELETE "https://api.flownally.com/v1/properties/custom-fields/{id}" \
  -H "Authorization: Bearer {token}"

Response

204

204 Property field definition deleted