Skip to content
Documentation and resources for the Faraday API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
readme.md match code examples Jul 23, 2019

readme.md

API documentation

Base URL: https://api.faraday.io/

Households: 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
  • allow_reverse_email "true" or omit — Allow Faraday to attempt an email match if matching by physical address fails. You may incur charges.
  • allow_reverse_phone "true" or omit — Allow Faraday to attempt a phone match if matching by physical address fails. You may incur charges.
  • 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.
Operations
  • audiences Array of UUID Strings — 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.
Response settings
  • 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.

Response

  • 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_algorithm "loose", "tight", or omit — Passed through from request.
  • match_code String — Match code.
  • 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.
  • warnings Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
  • error String — Error message.
  • email String — Passed through from request.

Scores

Endpoint

POST /v3/scores or GET /v3/scores

Response codes

  • 200 OK

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
  • allow_reverse_email "true" or omit — Allow Faraday to attempt an email match if matching by physical address fails. You may incur charges.
  • allow_reverse_phone "true" or omit — Allow Faraday to attempt a phone match if matching by physical address fails. You may incur charges.
  • 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.
Operations
  • outcome_id UUID String — Use the specified Outcome's currently promoted Model to score the matching household.
  • campaign_id UUID String Deprecated — Use the specified Campaign's currently promoted Model to score the matching household.
Response settings
  • 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.

Response

  • 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_algorithm "loose", "tight", or omit — Passed through from request.
  • match_code String — Match code.
  • score Float — The probability that the matched household will achieve the indicated Outcome/Campaign.
  • warnings Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
  • error String — Error message.
  • email String — Passed through from request.

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 2019 Faraday

You can’t perform that action at this time.