Lookup API specification

Faraday's Lookup API targets can be used in real-time contexts to retrieve any payload element set on the associated Scope.

Faraday's Lookup API targets can be used in real-time contexts to retrieve any payload element set on the associated Scope.

Use Lookup API as your 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 API 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.

Constructing a request

URL

You can access the Lookup API using a URL like

https://api.faraday.ai/v1/targets/<YOUR TARGET ID>/lookup

Replace <YOUR TARGET ID> with the ID of a Lookup API Target which you have created on your account. Instructions follow later in this document.

Methods

The Lookup API supports the only the POST method. All lookup parameters should be sent in the request body as JSON.

Headers

The following headers are required:

  • Authorization String — HTTP Bearer authentication. You can find your API key in the Faraday dashboard.
  • Content-Type String — Must be application/json.

Payload elements

Below are all available identifiers which can be used to reverse match. Use as many as are known; Faraday will use as many as possible to match to an individual.

  • 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.
  • longitude Float — Longitude of a point which will be used to reverse geocode an address.
  • latitude Float — Latitude of a point which will be used to reverse geocode an address.
  • search_radius Float — When reverse geocoding, limit the distance to search for an address, in meters. If unspecified, then no limit will be applied.

You must provide at least one of the following combinations to retrieve a match:

  • house_number_and_street + city + state
  • house_number_and_street + postcode
  • email
  • phone + person_last_name
  • longitude + latitude

Multiple identifiers can be used in a single identity_sets array to find a match for a person. If the root-level identifier does not find a match, Faraday will use each included identifier until a match is found.

{
  "first_name": "Jane",
  "last_name": "Doe"
  identity_sets: [
    {
      "house_number_and_street": "123 Main St",
      "city": "Burlington"
      "state": "VT"
    },
    {
      "house_number_and_street": "505 Pine St",
      "city": "Burlington"
      "state": "VT"
    }
  ]
}

Example request

Here is an example request using cURL:

curl --request POST \
     --url https://api.faraday.ai/v1/targets/<YOUR TARGET ID>/lookup \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR API KEY' \
      --data '{
          "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",
          "email": "john.doe@example.com"
}'

Response

If the target is correctly configured and the request is valid, then a 200 will be returned. If there was a configuration or validation error, then a 4XX will be returned with an error message.

Response codes

  • 200 OK
  • 400 Bad Request — Target configuration errors, request validation errors

Elements - 200 response

All provided identifiers will be returned in the response unmodified. The following elements might also be returned, depending on the payload elements set on the associated Scope and whether or not a match was made. If you have set a custom structure on your target, then the names you specify for any given payload element will be used instead.

  • fdy_outcome_<UNDERSCORED_OUTCOME_ID>_propensity_percentile Integer — Percentile of the propensity score for the indicated Outcome.
  • fdy_outcome_<UNDERSCORED_OUTCOME_ID>_propensity_probability Float — Propensity probability for the indicated Outcome.
  • fdy_persona_set_<UNDERSCORED_PERSONA_ID>_persona_id String — The UUID of the Persona within the given Persona Set that the individual belongs to.
  • fdy_persona_set_<UNDERSCORED_PERSONA_ID>_persona_name String — The name of the Persona within the given Persona Set that the individual belongs to.
  • fdy_cohort_<UNDERSCORED_COHORT_ID>_member Boolean — Whether the individual is a member of the indicated Cohort.
  • fdy_attribute_[fig]_<TRAIT_NAME> Any — The value of the indicated attribute. If the attribute is Faraday-provided trait, then the trait name will be prefixed with fig_, if the attribute is client-provided, then it will be un-prefixed. e.g. fdy_attribute_fig_age or fdy_attribute_clientfield.
  • match_type String — A plain English description of the identifiers used to match to an individual, if a match was found. See match_types for more information.
  • error String — If the request was valid but no match was found, then this element will be present and will read "Could not match an identity with the provided information."

Error messages

Non-200 responses will always include an error element. The following errors are possible:

  • Could not find target/<TARGET_ID> 404 Not Found — The target does not exist.
  • Invalid target mode: <TARGET MODE> 400 Bad Request — The target does not have a valid mode set. Configuration error, PATCH your target so that mode is one of the valid values in the error response. Please note: at this time only Identified mode is allowed.
  • Target must have options.type = 'lookup_api' 400 Bad Request — Configuration error, PATCH your target so that options.type is lookup_api.
  • Missing required fields: <MISSING FIELDS> 400 Bad Request — The request is missing one or more required fields. See the Identity section for a list of all required identifier groups.
  • Invalid identifiers: <INVALID IDENTIFIERS> 400 Bad Request — The request contains one or more excess or invalid identifiers. See the Identity section for a list of all valid identifiers.

Example response

Given the request above, here is an example response:

{
  "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",
  "email": "john.doe@example.com",
  "match_type": "email_full_name",
  "fdy_outcome_<UNDERSCORED_OUTCOME_ID>_propensity_probability": 0.6187726151430029,
  "fdy_outcome_<UNDERSCORED_OUTCOME_ID>_propensity_percentile": 85,
  "fdy_persona_set_<UNDERSCORED_PERSONA_ID>_persona_id": "persona id",
  "fdy_persona_set_<UNDERSCORED_PERSONA_ID>_persona_name": "persona name",
  "fdy_cohort_<UNDERSCORED_COHORT_ID>_member": true,
  "fdy_attribute_fig_age": 35
}

Matching & match types

Match types

The match_type element will be present in the response if a match was found. It is a plain English description of the identifiers used to match to an individual.

It will be one of the following values:

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

Optimizing match rates

Match types in the section above correspond to groups of identifiers which Faraday uses to cache payload information. When a request is received, we extract as many of the above match keys as possible from the request data and try them all in succession until a match is found, or available keys are exhausted. For example, if you provide an email and a last name, then the API will first attempt to match on email and last name, and if that fails, it will attempt to match on email alone. If that fails, then no match will be returned.

Due to this behavior described above, match rates tend to be highest when you provide as many identifiers as possible, as it greatly expands the number of potential combinations available to secure a precise identity match.

Quickstart

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

🚧️

This tutorial assumes that you have already taken all the necessary steps to create an outcome and are ready to deploy predictions. If you do not have any predictions, then follow the instructions in another quickstart or recipe and then come back to this tutorial.

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 'Content-Type: 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.

Test lookups

Before a scope is out of preview mode you may want to run a test call against the lookup_api target and see what a repsonse might look like.

You may do that by using the following test identity:

curl --request POST \
    --url https://api.faraday.ai/v1/targets/0c043777-c52a-45f1-b919-bfff0adc2bdc/lookup \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{
    "person_first_name": "Michael",
    "person_last_name": "Faraday",
    "house_number_and_street": "123 Science Dr",
    "city": "Phoenix",
    "state": "Farazona",
    "postcode": "00043",
    "email": "michael.faraday@example.com"
  }'

You will receive a response that depicts key information to be retrieved:

{
  "person_first_name": "Michael",
  "person_last_name": "Faraday",
  "house_number_and_street": "123 Science Dr",
  "city": "Phoenix",
  "state": "Farazona",
  "postcode": "00043",
  "email": "michael.faraday@example.com",
  "fdy_outcome_15315de0_cc34_43c4_8e56_66e22555fa33_propensity_probability": "0.44617022183997196",
  "fdy_outcome_8584ce05_9642_475c_9170_ce055b9b748e_propensity_percentile": "89",
  "match_type": "email_full_name"
}