Flock to Unlock API

In a Flock to Unlock, the teeming masses strive to unlock goodies by tweeting or posting enough to reach specific volume targets (e.g., display a behind-the-scenes photo if we get 1000 tweets w/the #flock hashtag). The Flock API provides information about the state of a Flock to Unlock, describing percentage progress towards its target thresholds and, if achieved, the thresholds' unlocked payloads.

Note: Flocks to Unlock thresholds and payloads must be configured by a Spredfast respresentative.

Resource URL

http://api.massrelevance.com/flock/:account/:flock_name.:format

Example URL: http://api.massrelevance.com/flock/massreldemo/example-flock.json

Example Request

When making a flock request...

$ curl http://api.massrelevance.com/flock/massreldemo/example-flock.json

...the response is a JSON object representing the state of the Flock to Unlock. If an error occurs then the response will be empty (whitespace).

{
    "thresholds": [{
        "payload": {
            "custom": "payload",
            "items": [0, 1, 2, 3]
        },
        "name": "",
        "pct": 100,
        "description": ""
    }],
    "kind": "flock-to-unlock",
    "full_name": "massreldemo/example-flock",
    "name": "example-flock",
    "description": ""
}

Thresholds

The thresholds array within the response is where the the unlocked information is contained. A flock to unlock endpoint may have more than one unlock threshold. We use this when there is more than one payoff.

The items of the threshold are ordered. The order can be specified. We usually order thresholds such that thresholds that unlock first are earlier in the array. The order is preserved with each request.

The two important threshold properties are payload and pct

Payload

A payload can be specified with any data that can be serialized to JSON. If the threshold condition has not been met, then the payload will NOT BE included. When the threshold condition has been met then pct === 100

Pct

pct is an integer value where 0 >= pct <= 100. When pct === 100, then the threshold condition has been met and there will be a payload included in the threshold (if one has been defined).

Each threshold's pct is independent* of all other thresholds within the array. e.g. if there are 10 thresholds, each one will calculate its own pct depending on its unlock condition. The only time when all thresholds are pct are 0 is when there are 0 tweets. This should not be an issue but it is worth noting.

*= pct acts a little bit differently if the flock endpoint is artificial. i.e. the thresholds unlock at some predetermined time instead of organically through number of tweets. In this case each condition is dependent on the when the previous threshold unlocks.

Other Properties

A name and a description can be defined per threshold. We usually do not use these fields.

Annotated JSON Response

Example scenario: if there are 10k tweets using a particular hashtag, there will be a video displayed, but there will be a new photo for each 1k tweets tweeted up to that point. In this case, there would be 10 threshold items in the thresholds array.

{
  //...
  "thresholds": [

    // picture 1:
    // unlocked. `payload` is given
    {
      "payload": {
        "thing": "that is awesome"
      },
      "pct": 100,
      "name": "",
      "description": ""
    }

    // picture 2:
    // not yet unlocked so `payload` is null
    {
      "pct": 62
      // + custom threshold name and description
    }

    //...7 other similar thresholds

    // final unlock (video):
    // not yet unlocked so `payload` is null
    {
      "pct": 12
      // + custom threshold name and description
    }

  ]
}