# 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](https://docs.foursquare.com/developer/reference/management) 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

```undefined
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

HTTP

```http
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

| Parameter Name | Description | Datatype | Example |
| --- | --- | --- | --- |
| visibility | Set of sluggified tags that you are assigning visibility for this design for. | comma-delimited array of Strings | `visibility=pepsi,diet_coke` |
| \*KEY | Your API Key. Note the _KEY_ parameter name must be declared in all caps. | String | `KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c` |

Notes on the _visibility_ parameter:

- _visibility_ takes one or more _tags_ that will be applied to the design. When accessing the [deployment list API](https://docs.foursquare.com/developer/docs/management#section-list-deployments) using the corresponding _visibility_ tag, only designs with matching tags will be returned.
- When tags are applied to visibility, the results will be OR’d. In other words, 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

| Parameter Name | Description | Datatype | Example |
| --- | --- | --- | --- |
| **version** | The version of the API response. | Number | `4` |
| **status** | The status of the API response. | String | `"OK"` |

### Example Response

JSON

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