factual

Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Management

Introduction

The Geopulse Management APIs are a suite of APIs that enable you to manage the building and deployment of Geopulse 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 Factual’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. Factual processes the build request.
    • Using information contained in the Proximity or Audience design, Factual generates a targeting file, known as a Proximity Filter or Audience Set, respectively.
    • These targeting files are used in conjunction with Factual’s Geopulse 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 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 Factual
/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 "OK"
**response The response object JSON Object
response.data The data object, containing a single design object with the parameters found in the below "Response Data Parameters" JSON Object
included_row_count The total rows included in the data array contained in this response Number 23
total_row_count The total rows available for this data array See paging Number 1002

Get Design

Returns all details about a specific Proximity or Audience design.

Endpoint

https://api.factual.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.factual.com/geopulse/designs/24e12f0e-ab5f-47e0-8b7d-a7ce63241068?KEY=your_api_key

Request Parameters

Parameter Name Description Datatype Example
*Key Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

Response Data Parameters

Parameter Name Description Datatype Example
id The design ID String (GUID) "38697e15-9e9e-4917-b55b-6431b99392f4"
name The design name String "LA Car Dealerships"
type proximity or audience String (enumerated) "proximity"
status in_design, requested, rejected, building, failed, built String (enumerated) "in_design"
created_at Timestamp for when design was created String (date) "2016-01-06T17:11:17.000Z"
updated_at Timestamp of most recent design update String (date) "2016-01-06T17:11:17.000Z"
external_build Whether or not the design is associated with a build created outside of the Geopulse designer tools. A design with a value of "true" cannot be edited. Boolean false
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. Number 12
most_recent_build The build ID of the most recent build String (GUID) "ac5925c7-e727-45b5-848b-c2532dc84db7"
owner_id The user id of the design's owner String (GUID) "eea9f6ef-c9f3-430a-8db0-d89e8476aebd"
owner_org_id The id of the design owner's organization String (GUID) "d4e49049-07fd-4c67-8325-1c803a8d1857"
owner_name The email of the design owner String "user1@factual.com"
price_cpm Price 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_builds The number of builds associated with this design that have been deployed to a partner's On-Prem software Number 1
is_shared_to_current_user Whether access to the design has been explicitly shared with the current user Boolean false
is_shared_to_current_org Whether access to the design has been shared with the current user's entire organization Boolean false
sets An array of sets contained within the design object JSON Array
sets[row].set_id The id of the set String (GUID) "d151ea2c-9879-460c-a169-77a0de9ec3c5"
sets[row].set_name The name of the set String "Used Car Dealers"
sets[row].targeting_code The targeting code associated with the set String "cars_1000m"
set_ids An array of all set IDs associated with the design JSON Array
collaborators An array of all users or orgs explicitly granted access to the design JSON Array
collaborators[row].type user or org String "user"
collaborators[row].id The user or org ID of the collaborator String (GUID) "eea9f6ef-c9f3-430a-8db0-d89e8476aebd"
collaborators[row].label The human readable representation of the user or org. Email for user. Org Name for org. String "user1@factual.com"
collaborators[row].permissions Permissions defining the collaborator's level of access to the design JSON Object
collaborators[row].permissions[row].view Whether or not the collaborator has access to view the design Boolean true
collaborators[row].permissions[row].edit Whether or not the collaborator has access to edit the design Boolean true

Design Status Enumeration

Design Status Description Design Editable? Can Request Build?
in_design The design is in the design phase and has not been requested or built yet. Yes Yes
requested The user has requested a build get created from the design, and it is awaiting being places onto Factual'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. No No
rejected The build request was rejected by Factual, and must be re-requested. The design is free to be edited in this state. Yes Yes
building The design is in Factual's cluster queue to be processed into a build. No No
failed The build process failed, and Factual will either fix the build and re-try or reach out to make any necessary fixes. No No
built The design has been successfully built. Yes Yes

List Designs

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

Endpoint

https://api.factual.com/geopulse/designs/
  • This endpoint only accepts GET requests.

Example

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

Request Parameters

