Contacts

LLM

Keep customer profiles, tags, custom fields, and imports in sync.

24 generated endpoints in this resource group.

get/contacts

Get contacts#

Returns customer profiles with identities, tags, and custom fields. Use filters to find the segment you want to message, enroll in journeys, or keep in sync.

Authorization

Scheme

bearerAuth

Required scopes

contact:list

Allowed roles

owner
admin
agent

List contacts in the caller's contact scope.

Optional parameters

Name
pageToken
Type
query string
Description
Opaque token from the previous response's `nextPageToken`.
Name
pageSize
Type
query integer
Description
Optional parameter.
Name
search
Type
query string
Description
Case-insensitive substring search across name, cf_email, cf_phone, identity phone, and tag name.
Name
customFields
Type
query object
Description
Filter by custom field values (AND logic)
Name
tagIds
Type
query array<string>
Description
Include contacts tagged with any of the listed tag IDs (OR semantics).
Name
channels
Type
query array<enum>
Description
Include contacts that have an identity on any of the listed channels (OR semantics).
Name
archived
Type
query boolean
Description
Tri-state filter. Omit to exclude archived contacts (default), set to true to return only archived contacts, or false to return only non-archived.
Name
createdAfter
Type
query string
Description
Inclusive lower bound on createdAt (RFC3339).
Name
createdBefore
Type
query string
Description
Exclusive upper bound on createdAt (RFC3339).
Name
orderBy
Type
query enum
Description
Optional parameter.
Name
orderDirection
Type
query enum
Description
Optional parameter.

Responses

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

Related schemas

Request

GETRequest

curl -G "https://api.flownally.com/v1/contacts" \
  -H "Authorization: Bearer {token}" \
  -d pageToken="{pageToken}" \
  -d pageSize="{pageSize}" \
  -d search="{search}" \
  -d customFields="{customFields}" \
  -d tagIds="{tagIds}" \
  -d channels="{channels}" \
  -d archived="{archived}" \
  -d createdAfter="{createdAfter}" \
  -d createdBefore="{createdBefore}" \
  -d orderBy="{orderBy}" \
  -d orderDirection="{orderDirection}"

Response

200application/json

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

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",
  "identities": [
    {
      "id": "idn_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
      "channel": "whatsapp",
      "metadata": {
        "phoneNumber": "+48123456789"
      }
    }
  ],
  "tagIds": [
    "tag_01HV8Y9R3Q4J6A7M8N9P0Q2S4"
  ],
  "customFields": {
    "lifecycleStage": "customer",
    "preferredStore": "Krakow"
  },
  "archivedAt": null
}

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 identities, 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",
  "identities": [
    {
      "id": "idn_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",
  "identities": [
    {
      "id": "idn_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/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

tag:delete

Allowed roles

owner
admin
agent

Delete a contact tag in the workspace.

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 or changes its value type.

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.
Name
type
Type
enum
Description
Value type accepted by the field.Allowed: text, date

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",
  "type": "text"
}'

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

Allowed roles

owner
admin
agent

Delete a contact field definition.

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 or changes its value type.

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.
Name
type
Type
enum
Description
Value type accepted by the field.Allowed: text, date

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",
  "type": "text"
}'

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