Introduction

The Marketing Solutions APIs are a suite of APIs that enable you to manage the building and deployment of Proximity and Audience designs.

Lifecycle

The basic lifecycle of a Proximity/Audience design is as follows:

1. A user creates and saves a design using Foursquare Targeting’s authoring tools. At this point, a design id is generated.
2. The user requests that the design be built. At this point, a build id is generated.
3. Foursquare Targeting processes the build request.

• Using information contained in the Proximity or Audience design, Foursquare Targeting generates a targeting file, known as a Proximity Filter or Audience Set, respectively.
• These targeting files are used in conjunction with Foursquare Targeting’s On-Prem software to provide real time targeting information.

4. Once the build is successfully processed, the design is now associated with an available build.
5. The user requests a deployment of that build to a given partner’s On-Prem software. At this point, a deployment id is generated.
6. An administrator of the On-Prem software approves the deployment request and activates the deployment.
7. Upon activation, the targeting file associated with the deployment will get loaded into memory in the partner’s On-Prem software and responses from the targeting file will begin to be returned.
8. When the campaign is complete, the administrator can deactivate or delete the deployment, removing the targeting file from their On-Prem software.

A few non-standard paths exist:

• After step 5 and before an administrator has completed step 6, the user that requested deployment of a built design may cancel their pending request.
• At step 6, the administrator may reject the activation request (e.g. if the targeting file associated with the deployment is abnormally large).
• At step 7, the administrator may tag a deployment for the purpose of optimizing server capacity.
• At step 7, the administrator may temporarily deactivate a build to free up memory in their On-Prem servers and then reactivate it when convenient.

API Overview

The following APIs enable programmatic access to each step of the aforementioned lifecycle:

You will find comprehensive documentation on each API call below.

Each API call will include a number of standard response parameters,

Get Design

Returns all details about a specific Proximity or Audience design.

Endpoint

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

• This endpoint only accepts GET requests.
• Replace (design Id) with the id of the design for which you are requesting information.

Example

https://api.targeting.foursquare.com/geopulse/designs/24e12f0e-ab5f-47e0-8b7d-a7ce63241068?KEY=your_api_key

Request Parameters

*Required

Response Data Parameters

Design Status Enumeration

List Designs

Returns all details about any Proximity or Audience designs for which you have been granted visibility.

Endpoint

https://api.targeting.foursquare.com/geopulse/designs/

• This endpoint only accepts GET requests.

Example

https://api.targeting.foursquare.com/geopulse/designs?type=proximity&KEY=your_api_key

Request Parameters

*Required

¹On rare occassions, a design may be administratively assigned ownership to a different user than the one who created it. For example, if a user was to leave an org.

Response Data Parameters

For a full description of all parameters available in each row of this data object, see Get Design: Response Data Parameters above.

Request Build of a Design

Sends a request to Foursquare Targeting that this design be processed and a targeting file be produced from it. Requesting a build will put the design into status “requested” and render the design un-editable until the build is either completed or rejected by Foursquare Targeting. Note that a request build call is only valid for designs of status “in_design”, “rejected”, or “built”. For more information on design status, please see Get Design: Design Status Enumeration above.

Endpoint

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

• This endpoint only accepts POST requests.
• Replace (design id) with the id of the design you are requesting a build for.
• 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/7e805739-34c2-43d8-b19c-965b2a19b715/request HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 81

reason=require+asap&KEY=your_api_key

Request Parameters

*Required

Response parameters

If the build request was successful, it will return with a status "OK"

List Builds

Returns a list of all designs that have been successfully built, along with the build history and current deployment status of each design.

Endpoint

https://api.targeting.foursquare.com/geopulse/builds

• This endpoint only accepts GET requests.

Example

https://api.targeting.foursquare.com/geopulse/builds?type=audience&deployment_status=activated&KEY=your_api_key

Request Parameters

*Required

Response Data Row Parameters

Deployment Status Filter Enumeration

Request Deployment of a Built Design

Request that a build be deployed to a partner's infrastructure. Note that this API represents a request to a Geopulse Administrator who must subsequently activate the request (or reject it). If a build already has an associated deployment on a given target org's infrastructure, it cannot be requested to that org. For a single design, only one build may have an activated deployment on a given target org's infrastructure at any time (e.g. if Design XYZ has 4 builds, a given target org can only have one of those builds deployed at any time.)

Geopulse Administrators can see pending requests by using the deployment list API.

Endpoint

https://api.targeting.foursquare.com/geopulse/builds/(build id)/request

