API documentation
Base URL: https://api.faraday.io/
Households: scoring, persona assignment, data append, and segment membership
Note: The Faraday API has recently deprecated all endpoints except /v3/households
. It now accepts an outcome_id
or campaign_id
(deprecated) parameter so that scores can be shown. In other words, /v3/households
is the only recommended endpoint for new projects.
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
— emptypassword
— 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.outcome_ids
Array of UUIDs — Use the specified Outcomes' currently promoted Models to score the matching household.campaign_id
UUID String Deprecated — Use the specified Campaign's currently promoted Model to score the matching household.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
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.
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 offdy_field_name
tohubspot_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 inhubspot
object. The Hubspot webhook provides this automatically.
Response
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.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.postcode
String — Normalized from request.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
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).state
String — Normalized from request.warnings
Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
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 usedL
— last name usedP
— full name usedN
— nickname used (e.g. Bill matching to William)E
— exact address usedX
— 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 2022 Faraday