{"id":24698662,"url":"https://github.com/faradayio/api","last_synced_at":"2026-01-05T03:43:04.573Z","repository":{"id":136464431,"uuid":"44642561","full_name":"faradayio/api","owner":"faradayio","description":"Documentation and resources for the Faraday API","archived":false,"fork":false,"pushed_at":"2023-12-01T15:37:42.000Z","size":44,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-01-27T04:29:31.069Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://api.faraday.io","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faradayio.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-10-21T00:20:41.000Z","updated_at":"2022-02-18T14:25:24.000Z","dependencies_parsed_at":"2023-04-21T07:02:26.050Z","dependency_job_id":null,"html_url":"https://github.com/faradayio/api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faradayio%2Fapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faradayio","download_url":"https://codeload.github.com/faradayio/api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244902936,"owners_count":20529114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-27T04:29:42.279Z","updated_at":"2026-01-05T03:43:04.544Z","avatar_url":"https://github.com/faradayio.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## Faraday Inform API (v3) - legacy read-only API\n\n**Base URL:** `https://api.faraday.ai/v3`\n\n## Difference between Faraday Inform API (v3) and Faraday API (v1)\n\nThis document refers to the Faraday Inform API (knowable by prefix `v3`), a read-only legacy product with a maximum rate of 5 calls per second per API token.\n\nThe [Faraday API](https://faraday.ai/developers/reference) (knowable by prefix `v1` even though it is more modern) is a different product with different capabilities.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eFeature\u003c/th\u003e\n\u003cth\u003e\u003ca href=\"https://faraday.ai/developers/reference\"\u003eFaraday API (v1)\u003c/a\u003e\u003c/th\u003e\n\u003cth\u003eLegacy Faraday Inform API (v3) - this document\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eConfigure Faraday resources\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eRead predictions up to 100/second\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eGet probability in addition to percentile\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eGet metadata about Faraday resources\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eRead predictions up to 5/second\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ca href=\"https://docs.google.com/document/d/1nThkUeqJROPjJEs8E9zy4vnzRajLQIV66SiHmujT-z0/edit#heading=h.7k6rycn881a\"\u003eFaraday Salesforce Lightning Connector\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eReturn average conversion rates per Outcome\u003c/td\u003e\n\u003ctd\u003e\u003c/td\u003e\n\u003ctd\u003e✅\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Households: scoring, persona assignment, data append, and segment membership\n\n#### Endpoint\n\n`POST /v3/households` or `GET /v3/households`\n\n#### Response codes\n\n- **200** OK\n- **404** Household could not be found\n\n#### Request parameters\n\n##### Auth\n\nHTTP Basic Authentication is the preferred method.\n\n- `username` — empty\n- `password` — Your account's API key\n\nYou can also put the API key in the parameters as `api_key` if that's easier.\n\n##### Identity\n\n- `person_first_name` _String_ — First name (if known).\n- `person_last_name` _String_ — Last name (if known).\n- `house_number_and_street` _String_ — Physical address including number and street.\n- `city` _String_ — City.\n- `state` _String_ — 2-letter postal abbreviation.\n- `postcode` _String_ — 5-digit zipcode. Send as string to preserve leading zeroes.\n- `phone` _String_ — E.123-compliant string representation.\n- `email` _String_ — E-mail address.\n\n##### Matching settings\n\n- `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.\n- `allow_reverse_email` _\"true\" or omit_ **Deprecated** — Ignored. Reverse email is always attempted if email provided.\n- `allow_reverse_phone` _\"true\" or omit_ **Deprecated** — Ignored. Reverse phone is an account-level setting that cannot be changed for individual lookups.\n\n##### Operations\n\n- `outcome_ids` _Array of UUIDs_ — Use the specified Outcomes to score the matching household.\n- `persona_set_ids` _Array of UUIDs_ — Use the specified Persona Sets to assess the matching household.\n- `outcome_id` _UUID String_ **Deprecated**— Use the specified Outcome to score the matching household. Use `outcome_ids` instead.\n- `persona_set_id` _UUID String_ **Deprecated**— Use the specified Persona Set to score the matching household. Use `persona_set_ids` instead.\n- `campaign_id` _UUID String_ **Deprecated** — Use the specified Campaigns to score the matching household.\n- `audiences` _Array of UUID Strings_ **Deprecated** — Check to see if the matched household falls within each of the specified Audiences. Each specified Audience must have been previously created with Explore.\n- `attributes` _Array of Strings_ **Deprecated** — Append the specified FIG attributes, each identified by its handle.\n\n##### Response settings\n\nCallers can specify a `prefix` and/or `postback_url`, _or_ a configuration for posting to Hubspot. In order to post to Hubspot, we require both a `vid` and a configuration of fields to post.\n\n- `include_average_conversion_rates` _Boolean_ — Enable returning average conversion rates.\n- `prefix` _String_ — Prefix each standard response key with the specified string.\n- `postback_url` _String_ — In addition to the standard HTTP response, also POST the response to the specified URL.\n- `hubspot` _Object_ — A mapping of `fdy_field_name` to `hubspot_field_name`. For example:\n  ```js\n    {\n      'persona_name': 'hb_persona_name',\n      'persona_id': 'hb_persona_id',\n      'house_number_and_street': 'hb_house_num'\n    }\n  ```\n- `vid` _String_ — ID of the hubspot customer to update with fields in `hubspot` object. The Hubspot webhook provides this automatically.\n\n#### Response\n\n##### Elements\n\n- `attributes` _Object_ — Each key is the handle of a requested FIG attribute. Each corresponding value is that attribute extracted from FIG.\n- `audiences` _Object_ — 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.\n- `city` _String_ — Normalized from request.\n- `email` _String_ — Passed through from request.\n- `error` _String_ — Error message.\n- `house_number_and_street` _String_ — Normalized from request.\n- `latitude` _Float_ — Decimal geocoded latitude.\n- `longitude` _Float_ — Decimal geocoded longitude.\n- `match_algorithm` _\"loose\", \"tight\", or omit_ — Passed through from request.\n- `match_code` _String_ — Match code.\n- `person_first_name` _String_ — Passed through from request.\n- `person_last_name` _String_ — Passed through from request.\n- `postcode` _String_ — Normalized from request.\n- `state` _String_ — Normalized from request.\n- `persona_sets` _Object_ - Each key is a Persona Set ID. Each corresponding value is an Object containing a Persona ID and a Persona Name.\n- `scores` _Object_ — Each key is an Outcome ID. Each corresponding value is the score.\n- `score_percentiles` _Object_ — Each key is an Outcome ID. Each corresponding value is the score percentile (if available).\n- `warnings` _Array of Strings_ — Each warning is a human-interpretable message indicating an issue with the API request.\n- `average_conversion_rates` _Object_ — Each key is an Outcome ID. Each corresponding value is its average conversion rate (if available). `include_average_conversion_rates` must be set to true.\n\n#### Deprecated elements\n\nStill supported.\n\n- `persona_id` _String_ — ID of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the response.\n- `persona_name` _String_ — Name of the persona that individual belongs to. Requires personas. Talk to your CSM if this is not in the response.\n- `score` _Float_ — The probability that the matched household will achieve the indicated Outcome/Campaign.\n- `score_percentile` _Float_ — Score percentile within the cross-validation dataset (if available).\n\n### Scores\n\n#### Endpoint\n\n`POST /v3/scores` or `GET /v3/scores`\n\nDeprecated. Use `/v3/households` instead, with the same inputs and outputs.\n\n### Match codes\n\nAll endpoints return a `match_code` of the form `oFLX`. Each letter stands for something.\n\n- `F` — first name used\n- `L` — last name used\n- `P` — full name used\n- `N` — nickname used (e.g. Bill matching to William)\n- `E` — exact address used\n- `X` — address prefix used (e.g., 123 N Blount St matching to 123 N Blount St Apt 403... it's a prefix)\n\nThe letters `i` (tight), `o` (default), and `a` (loose) refer to the match algorithm, but this can be seen more easily from the `match_algorithm` return value.\n\nExamples:\n\n- `oP-E` — Default mode full name exact address match. \"Seamus Abshere 1038 E Dayton St\" matched \"Shamus Abshere 1038 E Dayton St\".\n- `oFLX` — Default mode first and last name address prefix match. \"Devin/Abshere 123 N Blount St\" matched to \"Devon/Abshere 123 N Blount Apt 403\".\n- `a-LX` — Loose mode last-name only prefix match. \"Seamus Abshere 123 N Blount St\" matched to \"Devin Abshere 123 N Blount Apt 403\".\n\n## Copyright\n\nCopyright 2023 Faraday\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaradayio%2Fapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaradayio%2Fapi/lists"}