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    

Geopulse Embed

A common request from Factual’s Geopulse partners is to provide a way to allow users to access Factual’s Geopulse Proximity and Audience designer tools directly in a partner UI. For example, perhaps a DSP wants to allow users to create new Factual targeting without ever having to leave their platform. Geopulse Embed allows partners to implement this type of interaction.

This guide, with frequent references to the relevant Geopulse APIs, describes how to integrate with Facutal to provide Geopulse tools embedded entirely in your platform.

General Workflow

The workflow to enable a full embeddable UI involves several steps, including authentication, listing saved Geopulse desgns, launching the embeddable designer UI, and showing a user available targeting for actually attaching it to a campaign.

For the purposes of this workflow, there are a few basic requirements.

  • You must have a user account set up with Factual that can be granted “admin” level permissions to the Geopulse tools. The API key associated with this user account will be necessary for making many of the API calls described in the below workflow, and the required user will be noted as admin when necessary.
  • Your user account must be associated with an “organization” on Factual’s system. Any users you create on Factual’s system will be contained within this organization, ensuring that users on your system, their permissions, and their designs do not get mingled with other users generated by other partners using Geopulse Embed. A standard user account, generated in the embed process (e.g. one of your end users) will be noted as user in the workflow below.

If you have not already gotten set up with the necessary pieces to fulfill the above requirements, please contact Factual.

1. Authentication

Authentication is the first major step in the embed workflow. To use the Geopulse embed, you must allow individual users on your system to interact with Factual’s system. Factual makes this simple to do with the token Token API:

  • User comes to your platform wherever Factual Geopulse Embed is implemented.
  • Upon initial page load, admin makes a server side call to Factual’s Token API to generate a token for the user, using email as the primary key.
    • If the user exists already on Factual’s system as a member of your organization, the user’s unique token will be returned.
    • If the user does not already exist on Factual’s system as a member of your organization, Factual will immediately create a new user and then return that user’s token.
  • You now have a user token that will be necessary to use in subsequent steps. For more information on how to use the token for authenticating API calls, see using tokens in the Geopulse API docs.

2. Generating Lists of Designs

You now have a user token that you can use to make client side API calls to Factual on behalf of your user. The next step is to provide your user with a list of designs to edit and interact with. There are two ways to do this that vary slightly in complexity and flexibility:

  • Generate a list of designs from the user token:
    • Make a call to the List Designs API call with the user token.
    • This call can be made over the client side, and it will provide a list of designs created by the user.
    • By default, a user on Factual’s system will have the ability to edit and manage only designs that they have created themselves. For some Factual partners, this restriction is totally fine. However, if you need more flexible permissions (like allowing multiple users to see the same designs), see the method below.

Many Factual partners request more granular permissions to enable scenarios like “allow all users from the same company to see the same designs” or “allow a particular user to see anything created by anyone in their company”. This is enabled by the method described here in conjunction with visibility tags and the Grant API.

  • Generating a list of designs from the admin key and visibility tags:
    • Make a call to the List Designs API call with your admin key, and send the parameter “visibility” with any visibility tags you want to filter the list of results by.
    • By using your admin key, you are able to get access to any design created by any user on your platform, so you must take care (i.e. properly use visibility tags) to avoid accidentally showing the entire list of designs to any user.
    • Factual strongly recommends that you implement the “List Design API call” on the server side, so that your visibility tags are not exposed to end users.

At the end of this step, you should be able to show a list of editable Geopulse designs for your user, whether it is designs explicitly owned by that user, or owned by a number of users exposed through visibility tags.

3. Launching an Embeddable Designer

