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:

  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.
  1. Once the build is successfully processed, the design is now associated with an available build.
  2. The user requests a deployment of that build to a given partner’s On-Prem software. At this point, a deployment id is generated.
  3. An administrator of the On-Prem software approves the deployment request and activates the deployment.
  4. 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.
  5. 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:

EndpointDescription
/geopulse/designs/design_idGet meta-data for a specific design
/geopulse/designs/List all designs visible to you
/geopulse/designs/design_id/requestRequest that a design be built by Foursquare Targeting
/geopulse/buildsList designs that have been successfully built, build history, and deployment status
/geopulse/builds/build_id/requestRequest that a built design be activated
/geopulse/deployments/deployment_id/cancelCancel an activation request before it is approved and activated
/geopulse/deployments/deployment_id/rejectReject a request to activate a build
/geopulse/deployments/List deployments
/geopulse/deployments/deployment_id/activateActivate a build
/geopulse/deployments/deployment_id/deactivateDeactivate a build
/geopulse/deployments/deployment_id/deleteDelete a build
/geopulse/deployments/deployment_id/tagTag 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 NameDescriptionDatatypeExample
versionThe version of the API responseNumber4
statusThe status of the API responseString"OK"
**responseThe response objectJSON Object
response.dataThe data object, containing a single design object with the parameters found in the below "Response Data Parameters"JSON Object
included_row_countThe total rows included in the data array contained in this responseNumber23
total_row_countThe total rows available for this data array See pagingNumber1002

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

Parameter NameDescriptionDatatypeExample
*KeyYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

Response Data Parameters

Parameter NameDescriptionDatatypeExample
idThe design IDString (GUID)"38697e15-9e9e-4917-b55b-6431b99392f4"
nameThe design nameString"LA Car Dealerships"
typeproximity or audienceString (enumerated)"proximity"
statusin_design, requested, rejected, building, failed, builtString (enumerated)"in_design"
created_atTimestamp for when design was createdString (date)"2016-01-06T17:11:17.000Z"
updated_atTimestamp of most recent design updateString (date)"2016-01-06T17:11:17.000Z"
external_buildWhether or not the design is associated with a build created outside of the designer tools. A design with a value of "true" cannot be edited.Booleanfalse
design_size(Deprecated) An internal value that estimates how complex this design may be to build on a relative scale. Not intended to be user facing.Number12
most_recent_buildThe build ID of the most recent buildString (GUID)"ac5925c7-e727-45b5-848b-c2532dc84db7"
owner_idThe user id of the design's ownerString (GUID)"eea9f6ef-c9f3-430a-8db0-d89e8476aebd"
owner_org_idThe id of the design owner's organizationString (GUID)"d4e49049-07fd-4c67-8325-1c803a8d1857"
owner_nameThe email of the design ownerString"
price_cpmPrice of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon.JSON Object{"base": "0.75"}
active_buildsThe number of builds associated with this design that have been deployed to a partner's On-Prem softwareNumber1
is_shared_to_current_userWhether access to the design has been explicitly shared with the current userBooleanfalse
is_shared_to_current_orgWhether access to the design has been shared with the current user's entire organizationBooleanfalse
setsAn array of sets contained within the design objectJSON Array
sets[row].set_idThe id of the setString (GUID)"d151ea2c-9879-460c-a169-77a0de9ec3c5"
sets[row].set_nameThe name of the setString"Used Car Dealers"
sets[row].targeting_codeThe targeting code associated with the setString"cars_1000m"
set_idsAn array of all set IDs associated with the designJSON Array
collaboratorsAn array of all users or orgs explicitly granted access to the designJSON Array
collaborators[row].typeuser or orgString"user"
collaborators[row].idThe user or org ID of the collaboratorString (GUID)"eea9f6ef-c9f3-430a-8db0-d89e8476aebd"
collaborators[row].labelThe human readable representation of the user or org. Email for user. Org Name for org.String"
collaborators[row].permissionsPermissions defining the collaborator's level of access to the designJSON Object
collaborators[row].permissions[row].viewWhether or not the collaborator has access to view the designBooleantrue
collaborators[row].permissions[row].editWhether or not the collaborator has access to edit the designBooleantrue

