Geopulse API Documentation

The Geopulse APIs are a suite of APIs that allow Factual partners integrated with Geopulse to perfom a number of different functions, depending on the needed use case. The Geopulse APIs can be used for use cases as simple as calculating avails using your own sample data against a specific design to powering a fully functional embeddable Factual UI.

A few examples for what these APIs enable:

  • Manage memory usage in Geopulse On-Prem software
  • Drive a dropdown of available targeting in a partner UI
  • Estimate reach for a given Proximity or Audience design
  • Embed the Factual designer UIs into your own platform
  • Managing complex permissions to Geopulse designs

Authentication

In V4, server API calls are made by passing your API key into the KEY (case-sensitive) parameter, and making your requests through https:

https://api.factual.com/categories?KEY=your_API_key

Instead of cryptographically signing your requests to verify that requests are being made by your service, as is required by our V3 API, you restrict IP addresses that are authorized to make API calls using your key (server-side), or restrict access by Bundle Id (iOS).

If you do not bind your key to an IP address or Bundle Id, you may be responsible for any unauthorized access to your API key.




image: API key manager, accessible from your profile when you are logged into www.factual.com.


We’re still working on support for Android and client-side (Javascript/browser) access, so currently V4 APIs are unavailable to those platforms.

Tracking Throttle Allocation (Real-time)

Every API response includes the remaining throttle allocation for the specified API key in the X-Factual-Throttle-Allocation HTTP header.

Example:

X-Factual-Throttle-Allocation:{"burst":"0%","daily":"0%"}

Notes:

  • The Factual API has a requests per minute limit as well as a per day limit. Exceeding the requests per minute will result in a short delay in processing each request rather than denying requests. The delay will, in aggregate, result in your request volume to be no greater than the RPM limit.
  • Exceeding the RMD will result in a 429 response.
  • RPD and RPM are calculated by per individual request method.
  • RPD and RPM are calculated based on rolling 24 hour and 1 minute periods.

Tokens

Introduction

This document details generating access tokens that can be used by your web clients to make secure, direct calls to Factual’s APIs. Using tokens enables you to avoid proxying API calls through your own servers and is a required piece of implementing an embeddable UI workflow.

Requirements

The basic requirements to implement tokens to access Factual are:

  • A server in your control that can authenticate your clients against your own user DB
  • A Factual API key
  • The ability for your server to make an outbound API call to Factual
  • The ability for your server to forward the results of an API call from Factual to your clients


The diagram below details the basic authentication flow:


As shown in the diagram above, the basic steps are:

  1. Your user attempts to login from one of your clients by sending login credentials to your server.
  2. Assuming the user has acceptable credentials, your server will either:
    • Return the most recent Factual authentication token it has for the user (assuming that it hasn’t passed its expiration date).1
    • Request a new token from Factual on behalf of that user.2
  3. In the event a token was requested, Factual will return the token to your server.
  4. Your server in turn will return the access token to the client.
  5. Your client will use the token to make a request to Factual.
  6. Factual will determine if the token is valid, and what permissions it should have.
  7. As appropriate, Factual will return data to the client.

Note: Until your client’s Factual token has expired, your client does not need to re-request tokens to make calls to Factual.


1 There is no harm in asking for a token redundantly. Factual will consistently return the same token is for that user.

2 If this is the first time the user has requested access to Factual, all necessary configuration on Factual’s side will be performed immediately, in order to respond to your server’s request in a timely manner. E.g., each user’s Factual credentials are generated quickly but lazily.


Getting an API Key

If you haven’t already, you can register an account at Factual here. Once you’ve done that (or logged into Factual), go to the Factual API key manager at https://www.factual.com/keys.

  1. Within the key manager, you’ll be generating a Server App key:
  2. After you generate your Server App key, hit modify.
  3. Click the Security and Permissions tab.
  4. Enter the IP address of your server. This helps prevent use of your API key to generate tokens from unauthorized domains, if it were to be compromised.
  5. Hit save.
  6. Your API key is listed as OAuth Key. For this use case, you will not require the OAuth Secret.

