Create target groups

post https://{host}/v3/targetGroups

This API is used to create a target group.

A target group is an entity under which individual targets can be created. The targets are defined under the target group.

A target group is essential for creating a target, even when defining a single target. The target group serves as a container in the backend system. When creating a target through the user interface, you may not explicitly create a target group; however, the system automatically assigns the target to a backend group.

You can also use the same API to define targets and periods under the target group.

👍
Note
For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

Prerequisites

Authentication: Basic/OAuth authentication
Default access group

Resource information


URI	v3/targetGroups
HTTP method	POST
Pagination	NA
Rate limit	NA
Batch support	NA

API endpoint example

https://eu.api.capillarytech.com/v3/targetGroups

curl --location 'https://eu.api.capillarytech.com/v3/targetGroups' \
--header 'Content-Type: application/json' \
--header 'Cookie: _cfuvid=aidEostKQWmdskBHmh1pchvz2wSoA1O27JghNUFOpHw-1728306311172-0.0.1.1-604800000; _cfuvid=2ieM2eqBqFdNAAdfQMYR0zNvTd6WWmQxVVyU.OyFiEw-1728475108732-0.0.1.1-604800000' \
--header 'Authorization: Basic dGpfY2FwaWxsYXJ5OjVjMT5' \
--data '{
  "active": true,
  "description": "UAT target group number thirty nine",
  "name": "uatTargetGroup39",
  "trackingType": "DEFAULT",
  "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
  "totalPeriods": 1,
  "frequencyType": "DAILY",
  "frequency": 1,
  "recurringCycles": 1,
  "preferredTillId": 751552970000,
  "userCreated": false,
  "periods": [
    {
      "active": true,
      "description": "",
      "endDate": "2025-06-11T23:59:59.999Z",
      "periodStatus": "RUNNING",
      "refCode": "Cycle_1",
      "startDate": "2025-06-11T00:00:00.000Z"
    },
    {
      "active": true,
      "description": "",
      "endDate": "2025-05-11T23:59:59.999Z",
      "periodStatus": "NOT_STARTED",
      "refCode": "Cycle_2",
      "startDate": "2025-05-11T00:00:00.000Z"
    }
  ],
  "targets": [
    {
      "active": true,
      "description": "",
      "expression": true,
      "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
      "filters": [],
      "name": "uat_target_group_39",
      "targetEntity": "EVENT",
      "targetType": "COUNT",
      "extendedFieldInfo": {
        "name": "points",
        "aggregateFunction": "SUM"
      },
      "defaultValues": [
        {
          "defaultValue": "1.00"
        },
        {
          "defaultValue": "1.00"
        }
      ]
    }
  ]
}'

Request body parameters

