Faraday's Lookup API targets can be used in real-time contexts to retrieve any payload element set on the associated Scope.
To get started with a lookup API target, read the quickstart on real-time predictions.
https://api.faraday.ai/v1/targets/<YOUR TARGET ID>/lookup using the
- 200 OK
- 400 Bad Request — Target configuration errors, request validation errors
HTTP Bearer Authentication is required. Use a request header like:
Authorization: Bearer <YOUR API KEY>
Below are all available identifiers. Use as many as are known.
person_first_nameString — First name (if known).
person_last_nameString — Last name (if known).
house_number_and_streetString — Physical address including number and street.
cityString — City.
stateString — 2-letter postal abbreviation.
postcodeString — 5-digit zipcode. Send as string to preserve leading zeroes.
phoneString — E.123-compliant string representation.
You must provide at least one of the following combinations to retrieve a match:
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.
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_percentileInteger — Percentile of the propensity score for the indicated Outcome.
fdy_outcome_<UNDERSCORED_OUTCOME_ID>_propensity_probabilityFloat — Propensity probability for the indicated Outcome.
fdy_persona_set_<UNDERSCORED_PERSONA_ID>_idString — The UUID of the Persona within the given Persona Set that the individual belongs to.
fdy_persona_set_<UNDERSCORED_PERSONA_ID>_nameString — The name of the Persona within the given Persona Set that the individual belongs to.
fdy_cohort_<UNDERSCORED_COHORT_ID>_memberBoolean — 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.
match_typeString — A plain English description of the identifiers used to match to an individual, if a match was found. See match_types for more information.
errorString — 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."
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,
PATCHyour target so that
modeis one of the valid values in the error response.
Target must haveoptions.type = 'lookup_api'`` 400 Bad Request — Configuration error,
PATCHyour target so that
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_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:
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.