Getting Tokens

Tokens are generated using an https request to Factual’s V4 API. Authentication of your token API call is performed simply by supplying your API key to the KEY parameter (all CAPS) to the /token/user endpoint. Along with your API key, the following parameters are required (unless you provide a user Id, as detailed later):

  • email (User email address.)
  • first_name (first name of user. must not be blank or all white space.)
  • last_name (last name of user. must not be blank or all white space.)


Token API request

The basic syntax for getting a token is to make a GET request as follows:

https://api.factual.com/token/user?email=email_address&first_name=first_name&last_name=last_name&KEY=api_key

  • As per any http GET request parameter, the email address and first/last names must be URL-encoded.
  • The request must be transmitted securely through https.


Refresh Token API request

Once you have received a successful token response containing a user id, you should request future tokens for that user simply using the user id:

https://api.factual.com/token/user/user_id?KEY=api_key


Token API response

Responses to the Factual API contain a JSON object in the response body, in addition to metadata in the http headers and the http status code. The standard http response body will contain data conforming to the JSend convention, augmented with a few other attributes:

  • status (success, fail, error)
  • data (for success_/_fail)
  • message (for error)
  • version (API version)


Standard response

An http 200 response will be accompanied with JSON, similar to the following, containing the user’s userId, token and the expiration date of the token:

{
  "version":4,
  "status":"success",
  "data":{
    "uid":"fbd96e3a-1d7d-4a93-b201-020e53e65417",
    "token":"XTH4sYzIjP5cG6RzqSoi",
    "expiration":1443650290
  }
}

You should forward both the token and expiration date to your clients. The expiration date will be in epoch time, in seconds.


Exceptional paths
http response code message explanation
400 unknown parameter ‘parameter_name’ You have entered a parameter that the API does not recognize.
400 parameter ‘parameter_name’ should not be used alongside a user id. You have provided both a user id (in the URL) as well as user identifying information such as email, first_name, or last_name. You should only be providing the user Id if you have it.
400 missing required parameter ‘parameter_name’ You have not provided a user id and any of the email, first_name or last_name parameters is either missing or blank.
400 invalid email address The email address you provided is invalid.
401 invalid API key Your API key is not valid. This is most likely because you’ve either regenerated your API key (invalidating the existing one), or because you’ve made a copy/paste mistake.
403 throttled You’ve made too many API calls over the allotted period of time.
404 resource not found There is a typo somewhere in the request URL.
404 user not found The user id provided in the URL is invalid.

Using Tokens

Once your client has a token and expiration date, it can make API requests directly to Factual. In order to make requests to Factual:

  1. Ensure that the expiration date for the token has not passed. If it has, your client-side code should be prepared to ask your server for a new token, which it will have to fetch from Factual.
  2. Insert the valid token into the Authorization header as an OAuth 2.0 Bearer token.

For example, if the token is XTH4sYzIjP5cG6RzqSoi, the header would look like:

GET /geopulse/designs/ HTTP/1.1
Host: api.factual.com
Authorization: Bearer XTH4sYzIjP5cG6RzqSoi

Refreshing Tokens

If the token has expired, your server simply needs to make a new request to the token API with the appropriate user id. Factual will return a new token.

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/ List deployments
/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/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?tags=tags Tag a deployed build (for capacity management)

Below, you will find comprehensive documentation on each API call.

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 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
Response Data Parameters

Parameters within the response.data object described above:

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=coke
visibility=star_market,pepsi
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required

1 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 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 an array of individual design objects.

For a full description of all parameters available in each row of this data object, see Get Design: Response Data Parameters above.
JSON array
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


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 Datatype 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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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=coke
visibility=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 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 An array of design objects and their associated metadata.

For a full description of all parameters available in each row of this data object, see Response Data Row Parameters below.
JSON array
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
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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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 deployment id that was returned by the request for the build to be activated.
  • 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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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=coke
