Faraday live predictions API

Know more about your leads and customers with the Faraday live predictions API

Faraday's live prediction API, also known as Inform, has several parameters you can use to know more about your leads and customers.

See the technical documents for request parameters.

Endpoint

https://api.faraday.ai/v3/scores

This endpoint can lookup an individual US consumer and return back

  • lead score

  • churn score

  • persona assessment

  • or any Outcome or Persona Set created on the Faraday app or API

Parameters

api_key  - the account-specific key needed to call either endpoint. Talk to your Account Manager for the production key. A test key is also available.

Test key:
test_fdysec_XXXXXXXXXXXXXXXX
Production key:
prod_fdysec_XXXXXXXXXXXXXXXX

Outcome parameters

outcome_id  - Faraday models all fall under a specific outcome. So, while the model (and subsequently, model_id) may change, the outcome_id will not. In order to get a score in a response, this will need to be included. Talk to your Account Strategist to obtain your outcome_id. An outcome_id looks like 97c89ce6-b878-4e58-8902-61a357e4a2b9 

As long as an outcome_id  is included, a score will be provided if a match is found:

Call

{
  "api_key": "prod_fdysec_XXXXXXXXXXXXXXXX",
  "email": "fake.email@faraday.io",
  "outcome_id": "97c89ce6-b878-4e58-8902-61a357e4a2b9"
}

Response

{
  "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": []
}

Cohort and audience membership

audiences - the audiences parameter on the households endpoint will tell whether an individual falls within a specific Explore audience. Build an audience in Explore, and the URL will provide the audience-specific id. E.g. https://app.faraday.io/explore/map/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Call

{
    "api_key": "prod_fdysec_XXXXXXXXXXXXXXXX",
    "audiences": "[\"889f7b6f-7559-4440-9d2a-0795eb6df807\",\"2493141a-0630-4995-841f-2461dcaf0e69\"]",
    "email": "fake.email@faraday.io",
    "outcome_id": "97c89ce6-b878-4e58-8902-61a357e4a2b9"
}

Response

{
    "audiences": {
        "889f7b6f-7559-4440-9d2a-0795eb6df807": true,
        "2493141a-0630-4995-841f-2461dcaf0e69": false
    },
    "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",
    "state": "VT",
    "warnings": [
        "Zero allowed fields requested"
    ]
}


attributes  - household information can be called using this parameter, simply put the desired fields in an array. Common examples are age, gender, household income to personalize outreach. For the complete list of fields, see the full list in the Traits console.

Call

{
    "api_key": "prod_fdysec_XXXXXXXXXXXXXXXX",
    "attributes": "[\"household_income\",\"age\"]",
    "email": "fake.email@faraday.io"
}

Response

{
    "attributes": {
        "age": 30,
        "household_income": 175000
    },
    "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",
    "state": "VT",
    "warnings": []
}

Persona parameters

If your account is set up with Faraday personas, persona membership can be requested via API. Talk to your Account Strategist to request this functionality. Once they've confirmed that it is set up, the persona_name (and persona_id, just the unique ID associated that persona_name) will automatically be returned.

Call

POST https://api.faraday.io/v3/scores api_key="prod_fdysec_XXXXXXX" outcome_id="c08315c5-1431-4292-8a0e-dfd13906069a" house_number_and_street="123 Fake St" city="Burlington" state="VT"

Response

{
"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"
]
}

Miscellaneous parameters

prefix - adding a prefix  parameter will append a prefix to the fields in the response, so it doesn't overlap with your own data fields. This is particularly useful for e.g. HubSpot workflows:

Call

{
    "api_key": "prod_fdysec_XXXXXXXXXXXXXXXX",
    "email": "fake.email@faraday.io",
    "prefix": "fdy_"
}

Response

{
    "fdy_city": "Burlington",
    "fdy_email": "fake.email@faraday.io",
    "fdy_house_number_and_street": "123 Fake St",
    "fdy_latitude": 12.345,
    "fdy_longitude": -123.456,
    "fdy_match_algorithm": "a--E",
    "fdy_postcode": "05401",
    "fdy_state": "VT",
    "fdy_warnings": []
}