Parameter Name Description Datatype Example
limit When paging through longer lists of data, the maximum number of rows to return per request. See paging Number limit=10
offset When paging through longer lists, the offset from the first row of data to begin at. See paging Number offset=0
owner The user ID of the user that created the design.1 String (GUID) owner=eea9f6ef-c9f3-430a-8db0-d89e8476aebd
owner_org_id The organization ID of the user that owns the design. String (GUID) owner_org_id=d4e49049-07fd-4c67-8325-1c803a8d1857
q A full-text search string. String q=car
type The type of design. Either proximity or audience. String (enumerated) type=audience
visibility Filter out designs that do not contain the granted visibility tags Comma delimited array of Strings visibility=star_market,pepsi
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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 Factual 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 Factual. 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.factual.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.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 81

reason=require+asap&KEY=your_api_key

Request Parameters

Parameter Name Description Datatupe Example
*reason A text description of the reason for this build request String reason=testing
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.com/geopulse/builds
  • This endpoint only accepts GET requests.

Example

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

Request Parameters

Parameter Name Description Datatype Example
limit When paging through longer lists of data, the maximum number of rows to return per request. See paging Number limit=10
offset When paging through longer lists, the offset from the first row of data to begin at. See paging Number offset=0
q A full-text search string. String q=car
type The type of design. Either proximity or audience. String (enumerated) type=audience
visibility Filter out designs that do not contain the granted visibility tags Comma delimited array of Strings visibility=cokevisibility=star_market,pepsi
deployment_status The 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 strings deployment_status=activated,deactivated
deployment_target The 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 strings deployment_target=bigdsp
min_size Minimum size of the targeting file associated with the most recent build Number min_size=10000
max_size Maximum size of the targeting file associated with the most recent build Number max_size=10000000
sort Sort by build_date, requested_at, or last_build_size String (enumerated) sort=last_build_size
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

Response Data Row Parameters

Parameter Name Description Datatype Example
id The design ID String (GUID) "38697e15-9e9e-4917-b55b-6431b99392f4"
type proximity or audience String (enumerated) "proximity"
name The design name String "LA Car Dealerships"
owner Email of the design owner String "user1@factual.com"
builds Array of build objects associated with this design JSON Array
builds[row].id Build ID String (GUID) "a4d51e3b-ae95-4917-a7db-878255f334ea"
builds[row].name Name of the build. This is equal to the design name at the point that the build is initially generated. String "LA Automotive"
builds[row].status The processing status of the build. Currently will only return DONE String (enumerated) "DONE"
builds[row].size Size, in bytes, of the targeting file associated with the completed build Number 1061822
builds[row].requested_at Timestamp representing when the build was initially requested String (date) "2016-02-29T22:26:26.000Z"
builds[row].build_date Timestamp representing when the build was successfully completed String (date) "2016-03-01T05:22:33.000Z"
builds[row].builder Email of the user who requested the build String "user1@factual.com"
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].sources The 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_version Date that the inventory source used to create the build was last processed String (date) "2016-02-29T22:26:26.000Z"
builds[row].price_cpm Price 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"}
deployments Array of deployment objects associated with this design JSON Array
deployments[row].id Deployment ID String (GUID) "5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b"
deployments[row].target Name of the target where this deployment is associated String "Big DSP"
deployments[row].target_id ID of the target where this deployment is associated String (GUID) "42dc6d44-a910-4e11-8fdb-8051c10aadee"
deployments[row].status Status of the deployment activated, deactivated, requested String (enumerated) "activated"
deployments[row].build_id Build ID of the build object associated with this deployment String (GUID) "a4d51e3b-ae95-4917-a7db-878255f334ea"
last_build_id Build ID for the most recent build of this design String (GUID) "a4d51e3b-ae95-4917-a7db-878255f334ea"
last_build_name Name of the most recent build of this design String "LA Automotive"
last_build_builder Email of the user who requested the most recent build of this design String "user1@factual.com"
last_build_date Timestamp of when the most recent build of this design was completed String (date) "2016-03-01T05:22:33.000Z"
last_build_source (DEPRECATED) Inventory source of the most recent build of this design String "factual_dap"
last_build_sources Inventory source(s) of the most recent build of this design JSON Array ["factual_dap", "ad_corp"]
last_build_size Size in bytes of the targeting file associated with the most recent build of this design Number 110292
last_build_audience_index_version Date that the inventory source used to create the build was last processed String (date) "2016-02-29T22:26:26.000Z"

Deployment Status Filter Enumeration

