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

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
April 18, 2023 11:39

API documentation

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

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.

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

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

About

Documentation and resources for the Faraday API

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published