Legacy predictions API

Faraday's legacy predictions API can be used in real-time contexts to retrieve predefined predictions on individuals, such as:

  • Lead conversion probability
  • Churn probability
  • Persona assignment

... or any other Outcome or Persona Set previously created using the Faraday app or API

This API endpoint is deprecated and will be removed in the future. To migrate to Faraday's newer methodology for retrieving predictions in real time, see the migration section below.

Endpoint

https://api.faraday.ai/v3/households using the POST or GET methods.

Response codes

  • 200 OK
  • 404 Household could not be found

Request parameters

Auth

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

Some combination of fields is required. Use as many as are known.

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

Operations

At least one operation parameter is required.

  • outcome_ids Array of UUIDs — Use the specified Outcomes to score the matching household. To find an Outcome ID, navigate to any Outcome you'd like in your Account in the Faraday app. You'll find its ID in the URL of its detail page. Outcome IDs are UUIDs that look like 97c89ce6-b878-4e58-8902-61a357e4a2b9.
  • persona_set_ids Array of UUIDs — Use the specified Persona Sets to assess the matching household. To find a Persona Set ID, navigate to any Persona Set you'd like in your Account in the Faraday app. You'll find its ID in the URL of its detail page. Persona Set IDs are UUIDs that look like 97c89ce6-b878-4e58-8902-61a357e4a2b9.
  • 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.
  • attributes Array of Strings Deprecated — Append the specified FIG attributes, each identified by its handle. Only available if enabled on your Account.

Advanced settings

Optional.

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

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.

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

These will be removed from responses in the future.

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

Examples

Real-time propensity scoring

POST https://api.faraday.io/v3/scores

{
  "api_key": "prod_fdysec_XXXXXXXXXXXXXXXX",
  "email": "fake.email@faraday.io",
  "outcome_id": "97c89ce6-b878-4e58-8902-61a357e4a2b9"
}
{
  "city": "Burlington",
  "email": "fake.email@faraday.io",
  "house_number_and_street": "123 Fake St",
  "latitude": 12.345,
  "longitude": -123.456,
  "match_algorithm": "a--E",
  "postcode": "05401",
  "score": 0.05924,
  "state": "VT",
  "warnings": []
}

Real-time persona assignment

POST https://api.faraday.io/v3/scores
api_key="prod_fdysec_XXXXXXX" outcome_id="c08315c5-1431-4292-8a0e-dfd13906069a" person_set_id="b28980c9-1d32-4943-bbaf-baf2b1b6d8c6" house_number_and_street="123 Fake St" city="Burlington" state="VT"
{
    "city": "Burlington",
    "house_number_and_street": "123 Fake Street",
    "latitude": 43.08764,
    "longitude": -89.35335,
    "match_algorithm": "default",
    "match_code": "o--E",
    "persona_id": "869efa44-1df9-4373-8e3b-9bab894c71b8",
    "persona_name": "Young urbanites",
    "postcode": "05401",
    "score": 0.09719,
    "state": "VT",
    "warnings": [
        "Zero allowed fields requested"
    ]
}

Migrate to Lookup API

Lookup API targets are Faraday's replacement for the legacy predictions API.

Why migrate?

There are several reasons to migrate to Lookup API targets:

  • Data freshness: Lookup API targets are part of Faraday's resource update graph, so they will automatically be kept up to date whenever you (or Faraday!) updates the underlying data. Legacy API on the other hand requires manual intervention from Faraday support to update.
  • Simplicity: Several parameters which must be passed to the legacy API to define the response are no longer required, as that information is now encoded into the target and underlying scope. For example, to get scores from multiple outcomes and / or rosters in the legacy API, you must pass a list of outcome IDs and a list of persona set IDs. In the lookup API, all scope payload elements will automatically be included in the response, so you no longer need to specify.
  • Prediction richness: Lookup API targets return score probability, which is a more useful metric for determining propensity. See the docs or the blog for more information on score probability.
  • New response payload elements: Lookup API targets can return any payload element on a scope, which means you can now retrieve cohort membership information for a matched identity.
  • Stay up to date: Faraday is constantly improving our predictions and adding new features. The legacy API is no longer being updated, so you will miss out on new features like explainability, bias mitigation, and more if you remain on the legacy system.

How to migrate

Fortunately, migration is straightforward. If you are already using the legacy API, then you already have a scope defined, which you can find either in the Faraday web app on the pipelines page, or you can retrieve it via the scopes API. Both options will be described below.

Migrate from the Faraday web app

First, Navigate to the pipelines page in the Faraday web app.

Next, scroll down to the Deployment section and select the option for Lookup API.

lookup api

Next, select the option for Identified representation and leave individual identification options as One row per person

representation

If you wish, rename payload elements to your liking. Then, click Finish.

structure

You will be brought back to the Pipelines page, which should now show your new deployment:

deployed

Migrate using Faraday's REST API

First, retrieve your scope ID:

curl --request GET \
     --url https://api.faraday.ai/v1/scopes \
     --header "Authorization: Bearer YOUR_API_KEY" \
     --header 'Content-Type: application/json'

