The Segment Queries API is used to retrieve IDs of devices that meet certain criteria. The IDs can be internal Crowd Connected IDs or an alias provided by the app developer. This can be done as a batch or as a callback. Segment Queries should be used when you need to know individual IDs (for example, to send them a push message).
Batch
To get all the devices that match the given segment use the following API call:
POST https://api.crowdconnected.com/prod/external/query
Headers:
Auth: "YOUR_API_KEY"
Body:
{ "filters":[ { "type":"IN_BETWEEN", "regionIds":[ "8377b3f9-7308-44de-94dd-cf912b050375" ], "times":[{ "from":1632314700000, "to":1632318300000 }], "minDwell": 60 # Unit is seconds
"visitCount": 4 # Optional number of times a device has to have visited
"timeBetweenVisits": 300 # Optional number of seconds between visits } ] }
Response:
{ "queryID": "da03ebab-8f31-4f38-8b0a-33b4199badec" }
You must then poll the following API
GET https://api.crowdconnected.com/prod/external/da03ebab-8f31-4f38-8b0a-33b4199badec
Headers:
Auth: "YOUR_API_KEY"
Optional query parameters
If you have device aliases configured then you can optionally add to return these as part of the results set. Note that if a device alias has not been configured, then just its device Id will be returned.
GET https://api.crowdconnected.com/prod/external/da03ebab-8f31-4f38-8b0a-33b4199badec?aliasKey=onesignal_user_id
Response
The API will return either an in progress message or the device Ids and any relevant aliases.
200 (In Progress)
{ "status": "QUERY_RUNNING" }
200 (Complete)
{ "deviceIds":[ { "deviceId":"37483892-70ef-4305-963f-db72d361a0b5" }, { "alias":"297a55f0-3d5d-4ed8-85a6-34737f100640", "deviceId":"3115e705-f719-4b31-9cd2-3f1a2d388f10" } ] }
Callback
Callbacks can be setup so that an API call is made to another system when a device meets the segment.
POST - Segment
Firstly you must configure the segment using the following API
POST https://api.crowdconnected.com/prod/segment
Headers:
Auth: "YOUR_API_KEY"
Body:
{
"trigger": {
"from": 1638144000000
"to": 1638230340000
"type":
"regionIds": [
"041e43d3-6c93-46f1-9ab0-7bce066cf254", "e9056fda-2f97-4a0f-baed-76531ba61b42"
]
},
"filters": [
{
"type": "IN_BETWEEN"
"index": 0,
"regionIds": [
"041e43d3-6c93-46f1-9ab0-7bce066cf254", "e9056fda-2f97-4a0f-baed-76531ba61b42"
],
"times": [{
"from": 1638143940000,
"to": 1638144000000
}],
"visits": 1,
"dwell": 6000
}
]
}
Response:
{
"segmentID: "e11f4e91-82a4-4a9a-8816-ba8097fd1731"
}
It is then possible for you to DELETE, PUT or GET for more information on these methods see here.
POST - Callback
With the segment ID returned back from the POST API you must now create the callback. To do that you must use the following
POST https://api.crowdconnected.com/prod/external/callback
Headers:
Auth: "YOUR_API_KEY"
Body:
{
"segmentID": "e11f4e91-82a4-4a9a-8816-ba8097fd1731"
"callbackURL": "YOUR_CALLBACK_ENDPOINT",
"frequency": "ONCE_PER_PERIOD" | "ONCE_ONLY" | "EVERY_TIME",
"aliasKey": "ALIAS_NAME"
}
Response
{
"callbackID": "a32aa93f-c7d6-4ec8-b629-2a5c6f8055e0"
}
It is then possible to DELETE, GET, or PUT to your callback
Delete
DELETE https://api.crowdconnected.com/prod/external/callback/a32aa93f-c7d6-4ec8-b629-2a5c6f8055e0
Headers:
Auth: "YOUR_API_KEY"
--------------------------------------------------------------------------------------------------------------------
GET
GET https://api.crowdconnected.com/prod/external/callback/a32aa93f-c7d6-4ec8-b629-2a5c6f8055e0
Headers:
Auth: "YOUR_API_KEY"
Response
{
"callbackID": "a32aa93f-c7d6-4ec8-b629-2a5c6f8055e0"
"callbackURL": "YOUR_CALLBACK_ENDPOINT",
"segmentID": "e11f4e91-82a4-4a9a-8816-ba8097fd1731"
"frequency": "ONCE_PER_PERIOD" | "ONCE_ONLY" | "EVERY_TIME",
"aliasKey": "ALIAS_NAME"
}
--------------------------------------------------------------------------------------------------------------------
PUT
PUT https://api.crowdconnected.com/prod/external/callback/a32aa93f-c7d6-4ec8-b629-2a5c6f8055e0
Headers:
Auth: "YOUR_API_KEY"
Body:
{
"trigger": {
"from": 1638144000000
"to": 1638230340000
"type":
"regionIds": [
"041e43d3-6c93-46f1-9ab0-7bce066cf254"
]
},
"filters": [
{
"type": "IN_BETWEEN"
"index": 0,
"regionIds": [
"041e43d3-6c93-46f1-9ab0-7bce066cf254"
],
"times": [{
"from": 1638143940000,
"to": 1638144000000
}],
"visits": 1,
"dwell": 6000
}
]
}