Faraday's API has several parameters you can use to know more about your leads and customers via Inform. We have two main endpoints, and some parameters work for both, while others are specific to one.

Github

See github for request parameters to match off of

Endpoints

https://api.faraday.io/v3/scores - Use this endpoint for Faraday Real-Time Scoring, ranking your leads as they sign-up. Or, score existing customers to determine their likelihood to churn
https://api.faraday.io/v3/households
 - Use this endpoint to get Faraday's household information about your customers: age, gender, marital status, household income, and more.

General parameters

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

Test key:
test_fdysec_XXXXXXXXXXXXXXXX
Production key:
prod_fdysec_XXXXXXXXXXXXXXXX
 

/v3/scores 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 CSM 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": []
}

/v3/households parameters

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 here

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

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:

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


match_algorithm
- this gets returned on every call, and tells you the "level of the match". Faraday has three main levels of matching:

tight - first name, last name, and address
default - last name and address
loose - address only

Additionally, Faraday can match off of phone and email. Talk to your CSM to set your desired match algorithm, and to enable phone/email matching.

Match algorithm can be decoded using the following table:

F = first name used
L = last name used
P = full name (person) used
E = exact address
X = address prefix used (e.g., 123 N Blount St matching to 123 N Blount St Apt 403... it's a prefix)

Did this answer your question?