Market Segments

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

The market segment model

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

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the market segment.

  • Name
    name
    Type
    string
    Description

    Name of the market segment.

  • Name
    criteria
    Type
    string
    Description

    Criteria used to define the market segment.

  • Name
    description
    Type
    string
    Description

    Description of the market segment.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the market segment was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    Timestamp of when the market segment was last updated.

GET/v1/market-segments

List all market segments

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

Optional attributes

  • Name
    limit
    Type
    integer
    Description

    Limit the number of market segment records returned.

  • Name
    name
    Type
    string
    Description

    Only show records with the specified name.

  • Name
    criteria
    Type
    string
    Description

    Only show records with the specified criteria.

Request

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

Response

{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "name": "Tech Enthusiasts",
      "criteria": "Customers interested in technology products",
      "description": "Segment of customers who frequently purchase technology products.",
      "created_at": 705103200,
      "updated_at": 705103200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}
POST/v1/market-segments

Create a market segment

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

Required attributes

  • Name
    name
    Type
    string
    Description

    Name of the market segment.

  • Name
    criteria
    Type
    string
    Description

    Criteria used to define the market segment.

  • Name
    description
    Type
    string
    Description

    Description of the market segment.

Request

POST
/v1/market-segments'
curl https://api.finx.ai/v1/market-segments \
  -H "Authorization: Bearer {token}" \
  -d 'name'="Tech Enthusiasts" \
  -d 'criteria'="Customers interested in technology products" \
  -d 'description'="Segment of customers who frequently purchase technology products."

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "Tech Enthusiasts",
  "criteria": "Customers interested in technology products",
  "description": "Segment of customers who frequently purchase technology products.",
  "created_at": 705103200,
  "updated_at": 705103200
}
GET/v1/market-segments/:id

Retrieve a market segment

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

Request

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

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "Tech Enthusiasts",
  "criteria": "Customers interested in technology products",
  "description": "Segment of customers who frequently purchase technology products.",
  "created_at": 705103200,
  "updated_at": 705103200
}
PUT/v1/market-segments/:id

Update a market segment

This endpoint allows you to perform an update on a market 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 market segment.

  • Name
    criteria
    Type
    string
    Description

    Updated criteria used to define the market segment.

  • Name
    description
    Type
    string
    Description

    Updated description of the market segment.

Request

PUT
/v1/market-segments/xgQQXg3hrtjh7AvZ
curl -X PUT https://api.finx.ai/v1/market-segments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'criteria'="Customers interested in tech and gaming products"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "Tech Enthusiasts",
  "criteria": "Customers interested in tech and gaming products",
  "description": "Segment of customers who frequently purchase technology and gaming products.",
  "created_at": 705103200,
  "updated_at": 705103200
}
DELETE/v1/market-segments/:id

Delete a market segment

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

Request

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

Was this page helpful?