API documentation

Base URL: https://api.faraday.io/v3

Households: data append and segment membership

Endpoint

POST /households

Response codes

• 200 OK
• 404 Household could not be found

Request parameters

Auth

• api_key String Required — The API key for the Account within which this request should be made.

Identity

• 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.

Matching settings

• allow_reverse_email "true" or omit — Allow Faraday to attempt an email match if matching by physical address fails. You may incur charges.
• allow_reverse_phone "true" or omit — Allow Faraday to attempt a phone match if matching by physical address fails. You may incur charges.
• match_algorithm "loose", "tight", or omit — By default, Faraday will match a given identity when lastname, normalized address, and postcode match. Tight mode, on the other hand, also requires a firstname match. Choose loose mode to ignore name and match on address only.

Operations

• audiences Array of UUID Strings — Check to see if the matched household falls within each of the specified Audiences. Each specified Audience must have been previously created with Explore.
• attributes Array of Strings — Append the specified FIG attributes, each identified by its handle.

Response settings

• prefix String — Prefix each standard response key with the specified string.
• postback_url String — In addition to the standard HTTP response, also POST the response to the specified URL.

Response

• person_first_name String — Passed through from request.
• person_last_name String — Passed through from request.
• house_number_and_street String — Normalized from request.
• city String — Normalized from request.
• state String — Normalized from request.
• postcode String — Normalized from request.
• latitude Float — Decimal geocoded latitude.
• longitude Float — Decimal geocoded longitude.
• match_algorithm "loose", "tight", or omit — By default, Faraday will match a given identity when normalized address and postcode match exactly and lastname matches closely. Tight mode, on the other hand, requires an exact lastname match. Choose loose mode to ignore name and match on address only.
• attributes Hash — Each key is the handle of a requested FIG attribute. Each corresponding value is that attribute extracted from FIG.
• audiences Hash — Each key is the UUID of a requested Audience. Each corresponding value is a boolean indicating whether the household does or does not belong to that Audience.
• warnings Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
• error String — Error message.

Scores

Endpoint

POST /scores

Response codes

• 200 OK
• 422 Household could not be found

Request parameters

Auth

• api_key String Required — The API key for the Account within which this request should be made.

Identity

• 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.

Matching settings

• allow_reverse_email "true" or omit — Allow Faraday to attempt an email match if matching by physical address fails. You may incur charges.
• allow_reverse_phone "true" or omit — Allow Faraday to attempt a phone match if matching by physical address fails. You may incur charges.
• match_algorithm "loose", "tight", or omit — By default, Faraday will match a given identity when lastname, normalized address, and postcode match. Tight mode, on the other hand, also requires a firstname match. Choose loose mode to ignore name and match on address only.

Operations

• outcome_id UUID String — Use the specified Outcome's currently promoted Model to score the matching household.
• campaign_id UUID String Deprecated — Use the specified Campaign's currently promoted Model to score the matching household.

Response settings

• prefix String — Prefix each standard response key with the specified string.
• postback_url String — In addition to the standard HTTP response, also POST the response to the specified URL.

Response

• person_first_name String — Passed through from request.
• person_last_name String — Passed through from request.
• house_number_and_street String — Normalized from request.
• city String — Normalized from request.
• state String — Normalized from request.
• postcode String — Normalized from request.
• latitude Float — Decimal geocoded latitude.
• longitude Float — Decimal geocoded longitude.
• match_algorithm String — For internal use. Please report this value if you are having matching problems.
• score Float — The probability that the matched household will achieve the indicated Outcome/Campaign.
• warnings Array of Strings — Each warning is a human-interpretable message indicating an issue with the API request.
• error String — Error message.

Copyright

Copyright 2018 Faraday