# 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:

| Endpoint | Description |
| --- | --- |
| [/geopulse/designs/ **design_id**](https://docs.foursquare.com/developer/reference/targeting-api-management#section-get-design) | Get meta-data for a specific design |
| [/geopulse/designs/](https://docs.foursquare.com/developer/reference/targeting-api-management#section-list-designs) | List all designs visible to you |
| [/geopulse/designs/ **design_id**/request](https://docs.foursquare.com/developer/reference/targeting-api-management#section-request-build-of-a-design) | Request that a design be built by Foursquare Targeting |
| [/geopulse/builds](https://docs.foursquare.com/developer/reference/targeting-api-management#section-list-builds) | List designs that have been successfully built, build history, and deployment status |
| [/geopulse/builds/ **build_id**/request](https://docs.foursquare.com/developer/reference/targeting-api-management#section-request-deployment-of-a-built-design) | Request that a built design be activated |
| [/geopulse/deployments/ **deployment_id**/cancel](https://docs.foursquare.com/developer/reference/targeting-api-management#section-cancel-a-deployment-request) | Cancel an activation request before it is approved and activated |
| [/geopulse/deployments/ **deployment_id**/reject](https://docs.foursquare.com/developer/reference/targeting-api-management#section-reject-a-requested-deployment) | Reject a request to activate a build |
| [/geopulse/deployments/](https://docs.foursquare.com/developer/reference/targeting-api-management#section-list-deployments) | List deployments |
| [/geopulse/deployments/ **deployment_id**/activate](https://docs.foursquare.com/developer/reference/targeting-api-management#section-activate-a-deployment) | Activate a build |
| [/geopulse/deployments/ **deployment_id**/deactivate](https://docs.foursquare.com/developer/reference/targeting-api-management#section-deactivate-a-deployment) | Deactivate a build |
| [/geopulse/deployments/ **deployment_id**/delete](https://docs.foursquare.com/developer/reference/targeting-api-management#section-delete-a-deployment) | Delete a build |
| [/geopulse/deployments/ **deployment_id**/tag](https://docs.foursquare.com/developer/reference/targeting-api-management#section-tag-a-deployment) | 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 | `