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    

HTTP Server

Getting Started

This document describes the implementation of the Server version of On-Prem. See the On-Prem Overview for a higher-level introduction to On-Prem. Before provisioning servers, see the Hardware Guidance in the On-Prem Overview.

Required Software

The On-Prem HTTP Server is developed and tested against the following system environment:

  • Oracle JDK 7
  • Ubuntu 14.04

The following packages are also required:

  • upstart (installed by default on Ubuntu)
  • cronolog

Use only the Oracle JDK — issues with the SSL implementation of OpenJDK have been encountered in production deployments which can prevent On-Prem from updating its audience and geofence data.


Create a new user

First create a factual user:

$ createuser factual

Download On-Prem Server

Next, download the latest On-Prem Server binary here. Unpack and copy the provided files to /usr/local/factual/outpost.

$ mkdir -p /usr/local/factual/outpost
$ cd /usr/local/factual/outpost
$ wget [download link]
$ tar -xvzf outpost-3.1.4-example.tar.gz
$ cp -a outpost-3.1.4-example/. /usr/local/factual/outpost/

You’ll also want to create the following directory for storing logs:

$ mkdir -p /var/log/factual/outpost

Copy the outpost.conf file provided in the top-level into /etc/init.

$ cp /usr/local/factual/outpost/outpost.conf /etc/init/outpost.conf

Edit your config file

Edit the config.yml file, and add in your Organization ID under the comment “the organization-id for the user”. Your account manager can provide this value upon request.

# the organization-id for the user
  # the credentials for the organization, available via http://factual.com
  api-key: ""
  secret-key: ""

Next configure the values for source that you will pass in to On-Prem. source is the data source/exchange on which the impression originated. Your config.yml file supports aliasing of data sources. This means that you can map the name of the exchange you pass to On-Prem, to the name that Factual uses to refer to that exchange.

The following table provides a mapping of these values:

Data Source/Exchange

Factual Source Value













Per the snippet below, setup your config.yml with your desired data source mappings.

  directory: /tmp/on-prem/test-org
      max-memory: 1
      fields: [designId, targetingCode, dataSource]
      deployment-tags: []
        aerserv: internalAerservName
        mopub: internalMoPubName
        nexage: internalAOLName
        smaato: internalSmaatoName

Using Upstart

We strongly recommend using Upstart. Under normal operation, On-Prem Server should never crash. However, if it should, you can take the simple precaution of using Upstart to help maintain availability in production.

You’ll need to confirm that your server can open a large number of file descriptors, which can be done with the following command:

$ limit nofile 500000 500000

Running the Server

Startup the On-Prem server by running the following command:

$ sudo start outpost

Once the server is running, the following message should appear in /var/log/factual/outpost/outpost.log:

started HTTP server on 8989

If desired, the port can be changed in the outpost.conf file. You can confirm that the server is running by hitting the /zz/health endpoint.

$ curl http://localhost:8989/zz/health

The server can be stopped and restarted with the following commands:

$ sudo stop outpost
$ sudo restart outpost

Testing Responses

Use curl for testing your installation. Remember to wrap the URL in quotes:

Audience test:

$ curl "http://[server]/geopulse/audience?user-id=<device_id>&source=<data_source>"

Proximity test:

$ curl "http://[server]/geopulse/proximity/indices?latitude=40.642875&longitude=-73.782991"

Match Response

Although Proximity and Audience are two different products, with their own specific use cases, On-Prem powers each, or both concurrently. To facilitate integration and onboarding, we’ve designed the response packets to be identical:


JSON Field


Design Name


Name of the Proximity or Audience Design, assigned in the Designer UI.

Design ID


Factual generated unique ID for the Design.

Deployment ID


Factual generated unique ID for the associated deploy of the Design.

Deployment Tags


String tags associated with the deploy of the Design as assigned.

Targeting Code


A string assigned to the Set when designing the Design in the Designer UI. (In deprecated versions this was formerly called the “Group ID”.)

Data Source


Factual provided ID for the associated audience data source. (Audience only)



A map of keys and values describing the matched set within the Design.



JSON payload describing the matched set, available as string or bytes (Proximity only)

See the page on Terminology for detailed descriptions of each return value.

Proximity Response Example:

    "designName": "BigBox",
    "targetingCode": "Costco",
    "deploymentId": "ABCEHGEEG3q45hasdShe",
    "setId": "xyzHGEEG3q45hasdShe"
    "designName": "Electronics",
    "targetingCode": "Best Buy",
    "deploymentId": "ABMnOwHGbdcG3q45haoazq",
    "setId": "xyzHGEqa68Dxhasdhe"

Audience Response Example:

    "designName": "affluent-business-travelers",
    "designId": "17914b5c-899b-434a-b343-cbadec91e7ca",
    "targetingCode": "affluentBiz",
    "deploymentId": "AyoLwbEHGbdcG3q45haoae",
    "setId": "xyzHlQbiqa353q45ha3h9e"
    "designName": "san-diego-moms",
    "designId": "9653e9dd-236d-4c53-8398-ca73a3876343",
    "deploymentId": "ABCEHGbdcGwZqb3q45hao9e8",
    "setId": "xyzHqGExqsa353q45hys5he7"

Updated about a year ago

HTTP Server

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.