Design Status Enumeration

Design StatusDescriptionDesign Editable?Can Request Build?
in_designThe design is in the design phase and has not been requested or built yet.YesYes
requestedThe user has requested a build get created from the design, and it is awaiting being places onto Foursquare Targeting's cluster to process the build. The design is frozen in this state, and cannot be changed until the build successfully completes or the build request is rejected.NoNo
rejectedThe build request was rejected by Foursquare Targeting, and must be re-requested. The design is free to be edited in this state.YesYes
buildingThe design is in Foursquare Targeting's cluster queue to be processed into a build.NoNo
failedThe build process failed, and Foursquare Targeting will either fix the build and re-try or reach out to make any necessary fixes.NoNo
builtThe design has been successfully built.YesYes

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

Parameter NameDescriptionDatatypeExample
limitWhen paging through longer lists of data, the maximum number of rows to return per request. See pagingNumberlimit=10
offsetWhen paging through longer lists, the offset from the first row of data to begin at. See pagingNumberoffset=0
ownerThe user ID of the user that created the design.1String (GUID)owner=eea9f6ef-c9f3-430a-8db0-d89e8476aebd
owner_org_idThe organization ID of the user that owns the design.String (GUID)owner_org_id=d4e49049-07fd-4c67-8325-1c803a8d1857
qA full-text search string.Stringq=car
typeThe type of design. Either proximity or audience.String (enumerated)type=audience
visibilityFilter out designs that do not contain the granted visibility tagsComma delimited array of Stringsvisibility=star_market,pepsi
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

1On 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

Parameter NameDescriptionDatatupeExample
*reasonA text description of the reason for this build requestStringreason=testing
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
limitWhen paging through longer lists of data, the maximum number of rows to return per request. See pagingNumberlimit=10
offsetWhen paging through longer lists, the offset from the first row of data to begin at. See pagingNumberoffset=0
qA full-text search string.Stringq=car
typeThe type of design. Either proximity or audience.String (enumerated)type=audience
visibilityFilter out designs that do not contain the granted visibility tagsComma delimited array of Stringsvisibility=cokevisibility=star_market,pepsi
deployment_statusThe builds current deployment status: activated, deactivated, requested, requested_replacement, out_of_date, or undeployed. For a full description of the various deployment statuses, see Deployment Status Filter Enumeration below.Comma delimited array of stringsdeployment_status=activated,deactivated
deployment_targetThe slug of the target org to which the deployment_status parameter should be applied. Does nothing if deployment_status is not specified.Comma delimited array of stringsdeployment_target=bigdsp
min_sizeMinimum size of the targeting file associated with the most recent buildNumbermin_size=10000
max_sizeMaximum size of the targeting file associated with the most recent buildNumbermax_size=10000000
sortSort by build_date, requested_at, or last_build_sizeString (enumerated)sort=last_build_size
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

Response Data Row Parameters