Deployment Status Filter Description
activated Return any designs with a deployment that is "activated" on the target partner's system
deactivated Return any designs with a deployment that is temporarily "deactivated" the target partner's system (e.g. to conserve memory on the partner's servers)
requested Return 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_replacement Return 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_date Return 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)
undeployed Return 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.factual.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.factual.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 Name Description Datatype Example
message A message to send with the deployment request if you would like Factual to know additional metadata String message=this+is+a+test
*targetId The ID of the deployment target that the user is wanting to deploy to String (GUID) targetId=fc873d35-6f59-4d41-822a-254b716d8532
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.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.factual.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 Name Description Datatype Example
message A message to send with the deployment cancellation if you would like Factual to know additional metadata String message=wrong+partner
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.com/geopulse/deployments
  • This endpoint only accepts GET requests.

Example

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

Request Parameters

Parameter Name Description Datatype Example
limit When paging through longer lists of data, the maximum number of rows to return per request. See paging Number limit=10
offset When paging through longer lists, the offset from the first row of data to begin at. See paging Number offset=0
q A full-text search string. String q=car
type The type of design. Either proximity or audience. String (enumerated) type=audience
target_type The type of target the deployment is associated with (e.g. OnPrem, LIDS, etc.) String target_type=onprem
visibility Filter out designs that do not contain the granted visibility tags Comma delimited array of Strings visibility=cokevisibility=star_market,pepsi
status Status of the deployment: activated, deactivated, or requested. Comma delimited array of strings status=activated,deactivated
min_size Minimum size of the targeting file associated with deployed build Number min_size=10000
max_size Maximum size of the targeting file associated with deployed build Number max_size=10000000
start_date Starting timestamp to filter deployments by time of approval. Integer (epoch date, seconds) start_date=1475167405
end_date Ending timestamp to filter deployments by time of approval. Integer (epoch date, seconds) end_date=1475167424
new_build Filter by the following: true=deployments associated with the first build of a design, false=deployments associated with a refreshed build Boolean new_build=true
sort Sort by updated_at, approved_at, build_date, or build_size String (enumerated) sort=build_size
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

*Required

Response Data Row Parameters

Parameter Name Description Datatype Example
id The deployment ID String (GUID) "5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b"
status Status of the deployment: activated, deactivated, or requested. "activated"
type proximity or audience String (enumerated) "proximity"
design_id ID of the associated design String (GUID) "38697e15-9e9e-4917-b55b-6431b99392f4<"/pre>
build_id The build ID String (GUID) "a4d51e3b-ae95-4917-a7db-878255f334ea"
design_name The current name of the design. String "LA Car Dealerships"
build_name Name of the build String "LA Automotive"
filesize Size, in bytes, of the targeting file associated with the deployed build Number 1061822
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"
sources The 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_cpm Price 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_org Slug of the Org associated with the user who generated the build String "factual"
build_org_id ID of the Org associated with the user who generated the build String (GUID) "9303c65c-ad1f-4845-837f-aa87197cd448"
builder Email of the user who generated the build String "user1@factual.com"
requester Email of the user who requested the deployment String "user2@factual.com"
deployer Email of the Geopulse admin who approved the deployment request String "admin@bigdsp.com"
build_date Timestamp representing when the build was successfully completed String (date) "2016-03-01T05:22:33.000Z"
updated_at Timestamp representing when the deployment was most recently updated String (date) "2016-03-03T00:45:30.000Z"
approved_at Timestamp representing when the deployment was initially marked as activated String (date) "2016-03-03T00:45:30.000Z"
new_build Describes whether a deployment is associated with the first build of a given design. True = first version of a design Boolean true
tags Deployment tags associated with the deployment String "large,europe"
target Name of the target associated with the deployment String "Big DSP OnPrem"
target_id ID of the deployment target String (GUID) "aaffc17d-fd80-34aa-22bc-32133edf88b1"
sets Array of sets in the build associated with the deployment JSON Array
sets[row].set_id The id of the set String (GUID) "d151ea2c-9879-460c-a169-77a0de9ec3c5"
sets[row].set_name The name of the set String "Used Car Dealers"
sets[row].targeting_code The targeting code associated with the set String "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.factual.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.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key

Request Parameters

Parameter Name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.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.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

KEY=my_api_key

Request Parameters

Parameter Name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.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.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key

Request Parameters

Parameter Name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.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.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key

Request Parameters

Parameter Name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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.factual.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.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

tags=env1&KEY=my_api_key

Request Parameters

Parameter Name Description Datatype Example
*tags The defined deployment tags String (comma delimited) tags=large,europe
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String KEY=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 Factual 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.