Segment Queries
Introduction to Segment Queries
The Segment Queries API is used to retrieve IDs of devices that meet certain criteria. The IDs can be internal Colocator IDs or an alias provided by the app developer. This can be done as a batch or as a callback. Segments must first be created via the Segment Filters API. Segment Queries should be used when you need to know individual IDs (for example, to send them a push message). If you are doing analysis on the number of devices that match a segment Analytics Queries should be used instead.
Batch
To get all the devices that match the given segment use the following API call:
POST /v2/segmentQuery/advanced/batch/{segmentId}
Additionally an alias can be specified. This allows the ID list returned to be an alias specified by the app instead of an internal Colocator ID:
-d alias=YOUR_ALIAS_KEY
Callback
Callbacks can be setup so that an API call is made to another system when a device meets the segment.
GET, PUT, POST and DELETE methods are available for /v2/segmentQuery/callbacks
Callback properties
| Name | Type | Description |
|---|---|---|
| id | String | The callback ID. This is not required (and will be ignored) on creation. It is used when updating callbacks. |
| name | String | The name of the callback |
| callbackURL | String | The URL to POST to when a device meets the segment |
| trajectoryFilterId | String | The ID of the segment in use |
| callbackStrategy | String | The callback can be made ONCE The first time the segment is met for each device ALL Every time the segment is met for each device SENDSPER Limited to a number of sends per period for each device |
| sendsPer | Number | Used with the SENDSPER callback strategy. The number of sends per the defined period |
| period | String | Used with the SENDSPER callback strategy. The period that the sendsPer applies |
| activationTime | String | The time in milliseconds since epoch that the callback should activate |
| deactivationTime | String | The time in milliseconds since epoch that the callback should deactivate |
| state | String | ACTIVE, INACTIVE or PAUSED. The callback will automatically change between ACTIVE and INACTIVE as the times stated. Changing the callback from ACTIVE to INACTIVE while it is in it’s active period will be ineffective (this is also true the other way around). A callback can be set to PAUSED while ACTIVE and ACTIVE while PAUSED |
| alias | String | The key of the alias to return instead of the internal Colocator ID |
Callbacks will return with a JSON body with one property, id. This will be an internal Colocator ID or an alias if defined in the callback.
There may be limits applied to how many callbacks can be active concurrently.