Parameter NameDescriptionDatatypeExample
idThe design IDString (GUID)"38697e15-9e9e-4917-b55b-6431b99392f4"
typeproximity or audienceString (enumerated)"proximity"
nameThe design nameString"LA Car Dealerships"
ownerEmail of the design ownerString"
buildsArray of build objects associated with this designJSON Array
builds[row].idBuild IDString (GUID)"a4d51e3b-ae95-4917-a7db-878255f334ea"
builds[row].nameName of the build. This is equal to the design name at the point that the build is initially generated.String"LA Automotive"
builds[row].statusThe processing status of the build. Currently will only return DONEString (enumerated)"DONE"
builds[row].sizeSize, in bytes, of the targeting file associated with the completed buildNumber1061822
builds[row].requested_atTimestamp representing when the build was initially requestedString (date)"2016-02-29T22:26:26.000Z"
builds[row].build_dateTimestamp representing when the build was successfully completedString (date)"2016-03-01T05:22:33.000Z"
builds[row].builderEmail of the user who requested the buildString"
builds[row].source (DEPRECATED)The inventory source (e.g. ad exchange) that was used to create the build object. Only returned for designs of type "audience" where an inventory source must be specified.String"factual_dap"
builds[row].sourcesThe inventory source(s) (e.g. ad exchanges) that were used to create the build object. Only returned for designs of type "audience" where an inventory source must be specified.JSON Array["factual_dap", "ad_corp"]
builds[row].audience_index_versionDate that the inventory source used to create the build was last processedString (date)"2016-02-29T22:26:26.000Z"
builds[row].price_cpmPrice of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon.JSON Object{"base": "0.75"}
deploymentsArray of deployment objects associated with this designJSON Array
deployments[row].idDeployment IDString (GUID)"5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b"
deployments[row].targetName of the target where this deployment is associatedString"Big DSP"
deployments[row].target_idID of the target where this deployment is associatedString (GUID)"42dc6d44-a910-4e11-8fdb-8051c10aadee"
deployments[row].statusStatus of the deployment activated, deactivated, requestedString (enumerated)"activated"
deployments[row].build_idBuild ID of the build object associated with this deploymentString (GUID)"a4d51e3b-ae95-4917-a7db-878255f334ea"
last_build_idBuild ID for the most recent build of this designString (GUID)"a4d51e3b-ae95-4917-a7db-878255f334ea"
last_build_nameName of the most recent build of this designString"LA Automotive"
last_build_builderEmail of the user who requested the most recent build of this designString"
last_build_dateTimestamp of when the most recent build of this design was completedString (date)"2016-03-01T05:22:33.000Z"
last_build_source (DEPRECATED)Inventory source of the most recent build of this designString"factual_dap"
last_build_sourcesInventory source(s) of the most recent build of this designJSON Array["factual_dap", "ad_corp"]
last_build_sizeSize in bytes of the targeting file associated with the most recent build of this designNumber110292
last_build_audience_index_versionDate that the inventory source used to create the build was last processedString (date)"2016-02-29T22:26:26.000Z"

Deployment Status Filter Enumeration

Deployment Status FilterDescription
activatedReturn any designs with a deployment that is "activated" on the target partner's system
deactivatedReturn any designs with a deployment that is temporarily "deactivated" the target partner's system (e.g. to conserve memory on the partner's servers)
requestedReturn any designs with a deployment that is "requested" on the target partner's system, where that deployment has not been activated or rejected yet.
requested_replacementReturn any designs that have a deployment that is "requested" which, if activated, will replace an existing deployment associated with that design. A design can only have a single build activated on a given partner's system at any given time.
out_of_dateReturn any designs that have a deployment on the target partner's system where the build associated with that deployment is out of date, and a more recent build has since been generated. (e.g. Design ABC has been built 5 times, but only build 4 is deployed to a partner)
undeployedReturn any designs that have no deployment associated with the target partner's system.

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