If you have the tool jq installed, you can trim the results to just list scope ID and name, which could be useful if you have many scopes:

curl --request GET \
     --url https://api.faraday.ai/v1/scopes \
     --header "Authorization: Bearer YOUR_API_KEY" \
     --header 'Content-Type: application/json' | jq '.[].id + ": " + .[].name'

This will print a list of scope IDs and names like so:

"0398353a-bc15-4502-add6-40e3522d27b6: YOUR_SCOPE_NAME"

Next, create a lookup API target using the scope ID you retrieved above:

curl --request POST \
     --url https://api.faraday.ai/v1/targets \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
      --data '{
        "options": {
          "type": "lookup_api"
        },
        "representation": {
          "mode": "identified",
          "aggregate": "person"
        },
        "scope_id": "YOUR_SCOPE_ID",
        "name": "YOUR TARGET NAME"
}'

Update your request and response handling

Now that you have a lookup API target, you'll need to update your request and response handling to use the new target.

Request

Given this example legacy API request:

curl --request POST \
     --url https://api.faraday.ai/v3/households \
     --header 'Content-Type: application/json' \
     --data '{
        "api_key": "YOUR_API_KEY",
        "person_first_name": "John",
        "person_last_name": "Doe",
        "house_number_and_street": "123 Fake St",
        "city": "Burlington",
        "state": "VT",
        "postcode": "05401",
        "outcome_ids": [
          "0e086c3a-3541-11ee-9b67-d7ea8587ea97",
          "19595bda-3541-11ee-9a09-0b630baf905b"
        ],
        "persona_set_ids": [
          "28682340-3541-11ee-9e0e-b7e6cab78c6d"
        ]
}'

This is the corresponding lookup API request:

curl --request POST \
     --url 'https://api.faraday.ai/v1/targets/YOUR_TARGET_ID/lookup'\
     --header 'Content-Type: application/json' \
      --data '{
          "person_first_name": "John",
          "person_last_name": "Doe",
          "house_number_and_street": "123 Fake St",
          "city": "Burlington",
          "state": "VT",
          "postcode": "05401"
}'

The key changes are:

  • The URL has changed to https://api.faraday.ai/v1/targets/YOUR_TARGET_ID/lookup
  • The api_key parameter is no longer allowed. You must use HTTP Bearer Authentication instead.
  • The outcome_ids and persona_set_ids parameters are no longer allowed. Instead, the target will automatically return all outcomes and persona sets associated with the scope.
  • The match_algorithm parameter is no longer allowed. Instead, the target will automatically use the best possible match algorithm given the input identifiers.
Response

Given this example legacy API response:

{
  "person_first_name": "John",
  "person_last_name": "Doe",
  "house_number_and_street": "123 Fake St",
  "city": "Burlington",
  "state": "VT",
  "postcode": "05401",
  "latitude": 43.08764,
  "longitude": -89.35335,
  "match_algorithm": "default",
  "match_code": "o--E",
  "scores": {
    "0e086c3a-3541-11ee-9b67-d7ea8587ea97": 0.05924,
    "19595bda-3541-11ee-9a09-0b630baf905b": 0.09719
  },
  "score_percentiles": {
    "0e086c3a-3541-11ee-9b67-d7ea8587ea97": 53,
    "19595bda-3541-11ee-9a09-0b630baf905b": 91
  },
  "persona_sets": {
    "28682340-3541-11ee-9e0e-b7e6cab78c6d": {
      "persona_id": "869efa44-1df9-4373-8e3b-9bab894c71b8",
      "persona_name": "Young urbanites"
    }
  }
}

The corresponding lookup API response will be:

{
  "person_first_name": "John",
  "person_last_name": "Doe",
  "house_number_and_street": "123 Fake St",
  "city": "Burlington",
  "state": "VT",
  "postcode": "05401",
  "match_type": "address_full_name",
  "fdy_outcome_0e086c3a_3541_11ee_9b67_d7ea8587ea97_propensity_percentile": 53,
  "fdy_outcome_0e086c3a_3541_11ee_9b67_d7ea8587ea97_propensity_probability": 0.74,
  "fdy_outcome_19595bda_3541_11ee_9a09_0b630baf905b_propensity_percentile": 91,
  "fdy_outcome_19595bda_3541_11ee_9a09_0b630baf905b_propensity_probability": 0.97,
  "fdy_persona_set_28682340_3541_11ee_9e0e_b7e6cab78c6d_persona_id": "869efa44-1df9-4373-8e3b-9bab894c71b8",
  "fdy_persona_set_28682340_3541_11ee_9e0e_b7e6cab78c6d_persona_name": "Young urbanites"
}

The key changes are:

  • The response is now a flat JSON object, rather than a nested object.
  • The match_algorithm and match_code parameters are no longer returned. Instead, the target will automatically use the best possible match algorithm given the input identifiers. This is returned in plain English as match_type.
  • Score is no longer returned, as it has little value on its own. Instead, score_percentile and score_probability are returned.