The core piece of the Geopulse Embed interation, allowing users to create new designs and edit existing designs without leaving your platform, is also arguably the simplest. The only work required is to launch an iframe with the standard Factual designer url (e.g. https://www.factual.com/geopulse/proximity/designer) and a few additional parameters. Typically this iframe would appear in a modal window, overlayed on top of the page on your platform where Factual designs are listed.

Embeddable UI for new Geopulse Proximity design:

<iframe src="https://www.factual.com/geopulse/proximity/designer?embedded=true&factual_api_token=USER_TOKEN"></iframe>

Embeddable UI for existing Geopulse Proximity design:

<iframe src="ttps://www.factual.com/geopulse/proximity/designer/DESIGN_ID?embedded=true&factual_api_token=USER_TOKEN"></iframe>

Embeddable UI for new Geopulse Audience design:

<iframe src="https://www.factual.com/geopulse/audience/designer?embedded=true&factual_api_token=USER_TOKEN"></iframe>

Embeddable UI for existing Geopulse Audience design:

<iframe src="https://www.factual.com/geopulse/audience/designer/DESIGN_ID?embedded=true&factual_api_token=USER_TOKEN"></iframe>

Explanation of parameters:

Parameter Name


Your generated user token. This will ensure that anything done in the designer UI will be as that user. Saved designs will be associated with them and all permissions will be based on that specific user account.


This flag lets Factual know that the designer is being used in an embedded fashion, and it will remove any particular UI elements that may cause issues in an embedded use case, such as links to other pages on the Factual website.

In the above examples, be sure to replace DESIGN_ID and USER_TOKEN with an actual design ID and your generated user token respectively.

At the end of this step, you should be able to launch a designer UI from your own platform.

4. Building Designs and Managing Deployment

For Factual targeting to be useful, a design must be built and then deployed so that it can be called in real time from your platform. Managing this process is done through Factual’s Geopulse Management APIs. For a complete description of the process, see the lifecycle section of the Geopulse Management API docs.

There are a number of ways to integrate the build/deploy process into your platform. For example, it can be done without your users ever needing to be aware of it, where you manage the process entirely, and use metadata (like start date and end date) from your users’ campaigns to determine when to build designs, deploy them, and ultimately remove the deployments from your software.

Factual can help you walk through the multiple scenarios for how to manage the Geopulse build and deployment process, but here, we’ll describe a simple version as one example scenario:

  • When listing designs for the user, each design may be associated with a “build” button, which triggers a call to Factual’s Request Build API using the user token and noting that the build should be automatically deployed when it completes.
  • This build call sends the build request onto Factual’s cluster, and Factual begins processing the build request, to create a final targeting file.
  • Upon completion of the build, the build will be automatically deployed to your endpoint and be available for targeting.

Over time, as custom builds are no longer being used for campaigns, you can use the Geopulse Management APIs to remove unused builds from your software, saving memory over the long term.

At the end of this step, you should be able to create, save, and build/deploy Geopulse designs all through your platform.

5. Generating Lists of Available Targeting

The last piece of a successful embed solution is providing your users with a way to attach Factual targeting to campaigns that they are creating. This is typically implemented by using the List Deployments API call. This API call can give you a list of all builds actively deployed to your platform along with their associated targeting information (like targeting code).

The recommended method of allowing Factual users to attach targeting is to use the “List Deployments” call in conjunction with visibility tags, as described in step 2, above. This allows you to granularly control what targeting a given user on your platform should have access to attach to their campaigns.

The basic workflow follows:

  • Using your admin key, make a call to deployments with the “visibility” parameter set to the visibility tags you wish to filter your results by. This will return a list of deployments with associated design information (like name, owner, etc.) and their list of sets and associated targeting codes.
  • Use the results to generate a list of available targeting with a label of “design name” and a value of “design id”
  • For any targetable design, the user should be able to expand that design to select individual “targeting codes” from the list, allowing for more granular targeting, and depending on the capabilities of your platform, complex logic.
    • For example, in an ideal setup, a user would be able to create a Proximity design with sets for many different fast food brands at different radii, representing different distances to the location.
    • This could allow a user to do something like only bid on a potential impression when it falls at a McDonald’s but within 1000m of a Burger King (e.g. target when “Fast Food:at_mcdonalds” AND “Fast Food:burger_king_1000”, where “Fast Food” is the design and “at_mcdonalds” and “burger_king_1000” are the targeting codes), creating some interesting possibilities for geo-conquesting and other logical targeting.
  • From this list of available targeting, the user should be able to associate targeting with a campaign on your system and begin using Factual targeting in production.

On your platform, you should store both the design_id and the specified targeting_code that your user wants to target. This is the recommended way of checking for targeting matches on both Geopulse Proximity and Geopulse Audience, as it allows for both granularity (targeting_code) and uniqueness (design_id), ensuring that targeting codes do not clash in designs created by entirely different users.

At the end of this step you should have a complete, working Geopulse Embed solution, allowing your users to get easy access to customized geo-targeting with Proximity and Audience. Please reach out to Factual with any questions.