/api

Documentation and resources for the Faraday API

Faraday Inform API (v3) - legacy read-only API

Base URL: https://api.faraday.ai/v3

Difference between Faraday Inform API (v3) and Faraday API (v1)

This document refers to the Faraday Inform API (knowable by prefix v3), a read-only legacy product with a maximum rate of 5 calls per second per API token.

The Faraday API (knowable by prefix v1 even though it is more modern) is a different product with different capabilities.

Feature Faraday API (v1) Legacy Faraday Inform API (v3) - this document
Configure Faraday resources ✅
Read predictions up to 100/second ✅
Get probability in addition to percentile ✅
Get metadata about Faraday resources ✅
Read predictions up to 5/second ✅
Faraday Salesforce Lightning Connector ✅
Return average conversion rates per Outcome ✅

Households: scoring, persona assignment, data append, and segment membership

Endpoint

POST /v3/households or GET /v3/households

Response codes

  • 200 OK
  • 404 Household could not be found

Request parameters

Auth

HTTP Basic Authentication is the preferred method.

  • username — empty
  • password — Your account's API key

You can also put the API key in the parameters as api_key if that's easier.

Identity
  • 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
  • match_algorithm "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.
  • allow_reverse_email "true" or omit Deprecated — Ignored. Reverse email is always attempted if email provided.
  • allow_reverse_phone "true" or omit Deprecated — Ignored. Reverse phone is an account-level setting that cannot be changed for individual lookups.
Operations
  • outcome_ids Array of UUIDs — Use the specified Outcomes to score the matching household.
  • persona_set_ids Array of UUIDs — Use the specified Persona Sets to assess the matching household.
  • outcome_id UUID String Deprecated— Use the specified Outcome to score the matching household. Use outcome_ids instead.
  • persona_set_id UUID String Deprecated— Use the specified Persona Set to score the matching household. Use persona_set_ids instead.
  • campaign_id UUID String Deprecated — Use the specified Campaigns to score the matching household.
  • audiences Array of UUID Strings Deprecated — 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 Deprecated — Append the specified FIG attributes, each identified by its handle.
Response settings

Callers can specify a prefix and/or postback_url, or a configuration for posting to Hubspot. In order to post to Hubspot, we require both a vid and a configuration of fields to post.

  • include_average_conversion_rates Boolean — Enable returning average conversion rates.
  • 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.
  • hubspot Object — A mapping of fdy_field_name to hubspot_field_name. For example: 
      {
    'persona_name': 'hb_persona_name',
    'persona_id': 'hb_persona_id',
    'house_number_and_street': 'hb_house_num'
  }
  • vid String — ID of the hubspot customer to update with fields in hubspot object. The Hubspot webhook provides this automatically.

Response

Elements
  • attributes Object — Each key is the handle of a requested FIG attribute. Each corresponding value is that attribute extracted from FIG.
  • audiences Object — 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.
  • city String — Normalized from request.
  • email String — Passed through from request.
  • error String — Error message.
  • house_number_and_street String — Normalized from request.
  • latitude Float — Decimal geocoded latitude.
  • longitude Float — Decimal geocoded longitude.
  • match_algorithm "loose", "tight", or omit — Passed through from request.
  • match_code String — Match code.
  • person_first_name String — Passed through from request.
  • person_last_name String — Passed through from request.
  • postcode String — Normalized from request.
  • state String — Normalized from request.
  • persona_sets Object - Each key is a Persona Set ID. Each corresponding value is an Object containing a Persona ID and a Persona Name.
  • scores Object — Each key is an Outcome ID. Each corresponding value is the score.
  • score_percentiles Object — Each key is an Outcome ID. Each corresponding value is the score percentile (if available).
  • warnings Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
  • average_conversion_rates Object — Each key is an Outcome ID. Each corresponding value is its average conversion rate (if available). include_average_conversion_rates must be set to true.

Deprecated elements

Still supported.

  • persona_id String — ID of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the response.
  • persona_name String — Name of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the response.
  • score Float — The probability that the matched household will achieve the indicated Outcome/Campaign.
  • score_percentile Float — Score percentile within the cross-validation dataset (if available).

Scores

Endpoint

POST /v3/scores or GET /v3/scores

Deprecated. Use /v3/households instead, with the same inputs and outputs.

Match codes

All endpoints return a match_code of the form oFLX. Each letter stands for something.

  • F — first name used
  • L — last name used
  • P — full name used
  • N — nickname used (e.g. Bill matching to William)
  • E — exact address used
  • X — address prefix used (e.g., 123 N Blount St matching to 123 N Blount St Apt 403... it's a prefix)

The letters i (tight), o (default), and a (loose) refer to the match algorithm, but this can be seen more easily from the match_algorithm return value.

Examples:

  • oP-E — Default mode full name exact address match. "Seamus Abshere 1038 E Dayton St" matched "Shamus Abshere 1038 E Dayton St".
  • oFLX — Default mode first and last name address prefix match. "Devin/Abshere 123 N Blount St" matched to "Devon/Abshere 123 N Blount Apt 403".
  • a-LX — Loose mode last-name only prefix match. "Seamus Abshere 123 N Blount St" matched to "Devin Abshere 123 N Blount Apt 403".

Copyright

Copyright 2023 Faraday