Parameter Name	Data Type	Description
active	Boolean	Indicates if target tracking is active.
description	String	Brief description of the target group.
name*	String	The name identifier for the target group. The character limit for the name is 200 characters.
preferredTillId	Number	Identifier for the preferred POS till.
trackingType*	String	The type of tracking the milestone is created for. Supported values: `DEFAULT`: Track a single target `UNIFIED` :Track multiple targets `STREAK`: Track multiple targets as a streak. `CAPPING`: Track the number of points a user has got over a period, so that capping can be applied. Refer to the documentation on milestones, unified targets, streaksand capping for more information.
targetEvaluationType*	String	The evaluation strategy for the targets. Supported values: `FIXED_CALENDAR_WINDOW`, `CYCLIC_WINDOW`, `PERIOD_AGNOSTIC_WINDOW`
totalPeriods*	Number	The total number of periods over which the tracking is evaluated.
frequencyType*	Enum	The frequency of each cycle in which the user has to achieve the target value. Supported values: `MONTHLY, QUARTERLY`, `HALF_YEARLY`, `YEARLY`, `WEEKLY`, `DAILY`, `CUSTOM`.
frequency*	Number	The frequency count, based on the `frequencyType`.
recurringCycles*	Number	The number of cycles for which the tracking recurs.
userCreated	Boolean	If set to true, a user-created target group is created. A user-created target is a promotion that rewards customers for achieving goals they set themselves. By default the value is set to false and a regular target group is created.
leaderboardEnabled	Boolean	If enabled, a leaderboard enabled target group is created.
aggregateWindow *	ENUM	Contains information related to the aggregate window. An aggregate window is a defined time period during which you can track an extended field or behavioral event.
windowType *	ENUM	The type of window period (MIN or MAX). MIN: This function identifies the smallest value within a given time frame. For example, if you're tracking daily steps, the MIN would show you the least number of steps taken in that period. MAX: This function finds the largest value within that same time frame. Continuing with the step count example, the MAX would reveal the highest number of steps taken during the period.
windowTimeUnit *	ENUM	The timeframe for which the window will be active. Currently, DAY is supported.
windowValue	String	The time units for which the window will be active. Currently, one time unit is supported.
periods	Object	Details on target period creation, updates, and time-frame.
active	Boolean	Indicates if the period is active.
description	String	A brief description of the period.
endDate	Date Time	The end date and time of the period in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
periodStatus	String	Indicates if the cycle of the Milestone is running or upcoming. Supported values: `RUNNING`, `UPCOMING`, `NOT_STARTED`
refCode	String	A reference code for the period.
startDate	Date Time	The start date and time of the period in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
targets	Object	An array of target objects, each outlining a target within the tracking.
active	Boolean	Indicates if the target is active.
description	String	A brief description of the target.
expression	Boolean	Indicates if the target has an expression for evaluation.
expressionJson	String	A JSON expression that specifies the conditions required to achieve the target.
filters	Object	Details on the scope filters active on the target.
entityType	Enum	The entity to which the specified expressions related to the target will be applied. For example: The user has to make a purchase of shoes from ABC store. Here, purchase of shoes is the expression and the entity is ABC store. Supported values: `STORE`, `ZONE`, `CONCEPT`.
entityIds	Array	IDs of the entities to which the is filter applied on.
name	String	The name identifier for the target. The character limit for the target group name is 200 characters.
targetEntity	Enum	The KPI on which the target is tracked. For the transactional KPIs, the supported value for this are `TRANSACTION` and `LINEITEM`. For the Behavioural or EMF events, the supported value is `EVENT`. For the tracking based on rewards such as points, the supported value is `REWARDS`. Refer to creating target groups based on behavioural event, EMF event and alternate currencies for more details.
eventName	String	The name of the event that triggers the target.
targetType	Enum	Target type on which the target is set. Supported values: `QUANTITY, SALES, GROSS_SALES`, `REGULAR_POINTS, PROMOTIONAL_POINTS`, `ALL_POINTS` For information based on configuring target based on behavioural event (COUNT, VISIT, and SUM) and EMF event (COUNT and VISIT), refer to target based on behavioural event and target based on EMF event documentation.
defaultValues	Object	Details of the default values for the target.
defaultValue	Integer	Default value for the target.
extendedFieldInfo	Object	Details on extended field information for the target group.
name	String	Specific custom data field you want to perform the aggregation on. To create a new custom field, refer to the documentation on creating a new custom field.
aggregateFunction	String	The specific type of calculation that will be performed. This allows you to create a single, summary metric from a set of individual data points, which the system can then use to evaluate progress towards a goal. Supported values: `COUNT` : Counts the number of times the field specified in name appears in the data. `SUM`: Calculate the arithmetic sum of all the numeric values for the field specified in name

Request body

{
  "active": true,
  "description": "UAT target group number thirty nine",
  "name": "uatTargetGroup821",
  "trackingType": "DEFAULT",
  "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
  "totalPeriods": 1,
  "frequencyType": "DAILY",
  "frequency": 1,
  "recurringCycles": 1,
  "preferredTillId": 751552970000,
  "userCreated": false,
  "periods": [
    {
      "active": true,
      "description": "",
      "endDate": "2025-06-11T23:59:59.999Z",
      "periodStatus": "RUNNING",
      "refCode": "Cycle_1",
      "startDate": "2025-06-11T00:00:00.000Z"
    },
    {
      "active": true,
      "description": "",
      "endDate": "2025-05-11T23:59:59.999Z",
      "periodStatus": "NOT_STARTED",
      "refCode": "Cycle_2",
      "startDate": "2025-05-11T00:00:00.000Z"
    }
  ],
  "targets": [
    {
      "active": true,
      "description": "",
      "expression": true,
      "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
      "filters": [],
      "name": "uat_target_group_821",
      "targetEntity": "EVENT",
      "targetType": "COUNT",
      "extendedFieldInfo": {
        "name": "points",
        "aggregateFunction": "SUM"
      },
      "defaultValues": [
        {
          "defaultValue": "1.00"
        },
        {
          "defaultValue": "1.00"
        }
      ]
    }
  ]
}

Response parameters

