Introduction

The Grant API enables you to apply a visibility tag to a design in order to provide a filter for visibility. This is typically used for creating custom permissions in the Embed use case, and as a flexible tagging system, permissions can be as simple or complex as needed.

By default, a standard user will be able to see all of the designs that they have created themselves. However, many Foursquare Targeting partners have requirements for more granular, complex permissions on designs. For example, perhaps a Foursquare Targeting partner wants all users from the same company to see any design created by a user from that same company. This can be done using visibility tags in conjunction with server side API calls made by a Admin level user. See Management APIs for a more complete example of how to use visibility tags to retrieve lists of designs filtered by visibility tag.

Example workflow:

• User A is a member of “Sample, Inc.”
• User A creates a new Proximity Design, “Design XYZ” and saves it.
• Foursquare Targeting Partner uses the Grant API call to assign “Design XYZ” the visibility tag “sample_inc”
• When User B comes to the Foursquare Targeting Partner UI, partner makes a server side call to list all designs associated with the tag “sample_inc”, and lists these as valid designs for User B to interact with.

Note: Maintaining the mapping between which users should be associated with which visibility tags is dependent on the Foursquare Targeting partner system. Foursquare Targeting does not maintain mappings of users to visibility tags.

Endpoint

https://api.targeting.foursquare.com/geopulse/designs/(design id)/grant

Syntax

• This endpoint only accepts POST requests.
• Replace (design Id) with the id of the build for which you are requesting activation.
• Request Parameters should be URL encoded and POSTed as the body of the request.
• The Content-Type for this request should be set to application/x-www-form-urlencoded.

Example

POST /geopulse/designs/8d7d2d1f-7ee8-428e-9d27-23d7cfbf6c5d/grant HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 67

visibility=pepsi%2Cdiet_coke&KEY=my_api_key

Request Parameters

Notes on the visibility parameter:

• visibility takes one or more tags which will be appled to the design. When accessing the deployment list API using the corresponding visibility tag, only designs with matching tags will be returned.
• When tags are appled to visibility, the results will be OR’d. In otherwords, if a design has tags A and B applied to it, and you attempt to list all designs with tags B or C, the design will be returned as a match.
• Pre-existing tags will be overwritten.
• visibility tags will be sluggified.
  • Acceptable tags may use the characters a-z, A-Z, 0-9, and the underscore (‘_’) character. No whitespace is allowed.
  • Unacceptable characters will be transformed as follows: punctuation characters will be ignored, unicode letters transformed to the closest Arabic match, white space trimmed from the ends or replaced by underscore otherwise.
• visibility tags are case sensitive.

Response Parameters

Example Response

{
  "version": 4,
  "status": "ok"
}