Skip to content

faradayio/api

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
February 18, 2022 09:25

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 — 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.
  • 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 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

  • 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 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 2022 Faraday

About

Documentation and resources for the Faraday API

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published