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

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

• persona_name String — Name of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the response.
• persona_id String — ID of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the 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.
• 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

• persona_name String — Name of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the response.
• persona_id String — ID of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the 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.
• 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