Field	Data Type	Description
id	Integer	Unique ID of the target group
name	String	Unique name of the target group.
active	Boolean	Indicates if target tracking is active.
preferredTillId	Number	Identifier for the preferred POS till.
trackingType	Enum	The type of tracking the milestone is created for. Supported values: `DEFAULT`: Track a single target `UNIFIED` :Track multiple targets `STREAK`: Track multiple targets as a streak. `CAPPING`: Track the number of points a user has got over a period, so that capping can be applied.
frequency	Number	Frequency count, based on the `frequencyType`.
recurringCycles	Number	Number of cycles for which the tracking recurs.
periods	Object	Details on target creation, updates, and time-frame.
-id	Integer	The unique ID of the target period.
-attribution	Object	Details on the creation and update details of the target period.
-- createdOn	String	Date the target period was created in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
--lastUpdatedOn	String	Date the target period was last updated in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
--lastUpdatedBy	Object	Details on updates to the target period.
---id	Integer	Unique ID of the user who last modified the target period.
---code	String	Code of the user who last modified the target period.
---description	String	Description of the user who last modified the target period.
---name	String	Name of the user who last modified the target period.
---type	String	Type of user who last modified the target period.
-startDate	String	Start date of the target group, in `YYYY-MM-DD` format.
-endDate	String	End date of the target group, in `YYYY-MM-DD` format.
-refCode	Integer	Reference code of the target period.
-periodStatus	String	Current status of the target period. Supported values `NOT_STARTED`, `LIVE` and `ENDED`.
-targetGroupId	Integer	Unique ID of the target group.
-description	String	Description of the target group.
-active	Boolean	Current active status of the target period. If true, the target is currently active, else the target is inactive.
totalPeriods	Integer	Total number of periods for the target group.
description	String	Description of the target period.
targetEvaluationType	ENUM	Evaluation strategy for the target.
recurringCycles	Integer	Number of cycles for which the tracking recurs.
targetCycleStartDate	String	Start date of the target cycle in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
targetCycleEndDate	String	End date of the target cycle in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
frequencyType	String	The frequency of each cycle in which the user has to achieve the target value.
trackingType	Enum	The type of tracking the milestone is created for.
targets	Object	Details on creation of the target.
-id	Boolean	Unique ID of the target.
-attribution	Object	Details on the creation and update details of the target.
-- createdOn	String	Date the target was created in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
-- lastUpdatedOn	String	Date the target was last updated in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format.
-- lastUpdatedBy	Object	Details on updates to the target.
--- id	Integer	Unique ID of the user who last modified the target.
--- code	Integer	Code of the user who last modified the target.
-- description	String	Description of the user who last modified the target.
--- name	String	Name of the user who last modified the target.
--- type	String	Type of user who last modified the target.
-- createdBy	Object	Details on creation of the target.
--- id	Integer	Unique ID of the user who created the target .
--- code	Integer	Code of the user who created the target.
--- description	String	Description of the user who created the target.
--- name	String	Name of the user who created the target.
--- type	String	Type of user who created the target.
---name	String	Unique name for the target.
--targetType	String	The type of target Supported values: `ALL`: Tracks points that a customer earns across a loyalty program and from a loyalty promotion. `REGULAR`: Track the points that a customer earns across a loyalty program. Points earned from promotions are excluded. `PROMOTION`: Tracks the points that a customer earns from a loyalty promotion.
--targetEntity	Enum	The KPI on which the target is tracked. For the transactional KPIs, the supported value for this are `TRANSACTION` and `LINEITEM`. For the Behavioural or EMF events, the supported value is `EVENT`. For the tracking based on rewards such as points, the supported value is `REWARDS`.
--eventName	String	Name of the event that triggers the target.
--targetGroupId	Integer	Unique ID of the target group associated with the target.
--description	String	Description of the target.
--active	Boolean	Current active status of the target. If true, the target is currently active, else the target is inactive.
-- expression	Boolean	Indicates if the target has an expression for evaluation.
-- expressionJson	String	A JSON expression that specifies the conditions required to achieve the target.
-- filters	Object	Details on the scope filters active on the target.
-- enrolmentMethod	Enum	The method of enrolment for the target. Supported values: `TRANSACTION`, `IMPORT`.
-- defaultValues	Object	Details on the default values for the target.
--- defaultValue	Float	A default value used in the target evaluation.
-- targetPeriodDefaultValuesMap	Object	Details on the default values for the target period.
-- extendedFieldInfo	Object	Details on extended field information for the target group.
leaderboardEnabled	Boolean	Indicates if the leaderboard feature is enabled.
userCreated	Boolean	Indicates if the target is a user-created target.
errors	null or Object	Contains error details if any occurred during the API request.
warnings	null or Object	Contains warning details if any occurred during the API request.

