Faraday API
Overview
Faraday exposes a REST-style API for retrieving and manipulating data.
Versions
- API version
v1is currently in alpha
Contributing
-
Want a new resource exposed in the API? Submit a pull request documenting the change you'd like to see.
-
Have a question or other feedback? Open an issue.
Basics
All API requests share some common components.
Environments
Two environments are offered for developer convenience:
-
The production environment performs all requests against production data, returns complete responses, and incurs charges where applicable. Use of your production API key will perform API operations on the production environment.
-
The test environment uses fake random data, will not make any changes, and does not incur charges. Use of your test API key will perform API operations on the test environment.
URLs
API requests use the following base URL:
https://api.faraday.io/v1
HTTPS is required for all requests.
Authentication
In your Faraday settings, go to the Integrations section. You will see two API tokens provided, one for the production environment, and one for test. See the section on Environments for more information.
Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.
$ curl https://api.faraday.io/v1/audiences \
-u sk_test_E6V2sxvyYD5PX8a1tqqNE3eG:Headers
Required headers are in bold.
| Header | Description | Example |
|---|---|---|
Accept |
Indicates desired response format. Currently only JSON is supported. | Accept: application/json |
Content-Type |
Required for POST requests. Indicates the request format. Currently only JSON is supported. | Content-Type: application/json |
X-Request-Id |
If this header is set with a UUID in the request, it will be returned as-is in the response. Potentially useful for handling parallelized API consumption. | X-Request-Id: 3fe4594e-10f5-46e8-8ab3-28b812a3fc47 |
Parameters
The Faraday API accepts parameters in the query string (for GET-style requests) and as JSON in the request body (for POST-style requests).
Special request value types
The request-level documentation below occasionally refers to a special type for a parameter.
Segment specification
A segment describes the group of all known Faraday households in a given geography that meet certain criteria. A segment specification serializes this description into a JSON object:
| Top-level key | Description | Example |
|---|---|---|
geography |
A geography or array of geographies within which the households must be located to be included in the segment. When the array form is used, households must belong to at least one element to be considered in-segment. | [{ "type": "place", "id": 1234 }, { "type": "place", "id": 5678 }] |
criteria |
An object whose key-value pairs are attribute conditions which households must meet to be included in the segment. A household must meet all criteria to be considered in-segment. | [{ "household_income": [80000, 120000], "credit_rating": [700, "Infinity"]}] |
Geography
A geography is used to describe a geographical area. There are currently five types of geographic areas that Faraday supports: named places, zip codes, radius around current customers, radius around points of interest, and drawn areas. Indicate geography type with the type field and use additional fields described below to identify the area itself.
The most common geography type is a named place. Faraday maintains a list of named places.
The format for each of the supported geography types:
- Named place:
{ "type": "place", "id": "01234" }.idmust be a string to allow for leading zeroes. - Zip code:
{ "type": "zipcode", "id": "05401" } - Custom shape
{ "type": "custom_shape", "shape": {...} }. The provided `shape must be valid GeoJSON. - Radius around customers (must be combined with a non-radius geography type)
{ "type": "customer_proximity", "distance": 1000 }.distanceis radius in meters. - Radius around points of interest (must be combined with a non-radius geography type)
{ "type": "poi_proximity", "distance": 1000, "points_of_interest": [123, 456]}
Note that radiuses only work when combined with a named place, zip code, or custom shape.
Attribute condition
An attribute condition is generally one element of a JSON object listing several household criteria. Each such element must conform to the format appropriate for the household attribute in question:
-
Continuously variabled attributes are specified with a range:
"household_income": [80000, 120000]. For unbounded ranges, use"-Infinity"(no minimum) and"Infinity"(no maximum). To specifically look for null values (no coverage), use"NULL". -
Boolean attributes:
"gardener": false. To specifically look for null values (no coverage), use"NULL"; if non-truthy,"FALSE_OR_NULL". -
Categorical attributes are specified with an array of valid desired categories:
"house_style": ["Ranch", "Townhouse"]. Households must belong to one of the listed categories to meet the condition. To specifically look for null values (no coverage), use"NULL".
Responses
All responses will arrive as JSON. Your requests should include the Accept: application/json header to acknowledge this.
Requests
- Retrieve a list
- Create a list
- Retrieve an audience
- Create an audience
- Record a customer
- Record a lead
- Record a prospect
- Upload a file
- List household attributes
- List products
Retrieve a list
Status: In development
A Faraday list is the means to contact some or all members of an audience. Your list can be pushed to a vendors and/or downloaded.
Request
The first type of request retrieves the list's details:
GET https://api.faraday.io/v1/lists/57a257d0-752a-4a02-b039-93e56aeac77e
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/jsonParameters
None
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for this list. | 105b15a0-d539-4b13-861f-ccdb35b0b6ea |
audience_id |
The internal Faraday ID (UUID) for the audience this list belongs to. | 84d64b50-4610-4b7c-ba27-76af665480a8 |
contact |
The types of contact information requested for the list. | ["postal"] |
status |
The current state of the list as it builds: pending, building, or ready |
ready |
size |
The size of the list. Only included for ready lists. |
500 |
download_url |
The URL to a downloadable list CSV. Only included for ready lists. Note that the URL may contain encoded Unicode characters and should be properly parsed as JSON before using. |
http://example.com/list.csv |
Note that your code may need to poll this resource until it achieves ready state when attempting to retrieve the list's size or download URL.
Create a list
Status: In development
Request
POST https://api.faraday.io/v1/audiences/18b68e74-1953-4784-a37b-58e0c7d54961/lists
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/jsonParameters
Required parameters in bold.
| Parameter | Type | Description | Example |
|---|---|---|---|
max_size |
Integer | The maximum size desired for the list. | 500 |
contact |
Array of Strings | Which types of contact information to include, if any. Allowed values are postal and telephone. |
["postal"] |
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for this list. | 105b15a0-d539-4b13-861f-ccdb35b0b6ea |
audience_id |
The internal Faraday ID (UUID) for the audience this list belongs to. | 84d64b50-4610-4b7c-ba27-76af665480a8 |
contact |
The types of contact information requested for the list. | ["postal"] |
status |
The current state of the list as it builds: pending, building, or ready |
building |
Retrieve an audience
Status: In development
A Faraday audience is a fixed group of specific households within a geography that meet a set of criteria. Audiences are the basis for lists and must be created first.
Request
GET https://api.faraday.io/v1/audiences/3bdbf545-d5d8-4ddb-b813-f954a1882cc2
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/jsonParameters
None.
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) of the audience | 3bdbf545-d5d8-4ddb-b813-f954a1882cc2 |
status |
The audience's current state (pending, building, or ready) |
ready |
segment |
The geography and criteria used to construct this audience, delivered as a segment specficiation | { "geography": [ { "type": "place", "id": 1234 } ], "criteria": { "household_income": [80000, "Infinity"]} } |
build_details |
A summary of the approach used to arrive at the audience's size | { "max_size": 10000, "predict": true } |
size |
The size of the audience—only available when ready |
9434 |
reachability |
A summary of the audience's reachability by channel—only available when ready |
{ "postal": 9434, "telephone": 4993, "email": 3542, "social": 4853 } |
Create an audience
Status: In development
Request
POST https://api.faraday.io/v1/audiences
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/jsonParameters
Required parameters in bold.
| Parameter | Type | Description | Example |
|---|---|---|---|
segment |
Segment specification | Describes the population segment from which to draw households when building this audience | { "geography": [ { "type": "place", "id": 1234 } ], "criteria": { "household_income": [80000, "Infinity"]} } |
name |
String | A name for this audience | Wealthy Brooklynites |
product_id |
String | The ID of a Faraday product | 15c13b63-250b-4c24-96a5-955ccd7f3ae0 |
predict |
Boolean | Adjusts predictive targeting, which will select households in your segment with the highest likelihood of purchasing your product first. null (default) uses standard predictive targeting, true enables additional modeling approaches for potential improvements in accuracy (at the expense of time), and false disables predictions. |
true |
max_size |
Integer | Faraday will add households as possible from your segment to the audience until this size is reached | 10000 |
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for your newly created audience | 8c52b329-33b5-4d3a-b0ab-1aed32db633a |
status |
The state of the audience as it undergoes its build: pending, building, ready |
building |
segment |
The geography and criteria used to construct this audience, delivered as a segment specficiation | { "geography": [ { "type": "place", "id": 1234 } ], "criteria": { "household_income": [80000, "Infinity"]} } |
build_details |
A summary of the approach used to arrive at the audience's size | { "max_size": 10000, "predict": true } |
size |
The size of the audience—only available when ready |
9434 |
reachability |
A summary of the audience's reachability by channel—only available when ready |
{ "postal": 9434, "telephone": 4993, "email": 3542, "social": 4853 } |
Note that your code should poll the newly created audience until it reaches ready state before continuing with further actions on this audience, such as building lists.
Record a customer
Status: Live
A customer is a household that has purchased your product or service, whether or not as a result of Faraday-facilitated outreach. Reporting your customers to Faraday improves predictions and allows you to visualize and target your customers with the platform.
Request
POST https://api.faraday.io/v1/customers
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/jsonParameters
Required parameters in bold.
| Parameter | Type | Description | Example |
|---|---|---|---|
person |
String | The combined first and last name of the customer. | Michael Faraday |
house_number_and_street |
String | The physical address of the customer. | 123 Main St. |
city |
String | The customer's city. | Burlington |
state |
String | The 2-letter postal abbreviation of the customer's state. | VT |
postcode |
String | The customer's 5-digit zip code. (Use a string to avoid issues with leading zeroes.) | 05402 |
product_id |
String | The UUID of a recognized Faraday product indicating the purchase that was made by the customer. | b9dfbba4-bdc3-47dd-8006-2ee84b4861d4 |
became_customer_at |
String | A ISO8601 date/time string indicating when the purchase was made. Uses the current time if missing. | 20151025T223451Z |
attributes |
String or Array of strings | Instructs Faraday to include (append) one or more attributes of the customer—if a match to a known household can be made. Each attribute should be a valid Faraday household attribute; unrecognized attributes will be ignored and added to the Faraday-Unrecognized-Attributes response header. |
["household_income", "credit_rating"] |
qualify |
Segment specification | Instruct Faraday to qualify this customer by determining its inclusion in the specified segment, if the customer can be matched with high confidence to a known Faraday household. | { "geography": [ { "type": "place", "id": 1234 } ], "criteria": { "household_income": [80000, "Infinity"]} } |
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for your newly submitted customer. | 4a991134-2677-46c5-b01e-298582982fa0 |
customer_id |
(DEPRECATED; see id) The internal Faraday ID (UUID) for your newly submitted customer. |
4a991134-2677-46c5-b01e-298582982fa0 |
household_id |
The internal Faraday ID (UUID) for the known household that the customer matched to (if a match could be made). Note that Faraday household IDs are ephemeral and should be neither persisted nor relied upon; we include them for debugging purposes. | 2e231a5a-e3f7-4a09-b4fc-21289f7debcf |
person |
Null unless provided in request. The name of record for the known household your customer matched to, if such a match could be made. | Michael Faraday |
attributes |
Requested household-level attributes, if any were provided and a match could be made. | { "household_income": 110000, "credit_rating": 690 } |
qualify |
A boolean indicating whether the matched household (if any) is included in the segment specified in your request (if provided). | true |
disqualifications |
The reason for a false value in the qualify response value. Only included when qualify is false. |
[{"household_income": "expected between 50000.0 and Infinity, but outside"}] |
Record a lead
Status: Live
In Faraday parlance, a lead is a household that has expressed interest in your product or service, often by responding to marketing—whether or not the campaign was facilitated by Faraday.
Request
POST https://api.faraday.io/v1/leads
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/jsonParameters
Required parameters in bold.
| Parameter | Type | Description | Example |
|---|---|---|---|
person |
String | The combined first and last name of the lead. | Michael Faraday |
house_number_and_street |
String | The physical address of the lead. | 123 Main St. |
city |
String | The lead's city. | Burlington |
state |
String | The 2-letter postal abbreviation of the lead's state. | VT |
postcode |
String | The lead's 5-digit zip code. (Use a string to avoid issues with leading zeroes.) | 05402 |
product_id |
String | The UUID of a recognized Faraday product indicating the category of interest for the lead. | b9dfbba4-bdc3-47dd-8006-2ee84b4861d4 |
became_lead_at |
String | A ISO8601 date/time string indicating when the lead emerged. Uses the current time if missing. | 20151025T223451Z |
attributes |
String or Array of strings | Instructs Faraday to include (append) one or more attributes of the lead—if a match to a known household can be made. Each attribute should be a valid Faraday household attribute; unrecognized attributes will be ignored and added to the Faraday-Unrecognized-Attributes response header. |
["household_income", "credit_rating"] |
qualify |
Segment specification | Instruct Faraday to qualify this lead by determining its inclusion in the specified segment, if the lead can be matched with high confidence to a known Faraday household. | { "geography": [ { "type": "place", "id": 1234 } ], "criteria": { "household_income": [80000, "Infinity"]} } |
predict |
Boolean | Instruct Faraday to predict the likelihood that the lead will purchase the specified product, if a high-confidence match can be made to a known Faraday household. | true |
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for your newly submitted lead. | 4a991134-2677-46c5-b01e-298582982fa0 |
lead_id |
(DEPRECATED; see id) The internal Faraday ID (UUID) for your newly submitted lead. |
4a991134-2677-46c5-b01e-298582982fa0 |
household_id |
The internal Faraday ID (UUID) for the known household that the lead matched to (if a match could be made). Note that Faraday household IDs are ephemeral and should be neither persisted nor relied upon; we include them for debugging purposes. | 2e231a5a-e3f7-4a09-b4fc-21289f7debcf |
person |
Null unless provided in request. The name of record for the known household your lead matched to, if such a match could be made. | Michael Faraday |
attributes |
Requested household-level attributes, if any were provided and a match could be made. | { "household_income": 110000, "credit_rating": 690 } |
predict |
A number between -1 and 1 indicating the likelihood that the matched household (if such a match was possible) will purchase the product specified in the request. Positive values indicate that the household is predicted to purchase; negative values indicate the the household is predicted to reject. The absolute value of the number indicates Faraday's confidence in its prediction. A null response value indicates that a prediction was impossible. | 0.89 |
qualify |
A boolean indicating whether the matched household (if any) is included in the segment specified in your request (if provided). | true |
disqualifications |
The reason for a false value in the qualify response value. Only included when qualify is false. |
"household_income: expected between 50000 and Infinity, but outside" |
Record a prospect
Status: Live
In Faraday parlance, a prospect is a household that has been contacted (or will shortly be contacted) but where an outcome is not yet known.
Request
POST https://api.faraday.io/v1/prospects
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/jsonParameters
Required parameters in bold.
| Parameter | Type | Description | Example |
|---|---|---|---|
person |
String | The combined first and last name of the prospect. | Michael Faraday |
house_number_and_street |
String | The physical address of the prospect. | 123 Main St. |
city |
String | The prospect's city. | Burlington |
state |
String | The 2-letter postal abbreviation of the prospect's state. | VT |
postcode |
String | The prospect's 5-digit zip code. (Use a string to avoid issues with leading zeroes.) | 05402 |
product_id |
String | The UUID of a recognized Faraday product indicating the category of interest for the prospect. | b9dfbba4-bdc3-47dd-8006-2ee84b4861d4 |
became_prospect_at |
String | A ISO8601 date/time string indicating when the prospect emerged. Uses the current time if missing. | 20151025T223451Z |
attributes |
String or Array of strings | Instructs Faraday to include (append) one or more attributes of the prospect—if a match to a known household can be made. Each attribute should be a valid Faraday household attribute; unrecognized attributes will be ignored and added to the Faraday-Unrecognized-Attributes response header. |
["household_income", "credit_rating"] |
qualify |
Segment specification | Instruct Faraday to qualify this prospect by determining its inclusion in the specified segment, if the prospect can be matched with high confidence to a known Faraday household. | { "geography": [ { "type": "place", "id": 1234 } ], "criteria": { "household_income": [80000, "Infinity"]} } |
predict |
Boolean | Instruct Faraday to predict the likelihood that the lead will purchase the specified product, if a high-confidence match can be made to a known Faraday household. | true |
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for your newly submitted prospect. | 4a991134-2677-46c5-b01e-298582982fa0 |
prospect_id |
(DEPRECATED; see id) The internal Faraday ID (UUID) for your newly submitted prospect. |
4a991134-2677-46c5-b01e-298582982fa0 |
household_id |
The internal Faraday ID (UUID) for the known household that the prospect matched to (if a match could be made). Note that Faraday household IDs are ephemeral and should be neither persisted nor relied upon; we include them for debugging purposes. | 2e231a5a-e3f7-4a09-b4fc-21289f7debcf |
person |
Null unless provided in request. The name of record for the known household your prospect matched to, if such a match could be made. | Michael Faraday |
attributes |
Requested household-level attributes, if any were provided and a match could be made. | { "household_income": 110000, "credit_rating": 690 } |
predict |
A number between -1 and 1 indicating the likelihood that the matched household (if such a match was possible) will purchase the product specified in the request. Positive values indicate that the household is predicted to purchase; negative values indicate the the household is predicted to reject. The absolute value of the number indicates Faraday's confidence in its prediction. A missing response value indicates that a prediction was impossible. | 0.89 |
qualify |
A boolean indicating whether the matched household (if any) is included in the segment specified in your request (if provided). | true |
disqualifications |
The reason for a false value in the qualify response value. Only included when qualify is false. |
"household_income: expected between 50000 and Infinity, but outside" |
Upload a file
This endpoint can be used to submit bulk CSV data for managed ingestion, such as customer data, marketing lists, and points of interest. A Faraday analyst will inspect your file and may contact you for clarification.
Request
POST https://api.faraday.io/v1/files
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/jsonParameters
Required parameters in bold.
| Parameter | Type | Description | Example |
|---|---|---|---|
url |
String | Publicly accessible URL to the CSV file | https://example.com/mydata.csv |
email |
String | An email address of a valid Faraday user for use in clarification after ingestion | some.user@your_company.com |
Response
| Top-level key | Value description | Example |
|---|---|---|
id |
The internal Faraday ID (UUID) for your newly submitted file. | 4a991134-2677-46c5-b01e-298582982fa0 |
List household attributes
Status: Live
Faraday maintains data on each U.S. household, as many as hundreds of attributes depending on local coverage. This list of attributes changes frequently as new data sources are added.
Request
GET https://api.faraday.io/v1/household_attributes
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/jsonParameters
None.
Response
The response is a JSON array, each element of which is an object with the following structure:
| Top-level key | Description | Example |
|---|---|---|
name |
The snake_case identifier for the attribute |
household_income |
description |
A short human-readable description of the attribute | Household income |
type |
Either continuous (numeric), boolean, or an array of valid categories (each a string) for categorical attributes |
continuous |
List products
Status: Live
Faraday maintains an internal database of products (e.g. "Solar," "Life insurance") to facilitate predictive model creation. Some API requests require the ID of a product; use this request to find that ID.
Request
GET https://api.faraday.io/v1/products
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/jsonParameters
None.
Response
The response is a JSON array, each element of which is an object with the following structure:
| Top-level key | Description | Example |
|---|---|---|
id |
The internal ID of the product. | 07224389-ae7a-4b0e-b3c8-49e110e9c285 |
name |
The Sentence case name of the product. |
Life insurance |