Management
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:
- A user creates and saves a design using Foursquare Targeting’s authoring tools. At this point, a design id is generated.
- The user requests that the design be built. At this point, a build id is generated.
- 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.
- Once the build is successfully processed, the design is now associated with an available build.
- The user requests a deployment of that build to a given partner’s On-Prem software. At this point, a deployment id is generated.
- An administrator of the On-Prem software approves the deployment request and activates the deployment.
- 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.
- 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:
| Endpoint | Description |
|---|---|
| /geopulse/designs/ design_id | Get meta-data for a specific design |
| /geopulse/designs/ | List all designs visible to you |
| /geopulse/designs/ design_id/request | Request that a design be built by Foursquare Targeting |
| /geopulse/builds | List designs that have been successfully built, build history, and deployment status |
| /geopulse/builds/ build_id/request | Request that a built design be activated |
| /geopulse/deployments/ deployment_id/cancel | Cancel an activation request before it is approved and activated |
| /geopulse/deployments/ deployment_id/reject | Reject a request to activate a build |
| /geopulse/deployments/ | List deployments |
| /geopulse/deployments/ deployment_id/activate | Activate a build |
| /geopulse/deployments/ deployment_id/deactivate | Deactivate a build |
| /geopulse/deployments/ deployment_id/delete | Delete a build |
| /geopulse/deployments/ deployment_id/tag | Tag a deployed build (for capacity management) |
You will find comprehensive documentation on each API call below.
Each API call will include a number of standard response parameters,
| Parameter Name | Description | Datatype | Example |
|---|---|---|---|
| version | The version of the API response | Number | 4 |
| status | The status of the API response | String | ` |