Customer Segments

Customer segments are essential for categorizing your customers based on various criteria such as behavior, preferences, and demographics. On this page, we’ll dive into the different customer segment endpoints you can use to manage customer segments programmatically. We'll look at how to query, create, update, and delete customer segments.

The customer segment model

The customer segment model contains all the information related to a customer segment, including the segment name, criteria, and description.

Properties

Name
id
Type
string
Description
Unique identifier for the customer segment.
Name
name
Type
string
Description
Name of the customer segment.
Name
criteria
Type
string
Description
Criteria used to define the customer segment.
Name
description
Type
string
Description
Description of the customer segment.
Name
created_at
Type
timestamp
Description
Timestamp of when the customer segment was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the customer segment was last updated.

GET/v1/customer-segments

List all customer segments

This endpoint allows you to retrieve a paginated list of all your customer segments. By default, a maximum of ten segments are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of customer segments returned.
Name
name
Type
string
Description
Only show segments with the specified name.
Name
criteria
Type
string
Description
Only show segments with the specified criteria.

Request

GET

/v1/customer-segments

curl -G https://api.finx.ai/v1/customer-segments \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "name": "High Spend Customers",
      "criteria": "Customers who spend more than $1000 per month",
      "description": "Segment of customers who have high monthly spending.",
      "created_at": 705103200,
      "updated_at": 705103200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

POST/v1/customer-segments

Create a customer segment

This endpoint allows you to add a new customer segment. You need to provide the segment name, criteria, and description to create a customer segment.

Required attributes

Name
name
Type
string
Description
Name of the customer segment.
Name
criteria
Type
string
Description
Criteria used to define the customer segment.
Name
description
Type
string
Description
Description of the customer segment.

Request

POST

/v1/customer-segments'

curl https://api.finx.ai/v1/customer-segments \
  -H "Authorization: Bearer {token}" \
  -d 'name'="High Spend Customers" \
  -d 'criteria'="Customers who spend more than $1000 per month" \
  -d 'description'="Segment of customers who have high monthly spending."

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "High Spend Customers",
  "criteria": "Customers who spend more than $1000 per month",
  "description": "Segment of customers who have high monthly spending.",
  "created_at": 705103200,
  "updated_at": 705103200
}

GET/v1/customer-segments/:id

Retrieve a customer segment

This endpoint allows you to retrieve a customer segment by providing the segment id. Refer to the list at the top of this page to see which properties are included with customer segment objects.

Request

GET

/v1/customer-segments/xgQQXg3hrtjh7AvZ

curl https://api.finx.ai/v1/customer-segments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "High Spend Customers",
  "criteria": "Customers who spend more than $1000 per month",
  "description": "Segment of customers who have high monthly spending.",
  "created_at": 705103200,
  "updated_at": 705103200
}

PUT/v1/customer-segments/:id

Update a customer segment

This endpoint allows you to perform an update on a customer segment. Examples of updates are changing the segment name, updating the criteria, or modifying the description.

Optional attributes

Name
name
Type
string
Description
Updated name of the customer segment.
Name
criteria
Type
string
Description
Updated criteria used to define the customer segment.
Name
description
Type
string
Description
Updated description of the customer segment.

Request

PUT

/v1/customer-segments/xgQQXg3hrtjh7AvZ

curl -X PUT https://api.finx.ai/v1/customer-segments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'criteria'="Customers who spend more than $500 per month"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "High Spend Customers",
  "criteria": "Customers who spend more than $500 per month",
  "description": "Segment of customers who have high monthly spending.",
  "created_at": 705103200,
  "updated_at": 705103200
}

DELETE/v1/customer-segments/:id

Delete a customer segment

This endpoint allows you to delete your customer segments in Fin X. Note: This will permanently delete the segment and all its data — ensure this is the desired action before proceeding.

Request

DELETE

/v1/customer-segments/xgQQXg3hrtjh7AvZ

curl -X DELETE https://api.finx.ai/v1/customer-segments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"