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.

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.

Endpoint

https://api.faraday.ai/v1/targets/<YOUR TARGET ID>/lookup using the POST method

Response codes

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

Request parameters

Auth

HTTP Bearer Authentication is required. Use a request header like:

Authorization: Bearer <YOUR API KEY>

Identity

Below are all available identifiers. 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.

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

  • house_number_and_street + city + state
  • email
  • phone + person_last_name

Response

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

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:

  • 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>_id String — The UUID of the Persona within the given Persona Set that the individual belongs to.
  • fdy_persona_set_<UNDERSCORED_PERSONA_ID>_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.

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:

  • email_full_name
  • address_full_name
  • phone_full_name
  • email_last_name
  • address_last_name
  • phone_last_name
  • email_only
  • address_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.

← Collaborating with othersObject preservation →