visibility=star_market,pepsi
 status Status of the deployment: activated, deactivated, or requested

For a full description of the various deployment statuses, see Deployment Status Enumeration below.
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 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 An array of deployment objects. JSON Array
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
Response Data 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

For a full description of the various deployment statuses, see Deployment Status Enumeration below.
String (enumeratred)
“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”
download_path
(DEPRECATED)
URL to download the deployed file. Not available for all deployment target types String (URL)
https://api.factual.com/geopulse/deployments/factual_dap/f144789c-6cb6-48a8-a5aa-3ab1e052e2a2/download
download_paths Array of download path objects associated with the current deployment. Not available for all deployment target types. One download path per associated data source in the deployed build. JSON Array
download_paths[row].source The data source of the download path String
“factual_dap”
download_paths[row].download_path URL to download the deployed file for the particular source String (URL)
https://api.factual.com/geopulse/deployments/factual_dap/f144789c-6cb6-48a8-a5aa-3ab1e052e2a2/download
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.
Example
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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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.
  • 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/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/activate 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
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
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”


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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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 desctructive 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 deployment id.
  • 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
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“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.

Grant

Introduction

The Geopulse Grant API enables you to apply a visibility tag to a Geopulse design in order to provide a filter for visibility. This is typically used for creating custom permissions in the Geopulse Embed use case, and as a flexible tagging system, permissions can be as simple or complex as needed.

By default, a standard Geopulse user will be able to see all of the designs that they have created themselves. However, many Factual partners have requirements for more granular, complex permissions on designs. For example, perhaps a Factual partner wants all users from the same company to see any design created by a user from that same company. This can be done using visibility tags in conjunction with server side API calls made by a Geopulse Admin level user. See Geopulse Management APIs for a more complete example of how to use visibility tags to retrieve lists of designs filtered by visibility tag.

Example worflow:

  • User A is a member of “Sample, Inc.”
  • User A creates a new Geopulse Proximity Design, “Design XYZ” and saves it.
  • Factual Partner uses the Grant API call to assign “Design XYZ” the visibility tag “sample_inc”
  • When User B comes to the Factual Partner UI, partner makes a server side call to list all designs associated with the tag “sample_inc”, and lists these as valid designs for User B to interact with.

Note: Maintaining the mapping between which users should be associated with which visibility tags is dependent on the Fatual partner system. Factual does not maintain mappings of users to visibility tags.

Endpoint

https://api.factual.com/geopulse/designs/(design id)/grant

Syntax

  • This endpoint only accepts POST requests.
  • Replace (design id) with the id of the design you are granting visibility tags to.
  • 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/8d7d2d1f-7ee8-428e-9d27-23d7cfbf6c5d/grant HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 67

visibility=pepsi%2Cdiet_coke&KEY=my_api_key

Request Parameters

Parameter name Description Datatype Example
 visibility Set of sluggified tags that you are assigning visibility for this design for. comma-delimited array of Strings
visibility=pepsi,diet_coke
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

Notes on the visibility parameter:

  • visibility takes one or more tags which will be appled to the design. When accessing the deployment list API using the corresponding visibility tag, only designs with matching tags will be returned.
  • When tags are appled to visibility, the results will be OR’d. In otherwords, if a design has tags A and B applied to it, and you attempt to list all designs with tags B or C, the design will be returned as a match.
  • Pre-existing tags will be overwritten.
  • visibility tags will be sluggified.
    • Acceptable tags may use the characters a-z, A-Z, 0-9, and the underscore (‘_’) character. No whitespace is allowed.
    • Unacceptable characters will be transformed as follows: punction characters will be ignored, unicode letters transformed to the closest Arabic match, white space trimmed from the ends or replaced by underscore otherwise.
  • visibility tags are case sensitive.

Response Parameters

Parameter name Description Datatype Example
version The version of the API response. Integer
4
status The status of the response. String
“ok”
Example response:
{
  "version": 4,
  "status": "ok"
}