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
        }
    ]
}