Documentation and resources for the Faraday API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Faraday API


Faraday exposes a REST-style API for retrieving and manipulating data.


The current version of the API is v3.


  • API version v1 is currently deprecated
  • API version v2 is currently deprecated
  • API version v3 is currently active


  • Want a new resource exposed in the API? Submit a pull request documenting the change you'd like to see.

  • Have a question or other feedback? Open an issue.


All API requests share some common components.


API requests use the following base URL:[VERSION]

The current base URL is:

HTTPS is required for all requests.


Request an API token from Customer Success.

Authentication to the API occurs via the api_key request param.

Special request value types

The request-level documentation below occasionally refers to a special type for a parameter.

Describing Audiences

Some endpoints allow you to specify one or more Audiences (e.g. segment membership in the individuals endpoint). Each element of the Audiences array can describe an Audience in one of two forms:

  1. ID — Give the ID, as a UUID string, of an Audience which has been previously created on the Faraday platform in your Account (e.g. by using Explore interactively).
  2. Definition — Express the from-scratch definition of the Audience in JSON using FIG attributes. For example:
  "household_income": [0, 50000],
  "gardener": true

FIG attributes

Some endpoints allow you to indicate one or more FIG attributes (e.g. appending in the individuals endpoint). Please contact your Customer Success Manager for a data dictionary.


All responses will arrive as JSON.


The v3 API currently supports the following requests:


The Individuals endpoint allows users to query Faraday regarding a single individual, including scoring that individual against one or more Outcomes, determining that individuals membership in one or more segments, and appending data for that individual.


POST /individuals

Response codes

  • 200 OK
  • 404 Individual could not be found

Request parameters

  • api_key String Required — The API key for the Account within which this request should be made.
  • person_first_name String — First name (if known).
  • person_last_name String — Last name (if known).
  • house_number_and_street String — Physical address including number and street.
  • city String — City.
  • state String — 2-letter postal abbreviation.
  • postcode String — 5-digit zipcode. Send as string to preserve leading zeroes.
  • phone String — E.123-compliant string representation.
  • email String — E-mail address.
Matching settings
  • allow_email_match "true" or omit — Allow Faraday to attempt an email match if matching by physical address fails. You may incur charges.
  • allow_phone_match "true" or omit — Allow Faraday to attempt a phone match if matching by physical address fails. You may incur charges.
  • match_tolerance "loose", "tight", or omit — By default, Faraday will match a given identity when lastname, normalized address, and postcode match. Tight mode, on the other hand, also requires a firstname match. Choose loose mode to ignore name and match on address only.
  • audiences Array of Audiences — Check to see if the matched household falls within each of the specified Audiences. Each specified Audience must have been previously created with Explore.
  • attributes Array of Strings — Append the specified FIG attributes, each identified by its handle.
  • outcomes Array of UUID Strings — Use each specified Outcome's currently promoted Model to score the matching household.
Response settings
  • response_prefix String — Prefix each standard response key with the specified string.
  • postback_url String — In addition to the standard HTTP response, also POST the response to the specified URL.


  • person_first_name String — Passed through from request.
  • person_last_name String — Passed through from request.
  • house_number_and_street String — Normalized from request.
  • city String — Normalized from request.
  • state String — Normalized from request.
  • postcode String — Normalized from request.
  • latitude Float — Decimal geocoded latitude.
  • longitude Float — Decimal geocoded longitude.
  • match_code String — For internal troubleshooting purposes.
  • attributes Hash — Each key is the handle of a requested FIG attribute. Each corresponding value is that attribute extracted from FIG.
  • audiences Hash — Each key is the UUID of a requested Audience. Each corresponding value is a boolean indicating whether the household does or does not belong to that Audience.
  • outcomes Hash — Each key is the ID of an Outcome this household was scored against. The corresponding value is the probability that the matched household will achieve this Outcome.
  • warnings Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
  • error String — Error message.


Copyright 2018 Faraday