Retrieve real-time predictions

This tutorial will help you understand how create a Faraday lookup API target.

Use a lookup target when you want to retrieve predictions about an individual in your scope in real time. Behind the Scenes, Faraday will make the necessary predictions on everybody in your scope's population and cache them in a high-availability key-value store (KVS). The lookup target wraps that KVS to make it easy to retrieve predictions this way very quickly.

An important note is that predictions are only cached for individuals in the scope's population. If you want to be able to retrieve a prediction about, say, an incoming lead in real time, you must set the scope's population to include everybody who could possibly become a lead. In practice, this is often everyone.

Generate your predictions

First, you'll create a Scope—this is how you tell Faraday which predictions you want on which populations. YOUR_OUTCOME_ID in the below code block refers to the ID of an outcome that you've already created before following this tutorial. Note that you can include as many outcomes and/or persona sets as you like in your payload. The associated predictions will all be included in the eventual lookup API response.

curl --request POST \
     --url https://api.faraday.ai/v1/scopes \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '
{
     "payload": {
          "outcome_ids": [
               "YOUR_OUTCOME_ID"
          ]
     },
     "population": {
          "cohort_ids": []
     },
     "name": "SCOPE_NAME",
     "preview": true
}
'

When this request is successful, you'll get an ID for your scope which you will need in the next step (referred to as YOUR_SCOPE_ID in example requests).

Deploy predictions

To deploy your predictions, you'll need to attach a Target to your scope with publication type lookup_api.

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

}
'

When this request succeeds, you'll get an ID for your target that you will need in the next step (referred to as YOUR_TARGET_ID in example requests).

Check deployment status

Before you can use the deployed API, you need to check whether the resource (and all of its dependencies) are ready. You can do this with the following command:

curl --request GET \
     --url https://api.faraday.ai/v1/targets/YOUR_TARGET_ID \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY'

You should get a response like this:

{
  "resource_type": "targets",
  "id": "YOUR_TARGET_ID",
  "name": "YOUR TARGET NAME",
  "created_at": "2023-07-18T16:34:09.170Z",
  "updated_at": "2023-07-25T03:00:10.629Z",
  "scope_id": "YOUR_SCOPE_ID",
  "representation": {
    "mode": "identified",
    "transform_preset": "default",
    "aggregate": "person"
  },
  "connection_id": "CONNECTION_ID",
  "options": {
    "output_url": "https://api.faraday.ai/v1/targets/YOUR_TARGET_ID/lookup",
    "type": "lookup_api"
  },
  "status": "ready",
  "status_changed_at": "2023-07-25T06:23:20.274Z",
  "last_updated_output_at": "2023-07-25T06:23:20.274Z"
}

If the status field in the response reads ready, then your API is deployed and ready to be used.

Retrieve predictions

Once your target is ready, you can use it to retrieve predictions for individuals. You query the API by providing identifiers for the individual you want to look up like so:

curl --request POST \
     --url https://api.faraday.ai/v1/targets/YOUR_TARGET_ID/lookup \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY'
      --data '{
        "email": "john@example.com",
        "person_first_name": "John",
        "person_last_name": "Doe",
        "house_number_and_street": "123 Main St Apt 1",
        "city": "Anytown",
        "state": "FZ",
        "phone": "1 (555) 555-5555"
}'

Note: The above identifiers are made up and will not actually return a prediction.

If the identity is matched, then you will get a response which includes all request data, plus the predictions for each relevant payload element, along with a match_type which describes which identifiers the lookup used to confirm a match. Here's an example response:

{
  "email": "john@example.com",
  "person_first_name": "John",
  "person_last_name": "Doe",
  "house_number_and_street": "123 Main St Apt 1",
  "city": "Anytown",
  "state": "FZ",
  "phone": "1 (555) 555-5555",
  "match_type": "email_full_name",
  "fdy_outcome_YOUR_OUTCOME_ID_propensity_probability": 0.6187726151430029,
  "fdy_outcome_YOUR_OUTCOME_ID_propensity_percentile": 85
}

For a full specification of lookup API options and behavior, see the API reference.

Matching & match types

In order to successfully match, you must provide at least one of the following combinations of identifiers:

• email
• house_number_and_street + city + state
• phone + last name

If you do not, then the API will return an error with a message indicating that insufficient information was provided. If you provide more than one of the above combinations, then the API will use the combination with the highest confidence to produce a match. While last and first name are not required, it is recommended that you provide them if you have them, as they will always increase the precision of a match.

The match_type field in the response indicates which identifiers were ultimately used to match to an individual. The following match types are possible:

• email_full_name
• address_full_name
• phone_full_name
• email_last_name
• address_last_name
• phone_last_name
• address_only
• email_only

Optimizing match rates

Match rates tend to be highest when you provide as many identifiers as possible. While we can match an identity with as little as an email address, providing the full suite of information will significantly increase the likelihood and precision of a match.