• This endpoint only accepts POST requests.
• Replace (build 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/builds/03c26917-5d66-4de9-96bc-b13066173c65/request HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 104

message=this+is+for+a+geotargeting+campaign&targetId=fc873d35-6f59-4d41-822a-254b716d8532&KEY=your_api_key

Request Parameters

*Required

Response Parameters

If the deployment request was successful, it will return with a status "OK"

Cancel a Deployment Request

Cancel a pending deployment request. This API is intended to support cancellation of a deployment request by the user who initiated the request. Only requests which have not already been either activated or rejected can be cancelled.

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/cancel

• This endpoint only accepts POST requests.
• Replace (deployment id) with the id of the design you are requesting a build for.
• 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/deployments/8d7d2d1f-7ee8-428e-9d27-23d7cfbf6c5d/cancel HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 67

message=apologies%2C+but+this+was+the+wrong+build&KEY=my_api_key

Request Parameters

*Required

Response Parameters

If the deployment request cancellation was successful, it will return with a status "OK"

List Deployments

The Deployment List API returns a list of all builds that have been deployed across your infrastructure, whether they are activated, deactivated, or requested. To return only a list of requested deployments, add the filter "status=requested" to this call. Similarly, to return only a list of activated deployments, add the filter "status=activated"

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments

• This endpoint only accepts GET requests.

Example

https://api.targeting.foursquare.com/geopulse/deployments?type=proximity&status=activated&KEY=my_api_key

Request Parameters

*Required

Response Data Row Parameters

Reject a Requested Deployment

Reject a deployment request. This may be used in the event that a Geopulse Admininistrator considers the targeting file associated with a deployment request to be too large for their infrastructure. Only deployments with status “requested” may be rejected.

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/reject

• This endpoint only accepts POST requests.
• Replace (deployment Id) with the deployment id.

POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/reject HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key

Request Parameters

*Required

Response Parameters

If the deployment rejection is successful, the call will return a status of "OK"

Activate a Deployment

Activate a deployment. Any deployment may be activated, except for those with status "activated" already.

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/activate

• This endpoint only accepts POST requests.
• Replace (deployment Id) with the deployment id.

Example

POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/activate HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

KEY=my_api_key

Request Parameters

*Required

Response Parameters

If the deployment activation is successful, the call will return a status of "OK"

Deactivate a Deployment

Deactivate a deployment, temporarily removing it from an On-Prem instance. This endpoint is provided to support lightweight toggling of deployed builds between active and inactive states. Only deployments of status "activated" can be deactivated.

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/deactivate

• This endpoint only accepts POST requests.
• Replace (deployment Id) with the deployment id.

Example

POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/deactivate HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key

Request Parameters

*Required

Response Parameters

If the deployment deactivation is successful, the call will return a status of "OK"

Delete a Deployment

Delete a deployment, removing it permanently from an On-Prem server. At their core, “deactivate” and “delete” fulfill the same function, which is to remove a targeting file from memory on an On-Prem server, but where “deactivated” deployments will still show up in the Geopulse Management API results, “deleted” deployments do not show up, and should be considered as gone forever. Deleting deployments is primarily for situations where the end user or Geopulse Administrator know that this particular deployment will not be needed again, and deleting it (as opposed to deactivating it) can help to declutter the API results.

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/delete

• This endpoint only accepts POST requests.
• Replace (deployment Id) with the deployment id.

Example

POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/delete HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key

Request Parameters

*Required

Response Parameters

If the deployment deletion is successful, the call will return a status of "OK"

Tag a Deployment

Deployment tags, when used in conjunction with Geopulse On-Prem software, can help with server capacity management. At set up time, an On-Prem owner can define for any individual On-Prem server which deployment tags that server should be associated with. In this case, only targeting files associated with deployments that have the matching deployment tags will be loaded into memory on the particular On-Prem server. This can help to reduce required memory on your servers, as each server no longer needs to load every targeting file.

Adding deployment tags is destructive of previous tags, so making this call will always overwrite the earlier list of tags.

Endpoint

https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/tag

• This endpoint only accepts POST requests.
• Replace (deployment id) with the id of the design you are requesting a build for.
• 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/deployments/89aa8acb-4563-4817-9051-2424aa632f20/tag HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

tags=env1&KEY=my_api_key

Request Parameters

*Required

Response Parameters

If the tag assignment is successful, the call with return a status of "OK"

Common Conventions

Paging

For API calls that return large volumes of data, the Foursquare Targeting API implements a paging system. Each API call will return one "page" of data, which includes a limited number of rows of data, offset from the start of the entire list of available data.

For example:

• The first 10 rows would be identified by limit=10 and offset=0.
• The next 10 rows would be identified by limit=10 and offset=10.

Paging parameters are used in conjunction with any other parameters that may filter a list down. So, for example, if you request a list of designs filtered to just proximity designs, you'll get the first 10 proximity designs, then the next 10. There won't be any "holes" in the result set where audience designs would have slotted chronologically.