Parameter NameDescriptionDatatypeExample
messageA message to send with the deployment request if you would like Foursquare Targeting to know additional metadataStringmessage=this+is+a+test
*targetIdThe ID of the deployment target that the user is wanting to deploy toString (GUID)targetId=fc873d35-6f59-4d41-822a-254b716d8532
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
messageA message to send with the deployment cancellation if you would like Foursquare Targeting to know additional metadataStringmessage=wrong+partner
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
limitWhen paging through longer lists of data, the maximum number of rows to return per request. See pagingNumberlimit=10
offsetWhen paging through longer lists, the offset from the first row of data to begin at. See pagingNumberoffset=0
qA full-text search string.Stringq=car
typeThe type of design. Either proximity or audience.String (enumerated)type=audience
target_typeThe type of target the deployment is associated with (e.g. OnPrem, LIDS, etc.)Stringtarget_type=onprem
visibilityFilter out designs that do not contain the granted visibility tagsComma delimited array of Stringsvisibility=cokevisibility=star_market,pepsi
statusStatus of the deployment: activated, deactivated, or requested.Comma delimited array of stringsstatus=activated,deactivated
min_sizeMinimum size of the targeting file associated with deployed buildNumbermin_size=10000
max_sizeMaximum size of the targeting file associated with deployed buildNumbermax_size=10000000
start_dateStarting timestamp to filter deployments by time of approval.Integer (epoch date, seconds)start_date=1475167405
end_dateEnding timestamp to filter deployments by time of approval.Integer (epoch date, seconds)end_date=1475167424
new_buildFilter by the following: true=deployments associated with the first build of a design, false=deployments associated with a refreshed buildBooleannew_build=true
sortSort by updated_at, approved_at, build_date, or build_sizeString (enumerated)sort=build_size
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

Response Data Row Parameters

Parameter NameDescriptionDatatypeExample
idThe deployment IDString (GUID)"5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b"
statusStatus of the deployment: activated, deactivated, or requested."activated"
typeproximity or audienceString (enumerated)"proximity"
design_idID of the associated designString (GUID)"38697e15-9e9e-4917-b55b-6431b99392f4<"/pre>
build_idThe build IDString (GUID)"a4d51e3b-ae95-4917-a7db-878255f334ea"
design_nameThe current name of the design.String"LA Car Dealerships"
build_nameName of the buildString"LA Automotive"
filesizeSize, in bytes, of the targeting file associated with the deployed buildNumber1061822
source (DEPRECATED)The inventory source (e.g. ad exchange) that was used to create the build object. Only applicable to designs of type "audience" where an inventory source must be specified to determine what inventory source to create the audience off of. Null for builds associated with designs of type "proximity".String"factual_dap"
sourcesThe inventory source(s) (e.g. ad exchange) that was used to create the build object. Only applicable to designs of type "audience" where an inventory source must be specified to determine what inventory source(s) to create the audience off of. Null for builds associated with designs of type "proximity".JSON Array["factual_dap", "ad_corp"]
price_cpmPrice of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon.JSON Object{"base": "0.75"}
build_orgSlug of the Org associated with the user who generated the buildString"factual"
build_org_idID of the Org associated with the user who generated the buildString (GUID)"9303c65c-ad1f-4845-837f-aa87197cd448"
builderEmail of the user who generated the buildString"
requesterEmail of the user who requested the deploymentString"
deployerEmail of the Geopulse admin who approved the deployment requestString"
build_dateTimestamp representing when the build was successfully completedString (date)"2016-03-01T05:22:33.000Z"
updated_atTimestamp representing when the deployment was most recently updatedString (date)"2016-03-03T00:45:30.000Z"
approved_atTimestamp representing when the deployment was initially marked as activatedString (date)"2016-03-03T00:45:30.000Z"
new_buildDescribes whether a deployment is associated with the first build of a given design. True = first version of a designBooleantrue
tagsDeployment tags associated with the deploymentString"large,europe"
targetName of the target associated with the deploymentString"Big DSP OnPrem"
target_idID of the deployment targetString (GUID)"aaffc17d-fd80-34aa-22bc-32133edf88b1"
setsArray of sets in the build associated with the deploymentJSON Array
sets[row].set_idThe id of the setString (GUID)"d151ea2c-9879-460c-a169-77a0de9ec3c5"
sets[row].set_nameThe name of the setString"Used Car Dealers"
sets[row].targeting_codeThe targeting code associated with the setString"cars_1000m"

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

Parameter NameDescriptionDatatypeExample
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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

Parameter NameDescriptionDatatypeExample
*tagsThe defined deployment tagsString (comma delimited)tags=large,europe
*KEYYour API Key. Note the KEY parameter name must be declared in all caps.StringKEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*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.