{
    "data": {
        "id": 2295,
        "name": "uatTargetGroup821",
        "active": true,
        "preferredTillId": 751552970000,
        "periods": [
            {
                "id": 21196,
                "attribution": {
                    "createdOn": "2025-06-17T10:56:47.000+0000",
                    "lastUpdatedOn": "2025-06-17T10:56:47.000+0000",
                    "lastUpdatedBy": {
                        "id": 75155297,
                        "code": "tj_capillary",
                        "description": "",
                        "name": "tj_capillary",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75155297,
                        "code": "tj_capillary",
                        "description": "",
                        "name": "tj_capillary",
                        "type": "TILL"
                    }
                },
                "startDate": "2025-06-11",
                "endDate": "2025-06-11",
                "refCode": "Cycle_1",
                "periodStatus": "ENDED",
                "targetGroupId": 2295,
                "description": "",
                "active": true
            },
            {
                "id": 21197,
                "attribution": {
                    "createdOn": "2025-06-17T10:56:47.000+0000",
                    "lastUpdatedOn": "2025-06-17T10:56:47.000+0000",
                    "lastUpdatedBy": {
                        "id": 75155297,
                        "code": "tj_capillary",
                        "description": "",
                        "name": "tj_capillary",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75155297,
                        "code": "tj_capillary",
                        "description": "",
                        "name": "tj_capillary",
                        "type": "TILL"
                    }
                },
                "startDate": "2025-05-11",
                "endDate": "2025-05-11",
                "refCode": "Cycle_2",
                "periodStatus": "ENDED",
                "targetGroupId": 2295,
                "description": "",
                "active": true
            }
        ],
        "totalPeriods": 1,
        "description": "UAT target group number thirty nine",
        "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
        "recurringCycles": 1,
        "frequency": 1,
        "targetCycleStartDate": "2025-05-11T00:00:00.000Z",
        "targetCycleEndDate": "2025-06-11T23:59:59.000Z",
        "frequencyType": "DAILY",
        "trackingType": "DEFAULT",
        "targets": [
            {
                "id": 2440,
                "attribution": {
                    "createdOn": "2025-06-17T10:56:47.474+0000",
                    "lastUpdatedOn": "2025-06-17T10:56:47.474+0000",
                    "lastUpdatedBy": {
                        "id": 75155297,
                        "code": "tj_capillary",
                        "description": "",
                        "name": "tj_capillary",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75155297,
                        "code": "tj_capillary",
                        "description": "",
                        "name": "tj_capillary",
                        "type": "TILL"
                    }
                },
                "name": "uat_target_group_821",
                "emfRuleSetId": 126411030,
                "targetType": "COUNT",
                "targetEntity": "EVENT",
                "eventName": "TransactionAdd",
                "targetGroupId": 2295,
                "description": "",
                "active": true,
                "expression": "true",
                "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
                "filters": [],
                "enrolmentMethod": "IMPORT",
                "defaultValues": [
                    {
                        "id": 23552,
                        "periodId": 21196,
                        "defaultValue": 1.000
                    },
                    {
                        "id": 23553,
                        "periodId": 21197,
                        "defaultValue": 1.000
                    }
                ],
                "targetPeriodDefaultValuesMap": {
                    "21196": {
                        "id": 23552,
                        "periodId": 21196,
                        "defaultValue": 1.000
                    },
                    "21197": {
                        "id": 23553,
                        "periodId": 21197,
                        "defaultValue": 1.000
                    }
                },
                "extendedFieldInfo": {
                    "name": "points",
                    "aggregateFunction": "SUM"
                }
            }
        ],
        "leaderboardEnabled": false,
        "userCreated": false
    },
    "errors": null,
    "warnings": null
}

API error codes

Code	Description
310069	Target group name already exists
300004	Invalid input, check all values and ensure they are correct.
310133	Leaderboard is not enabled for the org
310132	Target evaluation type not supported for leaderboard, currently only `FIXED_CALENDER_WINDOW` is supported
310008	Length of Target rule name cannot exceed 200

Language

Credentials

Basic

base64

URL

Click Try It! to start a request and see the response here!