{ "openapi": "3.1.0", "info": { "version": "", "contact": { "email": "apisupport@spokeo.com" } }, "tags": [ { "name": "Name Search", "description": "**Endpoint name**: `https://api.spokeo.com/v5/names`\n\n{% partial file=\"/_partials/descriptions/name/name_intro.md\" /%}\n\n

Required Parameters

\n\nProvide at least one name and an additional identifying field.\n\n- `first_name` (string) - The person's first name. _(Conditionally Required)_\n- `last_name` (string) - The person's last name. _(Conditionally Required)_\n\n{% partial file=\"/_partials/descriptions/name/name_response_and_usage.md\" /%}\n\n# Name Data Overview\n\n| Name Data Field | Total Count | Fill Rate |\n| ---------------------------------- | ------------- | --------- |\n| `person.id` | 465,240,211 | 100.00% |\n| `person.names` | 465,240,211 | |\n| `person.names.first_name` | 975,522,850 | 100.00% |\n| `person.names.middle_name` | 703,815,798 | 80.82% |\n| `person.names.last_name` | 975,522,850 | 100.00% |\n| `person.names.full_name` | 975,522,850 | 100.00% |\n| `person.names.suffix` | 43,440,360 | 6.93% |\n| `person.names.name_type` | 975,522,850 | |\n| `person.dob_month` | 421,477,978 | 90.59% |\n| `person.dob_year` | 435,542,862 | 93.62% |\n| `person.is_deceased` | 28,920,044 | 6.22% |\n| `person.addresses.state` | 2,763,486,918 | 98.81% |\n| `person.addresses.street_address` | 2,763,486,604 | 98.81% |\n| `person.addresses.city` | 2,763,486,918 | 98.81% |\n| `person.addresses.latitude` | 2,763,359,570 | 98.81% |\n| `person.addresses.longitude` | 2,763,359,570 | 98.81% |\n| `person.addresses.zip` | 2,763,486,918 | 98.81% |\n| `person.emails.email` | 1,454,869,597 | 68.63% |\n| `person.emails.email_is_new` | 191,976,546 | 17.10% |\n| `person.phones.phone` | 1,936,335,349 | 86.25% |\n| `person.phones.phone_is_new` | 207,515,858 | 19.55% |\n| `person.work_history` | | 17.30% |\n| `person.work_history.company_name` | 200,532,496 | 16.99% |\n| `person.work_history.title` | 188,448,502 | 15.10% |\n| `person.schools` | | 14.67% |\n| `person.schools.name` | 589,545,911 | 14.67% |\n| `person.schools.type` | 578,432,174 | 14.60% |\n| `person.schools.location` | 475,780,528 | 11.98% |\n" }, { "name": "Person ID Search", "description": "**Endpoint name**: `https://api.spokeo.com/v5/person_id/{id}`\n\n{% partial file=\"/_partials/descriptions/person-id.md\" /%}\n\n# Person Data Overview\n\n| Person Data Field | Total Count | Fill Rate |\n| ---------------------------------------------------- | ------------- | --------- |\n| `person.id` | 465,240,211 | 100.00% |\n| `person.names` | 465,240,211 | |\n| `person.names.first_name` | 975,522,850 | 100.00% |\n| `person.names.middle_name` | 703,815,798 | 80.82% |\n| `person.names.last_name` | 975,522,850 | 100.00% |\n| `person.names.full_name` | 975,522,850 | 100.00% |\n| `person.names.suffix` | 43,440,360 | 6.93% |\n| `person.names.name_type` | 975,522,850 | |\n| `person.gender` | 451,923,902 | 97.14% |\n| `person.birth.dob_month` | 421,477,978 | 90.59% |\n| `person.birth.dob_year` | 435,542,862 | 93.62% |\n| `person.death.is_deceased` | 28,920,044 | 6.22% |\n| `person.death.death_month` | 28,283,360 | 6.08% |\n| `person.death.death_year` | 28,283,360 | 6.08% |\n| `person.death.death_age` | 28,283,360 | 6.08% |\n| `person.marital_status` | 180,440,876 | 38.78% |\n| `person.divorce.divorce_month` | 329,590 | 0.07% |\n| `person.divorce.divorce_year` | 329,590 | 0.07% |\n| `person.marriage.marriage_month` | 8,030,306 | 1.73% |\n| `person.marriage.marriage_year` | 8,030,306 | 1.73% |\n| `person.addresses.is_current` | 2,763,486,918 | 98.81% |\n| `person.addresses.state` | 2,763,486,918 | 98.81% |\n| `person.addresses.street_address` | 2,763,486,604 | 98.81% |\n| `person.addresses.city` | 2,763,486,918 | 98.81% |\n| `person.addresses.county` | 2,763,486,318 | 98.81% |\n| `person.addresses.latitude` | 2,763,359,570 | 98.81% |\n| `person.addresses.longitude` | 2,763,359,570 | 98.81% |\n| `person.addresses.zip` | 2,763,486,918 | 98.81% |\n| `person.addresses.property.zoned_use` | 2,186,773,339 | 95.10% |\n| `person.addresses.property.use_type` | 1,755,413,744 | 91.59% |\n| `person.addresses.property.market_value` | 1,533,206,478 | 88.02% |\n| `person.addresses.property.last_sold_date` | 1,611,956,327 | 88.63% |\n| `person.addresses.property.living_area` | 1,639,137,002 | 89.00% |\n| `person.addresses.property.bath_total_count` | 1,405,257,254 | 82.76% |\n| `person.addresses.property.bath_partial_count` | 322,288,585 | 38.15% |\n| `person.addresses.property.bed_count` | 1,174,474,724 | 74.93% |\n| `person.addresses.property.area_lot` | 1,604,744,215 | 89.14% |\n| `person.addresses.property.year_built` | 1,624,655,608 | 88.60% |\n| `person.addresses.property.ownership_start_date` | 1,629,305,732 | 89.04% |\n| `person.addresses.property.last_sold_price` | 1,185,857,341 | 75.66% |\n| `person.addresses.property.sellability.retail_score` | 1,618,703,148 | 89.86% |\n| `person.addresses.property.source_count` | 1,755,423,522 | 91.59% |\n| `person.addresses.property.source_date` | | 98.81% |\n| `person.addresses.property.owners_count` | 1,712,063,966 | 90.98% |\n| `person.addresses.property.valuations.date` | 1,743,387,327 | |\n| `person.addresses.property.valuations.market_value` | 1,743,387,327 | |\n| `person.emails.email` | 1,454,869,597 | 68.63% |\n| `person.emails.domain_name` | 1,454,869,597 | 68.63% |\n| `person.emails.source_count` | 1,454,869,597 | 68.63% |\n| `person.emails.source_date` | | 68.63% |\n| `person.emails.confidence_score` | 1,454,869,597 | 68.63% |\n| `person.emails.is_new` | 191,976,546 | 17.10% |\n| `person.social_records` | 6,615,469,130 | 57.63% |\n| `person.social_profiles.network_name` | 5,011,103,415 | 57.63% |\n| `person.social_profiles.url` | 6,768,643,133 | 57.63% |\n| `person.social_profiles.photo_url` | 3,062,722,150 | 49.97% |\n| `person.social_profiles.display_name` | 6,615,469,130 | 55.15% |\n| `person.social_profiles.last_seen_date` | 6,768,647,300 | 45.83% |\n| `person.social_profiles.source_count` | 6,768,647,300 | |\n| `person.phones.phone` | 1,936,335,349 | 86.25% |\n| `person.phones.activity_status` | 1,707,860,530 | 86.25% |\n| `person.phones.line_type` | 1,936,335,349 | 86.25% |\n| `person.phones.city` | 1,936,335,349 | 86.25% |\n| `person.phones.state` | 1,936,335,349 | 86.25% |\n| `person.phones.listing_type` | 1,936,335,349 | 86.25% |\n| `person.phones.carrier` | 1,936,335,349 | 86.25% |\n| `person.phones.source_count` | 1,936,335,349 | 86.25% |\n| `person.phones.is_valid` | | 86.25% |\n| `person.phones.reputation.risk_level` | 687,780,457 | 63.00% |\n| `person.phones.source_date` | | 86.25% |\n| `person.phones.time_zone_name` | 1,936,335,349 | 86.25% |\n| `person.phones.confidence_score` | 1,936,335,339 | 86.25% |\n| `person.phones.start_date` | 1,328,893,616 | 86.25% |\n| `person.phones.end_date` | 1,328,893,616 | 86.25% |\n| `person.phones.is_new` | 207,515,858 | 19.55% |\n| `person.work_history` | | 17.30% |\n| `person.work_history.is_current` | | 9.25% |\n| `person.work_history.start_date` | 158,929,338 | 11.03% |\n| `person.work_history.end_date` | 113,748,535 | 7.68% |\n| `person.work_history.company_name` | 200,532,496 | 16.99% |\n| `person.work_history.title` | 188,448,502 | 15.10% |\n| `person.schools` | | 14.67% |\n| `person.schools.name` | 589,545,911 | 14.67% |\n| `person.schools.start_date` | 344,636,942 | 7.55% |\n| `person.schools.type` | 578,432,174 | 14.60% |\n| `person.schools.location` | 475,780,528 | 11.98% |\n| `person.schools.majors.name` | 3,211,081 | 8.12% |\n| `person.certifications` | | 2.29% |\n| `person.certifications.name` | 61,306,868 | 2.29% |\n| `person.certifications.organization` | 52,452,505 | 2.29% |\n| `person.certifications.start_date` | 46,241,902 | 1.80% |\n| `person.certifications.end_date` | 32,833,303 | 1.68% |\n| `person.languages.language` | 145,140,370 | 31.20% |\n| `person.languages.proficiency` | 5,415,658 | 0.56% |\n| `person.historical_records` | | 36.60% |\n| `person.historical_records.record_type` | 3,652,562,053 | 36.60% |\n| `person.historical_records.event_year` | 3,625,748,354 | 36.56% |\n| `person.historical_records.event_month` | 3,461,209,445 | 36.44% |\n" }, { "name": "Phone Search", "description": "**Endpoint name**: `https://api.spokeo.com/v5/phones`\n\n{% partial file=\"/_partials/descriptions/phone.md\" /%}\n" }, { "name": "Address Search", "description": "**Endpoint name**: `https://api.spokeo.com/v5/addresses`\n\n{% partial file=\"/_partials/descriptions/address.md\" /%}\n" }, { "name": "Email Search", "description": "**Endpoint name**: `https://api.spokeo.com/v5/emails`\n\n{% partial file=\"/_partials/descriptions/email.md\" /%}\n" }, { "name": "Username Search", "description": "**Endpoint name**: `https://api.spokeo.com/v5/usernames`\n\n{% partial file=\"/_partials/descriptions/username.md\" /%}\n" } ], "servers": [ { "url": "https://api.spokeo.com/v5" } ], "paths": { "/names": { "get": { "tags": [ "Name Search" ], "summary": "Search for a Person by Name", "operationId": "names", "description": "#### Supported Query Combinations\n\n##### Queries must satisfy the following conditions:\n 1. Provide at least one name:\n - `first_name` or\n - `last_name`\n\n 2. Provide at least one of the following additional fields:\n - the other name (`first_name` or `last_name`, whichever wasn't used in the condition above)\n - `middle_name`\n - `phone`\n - `email`\n - `street`\n - `city`\n - `state`\n - `relative_first_name`\n - `relative_last_name`\n - `age_min`\n - `age_max`\n

\n##### Valid Examples\n- `first_name` + `last_name`\n- `first_name` + `email`\n- `last_name` + `phone`\n- `first_name` + `state`\n- `first_name` + `city`\n- `first_name` + `relative_last_name`\n- `last_name` + `middle_name` + `state`\n- `first_name` + `city` + `distance`\n- `first_name` + `street` + `unit`\n- `first_name` + `age_min`\n- `last_name` + `age_max`\n- `first_name` + `age_min` + `age_max`\n

\n##### Invalid Examples\n- `first_name` only\n- `last_name` only\n", "security": [ { "api_key": [] } ], "parameters": [ { "in": "query", "name": "first_name", "description": "The first name of the person you are searching for.\n\nConditionally required. Either provide both `first_name` and `last_name`, or provide this field with additional identifying fields.\n", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "middle_name", "description": "The middle name of the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "last_name", "description": "The last name of the person you are searching for.\n\nConditionally required. Either provide both `first_name` and `last_name`, or provide this field with additional identifying fields.\n", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "street", "description": "A street address associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "unit", "description": "A unit or suite number associated with the person you are searching for.\nMust be paired with `street`.\n", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "city", "description": "A city associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "state", "description": "A state associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "distance", "description": "Restricts results to people associated with addresses located within the specified distance (in miles) of the city provided in the city parameter. The maximum accepted value is 999.\nMust be paired with the `city`.\n", "schema": { "type": "number" }, "required": false }, { "in": "query", "name": "email", "description": "An email address associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "phone", "description": "A 10-digit US phone number associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "relative_first_name", "description": "The first name of a relative associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "relative_last_name", "description": "The last name of a relative associated with the person you are searching for.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "age_min", "description": "The minimum age of the searched name.", "schema": { "type": "integer" }, "required": false }, { "in": "query", "name": "age_max", "description": "The maximum age of the searched name.", "schema": { "type": "integer" }, "required": false }, { "in": "query", "name": "start_index", "description": "The starting index from which results should be fetched. This is a 1-based index. For example, if there are 10 total results and start_index is set to 3, results from the third item (index 3) through to the tenth item (index 10) will be returned.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "end_index", "description": "The ending index up to which results should be fetched. This is a 1-based index. For example, if there are 10 total results and end_index is set to 7, results from the first item (index 1) through to the seventh item (index 7) will be returned.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "position_token", "description": "This method facilitates continuous data retrieval in a sequenced manner. If the response has position_token set, use the token obtained from the initial Name Search response as a parameter in the search URL to access the next set of results. Each response is limited to returning a maximum of 50 results.", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "include_possible_matches", "description": "This option includes similar results when exact matches are not found.", "schema": { "type": "boolean" }, "required": false } ], "responses": { "200": { "description": "OK - A successful Name Search returns an array of people.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Name" } } } }, "404": { "description": "Not Found" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --header \"X-api-key: [YOUR API KEY]\" \\\n -X GET 'https://api.spokeo.com/v5/names?first_name=john&last_name=smith&state=california'\n" }, { "lang": "Ruby", "label": "Ruby", "source": "connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|\n faraday.headers['X-api-key'] = 'YOUR API KEY'\nend\nparams = {\n last_name: 'smith',\n first_name: 'john',\n state: 'CA'\n}\nconnection.get('/names', params)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = \"https://api.spokeo.com/v5/names\"\n\nquery = {\n \"first_name\": \"string\",\n \"middle_name\": \"string\",\n \"last_name\": \"string\",\n \"city\": \"string\",\n \"state\": \"string\",\n \"email\": \"string\",\n \"start_index\": \"string\",\n \"end_index\": \"string\",\n \"position_token\": \"string\"\n}\n\nheaders = {\n \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36\",\n \"X-api-key\": \"YOUR_API_KEY_HERE\"\n}\n\nresponse = requests.get(url, headers=headers, params=query)\n\ndata = response.json()\nprint(data)\n" } ] } }, "/phones": { "get": { "tags": [ "Phone Search" ], "summary": "Search for Information on a Phone Number", "operationId": "phones", "security": [ { "api_key": [] } ], "parameters": [ { "in": "query", "name": "phone", "description": "The 10-digit US phone number you are using in your search.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK - A successful Phone Search returns an array of people associated with a phone number, as well as metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --header \"X-api-key: [YOUR API KEY]\" \\\n -X GET 'https://api.spokeo.com/v5/phones?phone=1234567890'\n" }, { "lang": "Ruby", "label": "Ruby", "source": "connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|\n faraday.headers['X-api-key'] = 'YOUR API KEY'\nend\nparams = {\n phone: 1234567890\n}\nconnection.get('/phones', params)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = \"https://api.spokeo.com/v5/phones\"\n\nquery = {\n \"phone\": \"string\"\n}\n\nheaders = {\n \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36\",\n \"X-api-key\": \"YOUR_API_KEY_HERE\"\n}\n \nresponse = requests.get(url, headers=headers, params=query)\n \ndata = response.json()\nprint(data)\n" } ] } }, "/addresses": { "get": { "tags": [ "Address Search" ], "summary": "Search for Information on an Address", "operationId": "addresses", "security": [ { "api_key": [] } ], "parameters": [ { "in": "query", "name": "street", "description": "street and address", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "city", "description": "city name", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "state", "description": "US state; can be abbreviated", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "unit", "description": "unit number or letter", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "position_token", "description": "page/position token of the address response", "schema": { "type": "integer" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --header \"X-api-key: [YOUR API KEY]\" \\\n -X GET 'https://api.spokeo.com/v5/addresses?street=301-Standiford-Ave&city=Modesto&state=CA'\n" }, { "lang": "Ruby", "label": "Ruby", "source": "connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|\n faraday.headers['X-api-key'] = 'YOUR API KEY'\nend\nparams = {\n street: '301-Standiford-Ave',\n city: 'Modesto',\n state: 'CA' \n}\nconnection.get('/addresses', params)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = \"https://api.spokeo.com/v5/addresses\"\n\nquery = {\n \"street\": \"string\",\n \"city\": \"string\",\n \"state\": \"string\",\n \"unit\": \"string\",\n \"position_token\": \"0\"\n}\n\n headers = {\n \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36\",\n \"X-api-key\": \"YOUR_API_KEY_HERE\"\n}\n\nresponse = requests.get(url, headers=headers, params=query)\n\ndata = response.json()\nprint(data)\n" } ] } }, "/person_id/{id}": { "get": { "tags": [ "Person ID Search" ], "summary": "Search for a Person by Person ID", "operationId": "pids", "security": [ { "api_key": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "unique person identifier", "schema": { "type": "number" }, "required": true } ], "responses": { "200": { "description": "OK - A successful Person ID Search returns a Spokeo profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --header \"X-api-key: [YOUR API KEY]\" \\\n -X GET 'https://api.spokeo.com/v5/person_id/1234567890'\n" }, { "lang": "Ruby", "label": "Ruby", "source": "connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|\n faraday.headers['X-api-key'] = 'YOUR API KEY'\nend\nconnection.get('/person_id/1234567890')\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nid = \"YOUR_ID_PARAMETER\"\nurl = \"https://api.spokeo.com/v5/person_id/\" + id\n\nheaders = {\n \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36\",\n \"X-api-key\": \"YOUR_API_KEY_HERE\"\n}\n\nresponse = requests.get(url, headers=headers)\n\ndata = response.json()\nprint(data)\n" } ] } }, "/emails": { "get": { "tags": [ "Email Search" ], "summary": "Search for Information on an Email Address", "operationId": "emails", "security": [ { "api_key": [] } ], "parameters": [ { "in": "query", "name": "email", "description": "The email address you are using in your search.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK - A successful Email Search returns an array of people and social profiles associated with an email address, as well as metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "400": { "description": "Bad Request" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --header \"X-api-key: [YOUR API KEY]\" \\\n -X GET 'https://api.spokeo.com/v5/emails?email=email@mail.com'\n" }, { "lang": "Ruby", "label": "Ruby", "source": "connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|\n faraday.headers['X-api-key'] = 'YOUR API KEY'\nend\nparams = {\n email: 'email=email@mail.com'\n}\nconnection.get('/emails', params)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = \"https://api.spokeo.com/v5/emails\"\n \nquery = {\n \"email\": \"string\"\n}\n \nheaders = {\n \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36\",\n \"X-api-key\": \"YOUR_API_KEY_HERE\"\n}\n\nresponse = requests.get(url, headers=headers, params=query)\n \ndata = response.json()\nprint(data)\n" } ] } }, "/usernames": { "get": { "tags": [ "Username Search" ], "summary": "Search for Information on a Username", "operationId": "usernames", "security": [ { "api_key": [] } ], "parameters": [ { "in": "query", "name": "username", "description": "username to search for social profiles", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Username" } } } }, "412": { "description": "Precondition Failed" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CLI", "source": "curl --header \"X-api-key: [YOUR API KEY]\" \\\n -X GET 'https://api.spokeo.com/v5/usernames?username=tangtalks'\n" }, { "lang": "Ruby", "label": "Ruby", "source": "connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|\n faraday.headers['X-api-key'] = 'YOUR API KEY'\nend\nparams = {\n username: \"tangtalks\"\n}\nconnection.get('/usernames', params)\n" } ] } } }, "components": { "securitySchemes": { "api_key": { "type": "apiKey", "in": "header", "name": "X-api-key", "description": "To properly authenticate, you must provide your API key.\nThis API key must be provided in the `X-api-key` request header.\n" } }, "schemas": { "Name": { "type": "object", "properties": { "data": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n", "example": 1234567890 }, "names": { "type": "array", "description": "Names associated with the person.", "items": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The person’s first name.", "example": "John" }, "last_name": { "type": "string", "description": "The person’s last name.", "example": "Doe" }, "middle_name": { "type": "string", "description": "The person’s middle name.", "example": "U" }, "full_name": { "type": "string", "description": "The person’s full name.", "example": "John U Doe Jr." }, "suffix": { "type": "string", "description": "The person’s name suffix.", "example": "Jr." }, "name_type": { "type": "string", "description": "The name type of this record.", "example": "main" } } } }, "age": { "type": "number", "description": "The person’s current age or age at death.", "example": 30 }, "dob_month": { "type": "number", "description": "The person’s dob month as a number.", "example": 12 }, "dob_year": { "type": "number", "description": "The person’s dob year as a number.", "example": 1990 }, "is_deceased": { "type": "boolean", "description": "A value of \"true\" signifies that the person is deceased, while \"false\" signifies that the person is alive.", "example": false }, "phones": { "type": "array", "description": "Phone numbers associated with the person.", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone Number associated with the person.", "example": 5551234567 }, "phone_is_new": { "type": "boolean", "description": "Indicates if the phone is new in the data.", "example": true }, "phone_is_new_rank_one": { "type": "boolean", "description": "Indicates that the phone has newly become rank 1 (i.e. the current rank is 1 and the previous rank was not 1). Otherwise, this value is null.", "example": true } } } }, "emails": { "type": "array", "description": "Email addresses associated with the person.", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email associated with the person.", "example": "username@email.com" }, "email_is_new": { "type": "boolean", "description": "Indicates if the email is new in the data.", "example": true }, "email_is_new_rank_one": { "type": "boolean", "description": "Indicates that the email has newly become rank 1 (i.e. the current rank is 1 and the previous rank was not 1). Otherwise, this value is null.", "example": true } } } }, "addresses": { "type": "array", "description": "Addresses associated with the person.", "items": { "type": "object", "properties": { "city": { "type": "string", "description": "The city associated with the person.", "example": "Anytown" }, "state": { "type": "string", "description": "The state associated with the person.", "example": "CA" }, "street_address": { "type": "string", "description": "The street address associated with the person.", "example": "123 Main St" }, "zip": { "type": "string", "example": 12345 }, "latitude": { "type": "number", "description": "The latitude of the address associated with the person.", "example": 40.689247 }, "longitude": { "type": "number", "description": "The longitude of the address associated with the person.", "example": -74.0451471 }, "address_is_new": { "type": "boolean", "description": "Indicates if the address is new in the data.", "example": true }, "address_is_new_rank_one": { "type": "boolean", "description": "Indicates that the address has newly become rank 1 (i.e. the current rank is 1 and the previous rank was not 1). Otherwise, this value is null.", "example": true } } } }, "relatives": { "type": "array", "description": "Relatives associated with the person.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n" }, "names": { "type": "array", "description": "Names associated with the relative.", "items": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The relative's first name.", "example": "John" }, "last_name": { "type": "string", "description": "The relative's last name.", "example": "Doe" }, "full_name": { "type": "string", "description": "The relative's full name.", "example": "John Doe" } } } } } } }, "usernames": { "type": "array", "description": "Usernames associated with the person.", "items": { "type": "string", "example": "johndoe123" } }, "work_history": { "type": "array", "description": "Work history associated with the person.", "items": { "type": "object", "properties": { "company_name": { "type": "string", "description": "The name of the company.", "example": "Example Corp" }, "title": { "type": "string", "description": "The job title at the company.", "example": "Software Engineer" }, "location": { "type": "string", "description": "The location of the company.", "example": "New York, NY" } } } }, "schools": { "type": "array", "description": "Schools associated with the person.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the school.", "example": "Example University" }, "type": { "type": "string", "description": "The type of school.", "example": "Post-Secondary Institution" }, "location": { "type": "string", "description": "The location of the school.", "example": "Boston, MA" } } } }, "phone_record_count": { "type": "number", "description": "The total number of phone records associated with the person.", "example": 5 }, "phone_record_delta_count": { "type": "number", "description": "The total change in the number of phone records associated with the person.", "example": 1 }, "email_record_count": { "type": "number", "description": "The total number of email records associated with the person.", "example": 5 }, "email_record_delta_count": { "type": "number", "description": "The total change in the number of email records associated with the person.", "example": 2 }, "address_count": { "type": "number", "description": "The total number of addresses associated with the person.", "example": 10 }, "address_record_delta_count": { "type": "number", "description": "The total change in the number of address records associated with the person.", "example": 0 }, "relative_count": { "type": "number", "description": "The total number of relatives associated with the person.", "example": 10 }, "username_count": { "type": "number", "description": "The total number of usernames associated with the person.", "example": 10 } } } } } }, "metadata": { "type": "object", "properties": { "total_people_count": { "type": "number", "description": "The total count in the array of people returned based on your search inputs.", "example": 200 } } }, "position_token": { "type": "string", "description": "A token indicating that there are additional results beyond those initially returned. Use the token obtained from the initial Name Search response as a parameter in the search URL to access the next set of results.", "example": "Mg==" } } }, "Phone": { "type": "object", "properties": { "data": { "type": "object", "properties": { "owners": { "type": "array", "items": { "type": "object", "description": "Owners associated with the phone number.", "properties": { "is_current_owner": { "type": "boolean", "description": "A value of \"true\" signifies that the person is the current owner of the phone number, while \"false\" signifies that the person is either a possible current owner or a previous owner." }, "age": { "type": "number", "description": "The person’s current age or age at death.", "example": 62 }, "additional_phones": { "type": "array", "description": "Additional phone numbers associated with the person.", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone Number associated with the person.", "example": 5551234567 } } } }, "addresses": { "type": "array", "description": "Addresses associated with the person.", "items": { "type": "object", "properties": { "address_id": { "type": "string", "description": "The address id associated with the person.", "example": "123a2bf|October Ln|47||" }, "street_address": { "type": "string", "description": "The street address associated with the person.", "example": "123 Main St" }, "city": { "type": "string", "description": "The city associated with the person.", "example": "Anytown" }, "country": { "type": "string", "description": "The country associated with the person.", "example": "United States" }, "latitude": { "type": "number", "description": "The latitude of the address associated with the person.", "example": 40.689247 }, "longitude": { "type": "number", "description": "The longitude of the address associated with the person.", "example": -74.0451471 }, "state": { "type": "string", "description": "The state associated with the person.", "example": "MN" }, "zip": { "type": "string", "description": "The ZIP code associated with the person.", "example": 55555 }, "start_date": { "type": "string", "description": "The date the phone owner started owning this property.", "example": "1996-01-12" }, "end_date": { "type": "string", "description": "The date the phone owner stopped owning this property.", "example": "2025-01-31" } } } }, "schools": { "type": "array", "description": "Schools the person attended.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the school the person attended.", "example": "Anytown University" }, "type": { "type": "string", "description": "The type of school the person attended. (e.g. \"University\")", "example": "University" }, "location": { "type": "string", "description": "The location of the school the person attended.", "example": "Anytown, CA" }, "linkedin": { "type": "string", "description": "The social profile of the school the person attended.", "example": "linkedin.com/school/anytown-university" }, "facebook": { "type": "string", "description": "The social profile of the school the person attended.", "example": "facebook.com/anytownuniversity" }, "twitter": { "type": "string", "description": "The social profile of the school the person attended.", "example": "twitter.com/anytownuniversity" }, "website": { "type": "string", "description": "The website of the school the person attended.", "example": "anytownuniversity.edu" }, "start_date": { "type": "string", "description": "The date the phone owner started attending this school.", "example": 2010 }, "end_date": { "type": "string", "description": "The date the phone owner stopped attending this school.", "example": 2012 }, "degrees": { "type": "array", "description": "Degrees the person received.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the degree the person received.", "example": "computer science" } } } } } } }, "emails": { "type": "array", "description": "Email addresses associated with the person.", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email associated with the person.", "example": "username@email.com" } } } }, "names": { "type": "array", "description": "Names associated with the person.", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Full Name associated with the person.", "example": "John Smith" }, "first_name": { "type": "string", "description": "First Name associated with the person.", "example": "John" }, "last_name": { "type": "string", "description": "Last Name associated with the person.", "example": "Smith" }, "name_type": { "type": "string", "description": "The name type of this record.", "example": "main" } } } }, "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n", "example": 1234567890 }, "relatives": { "type": "array", "description": "Relatives associated with the person.", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Full Name associated with the person.", "example": "Jane Smith" }, "first_name": { "type": "string", "description": "First Name associated with the person.", "example": "Jane" }, "last_name": { "type": "string", "description": "Last Name associated with the person.", "example": "Smith" } } } }, "social_profiles": { "type": "array", "description": "Social profiles associated with the person.", "items": { "type": "object", "properties": { "profile_photo_url": { "type": "string", "description": "The social profile photo url.", "example": "https://graph.facebook.com/123/picture?type=large&redirect=true" }, "profile_url": { "type": "string", "description": "The social profile url.", "example": "https://www.facebook.com/jsmith" } } } }, "work_history": { "type": "array", "description": "Jobs the person held.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The job title of the phone owner.", "example": "Product Manager" }, "company_name": { "type": "string", "description": "The company name of the workplace.", "example": "Spokeo" } } } }, "confidence_score": { "type": "number", "description": "The confidence level of the phone owner.", "example": 34.53 }, "is_company": { "type": "boolean", "description": "Indicates whether the owner is a person or company.", "example": false }, "is_deceased": { "type": "boolean", "description": "Indicates whether the owner is deceased.", "example": false }, "death_month": { "type": "number", "description": "Owner's death month as a number.", "example": 11 }, "death_year": { "type": "number", "description": "Owner's death year as a number.", "example": 2010 }, "dob_month": { "type": "number", "description": "The person’s dob month as a number.", "example": 3 }, "dob_year": { "type": "number", "description": "The person’s dob year as a number.", "example": 1943 }, "start_date": { "type": "date", "description": "The start date of this phone owner.", "example": "1996-01-12" }, "end_date": { "type": "date", "description": "The end date of this phone owner.", "example": "2025-01-31" } } } }, "area_code_locations": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string", "description": "The city associated with the person.", "example": "Anytown" }, "latitude": { "type": "number", "description": "The latitude of the address associated with the person.", "example": 40.689247 }, "longitude": { "type": "number", "description": "The longitude of the address associated with the person.", "example": -74.0451471 }, "state": { "type": "string", "description": "The state associated with the phone number's area code.", "example": "CA" } } } }, "phone_info": { "type": "object", "properties": { "activity_status": { "type": "string", "description": "Returns whether the phone line is “Active” or “Inactive”.", "example": "Active" }, "activity_status_confidence": { "type": "string", "description": "The confidence level of the activity status.", "example": "High" }, "line_type": { "type": "string", "description": "Returns whether the phone line is “Landline”, “Wireless”, or “VOIP”.", "example": "Wireless" }, "listing_type": { "type": "string", "description": "Returns whether the phone service is \"Residential\", \"Business\", or \"Special Services\".", "example": "Unknown" }, "special_service_type": { "type": "string", "description": "The type of special service associated with the phone number (e.g. “Information Provider”).", "example": null }, "carrier": { "type": "string", "description": "The company providing the phone service.", "example": "Verizon Wireless" }, "carrier_type": { "type": "string", "description": "The type of business for the carrier (e.g. “Wireless”).", "example": "Wireless" }, "is_valid": { "type": "boolean", "description": "A value of \"true\" signifies that the phone number is properly formed and assigned to a carrier." }, "is_portable": { "type": "boolean", "description": "A value of \"true\" signifies that the phone number can switch carriers." }, "time_zone": { "type": "string", "description": "The time zone associated with the phone number's area code.", "example": "America/Anytown" } } }, "reputation": { "type": "object", "properties": { "risk_level": { "type": "string", "description": "The risk level of the phone number.", "example": "High" }, "recent_search_count": { "type": "number", "description": "The number of recent searches of this phone number.", "example": 5 }, "last_comment_date": { "type": "date", "description": "The date of the last comment reported for this phone number.", "example": "2023-09-04" }, "is_toll_free_or_erc": { "type": "boolean", "description": "Flag to indicate whether the phone number is toll free or ERC.", "example": false }, "score": { "type": "number", "description": "The reputation score of the phone number.", "example": 1 } } } } }, "metadata": { "type": "object", "properties": { "total_owner_count": { "type": "number", "description": "The total count in the array of owners returned based on your search inputs.", "example": 1 } } } } }, "Address": { "type": "object", "properties": { "data": { "type": "object", "properties": { "address": { "type": "object", "properties": { "street_address": { "type": "string", "example": "123 Main St" }, "city": { "type": "string", "example": "Anytown" }, "zip": { "type": "string", "example": 11111 }, "county": { "type": "string", "example": "Los Angeles" }, "state": { "type": "string", "example": "CA" }, "latitude": { "type": "number", "example": 40.689247 }, "longitude": { "type": "number", "example": -74.0451471 }, "nearby_schools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "MP Montessori School" }, "address": { "type": "object", "properties": { "street_address": { "type": "string", "example": "123 Main St Ave" }, "city": { "type": "string", "example": "Anytown" }, "state": { "type": "string", "example": "CA" } } }, "grades_served": { "type": "string", "example": "PK-KG" }, "type": { "type": "string", "example": "Private" }, "enrollment_count": { "type": "number", "example": 34 }, "rating": { "type": "string", "example": "B-" }, "district_name": { "type": "string", "example": "Los Angeles Unified" } } } }, "properties": { "type": "array", "items": { "type": "object", "properties": { "valuations": { "type": "array", "items": { "type": "object", "properties": { "confidence_score": { "type": "number", "example": 95 }, "date": { "type": "string", "example": "2021-11-24" }, "forecast_standard_deviation": { "type": "number", "example": 5 }, "market_value": { "type": "number", "example": 1327500 }, "market_value_max": { "type": "number", "example": 1393875 }, "market_value_min": { "type": "number", "example": 1261125 } } } }, "residents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n", "example": 1234567890 }, "is_deceased": { "type": "boolean", "example": false }, "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "John James Smith" }, "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "James" }, "last_name": { "type": "string", "example": "Smith" }, "name_type": { "type": "string", "example": "main" } } } }, "age": { "type": "number", "example": 51 }, "dob_month": { "type": "number", "example": 8 }, "dob_year": { "type": "number", "example": 2023 }, "lives_at_property": { "type": "boolean", "example": true }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string", "example": "Anytown" }, "latitude": { "type": "number", "example": 40.689247 }, "longitude": { "type": "number", "example": -74.0451471 }, "street_address": { "type": "string", "example": "123 Main St Apt 8" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": 11111 }, "state": { "type": "string", "example": "CA" }, "url_path": { "type": "string", "example": "/CA/Anytown/123-Anytown-St" }, "is_current": { "type": "boolean", "example": false } } } }, "relatives": { "type": "array", "items": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "Jane Doe" } } } } } } }, "phones": { "type": "array", "items": { "type": "object", "properties": { "phones": { "type": "object", "properties": { "phone": { "type": "string", "example": 2521425485 }, "is_best": { "type": "boolean", "example": true } } } } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "emails": { "type": "object", "properties": { "email": { "type": "string", "example": "jdoe@email.com" }, "is_best": { "type": "boolean", "example": true } } } } } }, "phone_record_count": { "type": "number", "example": 3 }, "address_count": { "type": "number", "example": 2 }, "email_record_count": { "type": "number", "example": 1 }, "start_date": { "type": "string", "example": "2024-05-05" }, "end_date": { "type": "string", "example": "2024-05-05" }, "first_processed": { "type": "string", "example": "2024-05-05" }, "last_processed": { "type": "string", "example": "2024-05-05" }, "confidence_score": { "type": "number", "example": 1.8 } } } }, "owners": { "type": "array", "items": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "middle_name": { "type": "string", "example": "James" }, "full_name": { "type": "string", "example": "John James Doe" }, "name_type": { "type": "string", "example": "main" } } } }, "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n", "example": 1234567890 }, "ownership_type": { "type": "string", "example": "Individual" }, "is_trust": { "type": "boolean", "example": false }, "is_company": { "type": "boolean", "example": false }, "lives_at_property": { "type": "boolean", "example": false }, "ownership_start_date": { "type": "string", "example": "1999-02-25" }, "ownership_end_date": { "type": "string", "example": "1999-02-25" }, "phones": { "type": "array", "items": { "type": "object", "properties": { "phones": { "type": "object", "properties": { "phone": { "type": "string", "example": 2521452154 }, "is_best": { "type": "boolean", "example": true } } } } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "emails": { "type": "object", "properties": { "email": { "type": "string", "example": "jdoe@email.com" }, "is_best": { "type": "boolean", "example": true } } } } } }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string", "example": "Anytown" }, "latitude": { "type": "number", "example": 40.689247 }, "longitude": { "type": "number", "example": -74.0451471 }, "street_address": { "type": "string", "example": "123 Main St Apt 8" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": 11111 }, "state": { "type": "string", "example": "CA" }, "url_path": { "type": "string", "example": "CA/Anytown/123-Anytown-St" }, "is_current": { "type": "boolean", "example": false } } } } } } }, "property_info": { "type": "object", "properties": { "zoned_use": { "type": "string", "example": "Single Family Residence" }, "living_area_sqft": { "type": "number", "example": 2652 }, "bath_count": { "type": "number", "example": 4.5 }, "bed_count": { "type": "number", "example": 3 }, "heating_type": { "type": "string", "example": "Central" }, "cooling_type": { "type": "string", "example": "Central" }, "garage_type": { "type": "string", "example": "Detached" }, "story_count": { "type": "number", "example": 2 }, "structure_style": { "type": "string", "example": "Bungalow" }, "view_type": { "type": "string", "example": "Beach" }, "pool_type": { "type": "string", "example": "Square" }, "fireplace": { "type": "string", "example": "None" }, "year_built": { "type": "number", "example": 1904 }, "lot_sqft": { "type": "number", "example": 15120 }, "unit_count": { "type": "number", "example": 1 }, "garage_sqft": { "type": "number", "example": 360 }, "type": { "type": "string", "example": "single_family" }, "has_carport": { "type": "boolean", "example": false }, "carport_sqft": { "type": "number", "example": 280 }, "parking_space_count": { "type": "number", "example": 2 }, "use_type": { "type": "string", "example": "Residential" }, "legal_subdivision": { "type": "string", "example": 9038 }, "foundation_type": { "type": "string", "example": "Concrete" }, "attic_sqft": { "type": "number", "example": 380 }, "has_attic": { "type": "boolean", "example": true }, "basement_sqft": { "type": "number", "example": 280 }, "basement_sqft_finished": { "type": "number", "example": 280 }, "basement_sqft_unfinished": { "type": "number", "example": 0 }, "porch_type": { "type": "string", "example": "None" }, "roof_construction": { "type": "string", "example": "Pitched" }, "roof_material": { "type": "string", "example": "Shingles" }, "floor_material": { "type": "string", "example": "Concrete" }, "sewage_type": { "type": "string", "example": "Underground" }, "is_multi_floor": { "type": "boolean", "example": true }, "parcel_number": { "type": "number", "example": 3254125856 }, "zoned_use_jurisdiction_code": { "type": "string", "example": "LAR1" }, "fence_type": { "type": "string", "example": "Picket" }, "area_fence": { "type": "number", "example": 280 }, "flood_zone_description": { "type": "string", "example": "This property is located in a minimal flood risk area" } } }, "tax": { "type": "object", "properties": { "assessor": { "type": "object", "properties": { "last_sold_date": { "type": "string", "example": "1997-06-25" }, "last_sold_price": { "type": "number", "example": 192500 }, "last_sold_price_per_sqft": { "type": "number", "example": 72 }, "parties": { "type": "array", "items": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "John Doe" }, "suffix": { "type": "string", "example": "Jr." } } } } } } } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "number", "example": 2020 }, "billed_amount": { "type": "number", "example": 4525 }, "total_assessed_value": { "type": "number", "example": 371709 }, "improvement_value": { "type": "number", "example": 170674 }, "land_value": { "type": "number", "example": 201035 } } } }, "delinquent_first_year": { "type": "string", "example": 2020 }, "delinquent_last_year": { "type": "string", "example": 2021 }, "district_code": { "type": "string", "example": 7500 }, "exemptions": { "type": "object", "properties": { "is_homeowner": { "type": "boolean", "example": false }, "is_disabled": { "type": "boolean", "example": false }, "is_senior": { "type": "boolean", "example": false }, "is_veteran": { "type": "boolean", "example": false }, "is_widow": { "type": "boolean", "example": false }, "is_additional": { "type": "string", "example": true } } } } }, "deed": { "type": "object", "properties": { "buyers": { "type": "array", "items": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "John Doe" }, "suffix": { "type": "string", "example": "Jr." } } } } } } }, "last_sale": { "type": "object", "properties": { "book_number": { "type": "string", "example": 10 }, "page_number": { "type": "string", "example": 25 }, "document_number": { "type": "string", "example": 123456 }, "price": { "type": "number", "example": 192500 }, "date": { "type": "string", "example": "1997-06-25" }, "price_per_sqft": { "type": "number", "example": 72 } } } } }, "financial_insight": { "type": "object", "properties": { "estimated_loan_to_value": { "type": "number", "example": 0 }, "loans_total": { "type": "number", "example": 0 }, "is_free_and_clear": { "type": "boolean", "example": false }, "is_absentee_owned": { "type": "boolean", "example": false }, "is_out_of_state_owner": { "type": "boolean", "example": false }, "is_upside_down": { "type": "boolean", "example": false }, "is_long_time_owner": { "type": "boolean", "example": false }, "is_bored_investor": { "type": "boolean", "example": false }, "is_potentially_inherited": { "type": "boolean", "example": false }, "is_potentially_distressed": { "type": "boolean", "example": false }, "known_preforeclosure_date": { "type": "boolean", "example": false } } }, "sellability": { "type": "object", "properties": { "retail_score": { "type": "number", "example": 461 }, "retail_score_date": { "type": "string", "example": "2021-10-29" }, "wholesale_score": { "type": "number", "example": 10 }, "wholesale_score_date": { "type": "string", "example": "2021-10-29" }, "investor_score": { "type": "number", "example": 504 }, "investor_score_date": { "type": "string", "example": "2021-10-29" } } }, "units": { "type": "array", "items": { "type": "object", "properties": { "designator": { "type": "string", "example": "5A" }, "bath_count": { "type": "number", "example": 2 }, "bed_count": { "type": "number", "example": 3 }, "zoned_use": { "type": "string", "example": "Residential" }, "living_sqft": { "type": "number", "example": 2000 }, "year_built": { "type": "number", "example": 1973 }, "residents": { "type": "array", "items": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "John M Doe" } } } }, "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n", "example": 1234567890 } } } } } } }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string", "example": "Anytown" }, "latitude": { "type": "number", "example": 40.689247 }, "longitude": { "type": "number", "example": -74.0445 }, "street_address": { "type": "string", "example": "123 Main St" }, "zip": { "type": "string", "example": "10001" }, "state": { "type": "string", "example": "CA" }, "county": { "type": "string", "example": "New York" }, "url_path": { "type": "string", "example": "/CA/Anytown/123-Main-St" } } } } } } } } } } }, "position_token": { "type": "string", "example": "Mg==" } } }, "Person": { "type": "object", "properties": { "data": { "type": "object", "properties": { "person": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique person identifier.", "example": 1234567890 }, "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "The person's full name.", "example": "John James Doe Jr." }, "first_name": { "type": "string", "description": "The person's first name.", "example": "John" }, "middle_name": { "type": "string", "description": "The person's middle name.", "example": "James" }, "last_name": { "type": "string", "description": "The person's last name.", "example": "Doe" }, "suffix": { "type": "string", "description": "The person's suffix.", "example": "Jr." }, "name_type": { "type": "string", "description": "The name type of this record.", "example": "main" } } } }, "gender": { "type": "string", "description": "The person's gender.", "example": "Male" }, "birth": { "type": "object", "properties": { "dob_month": { "type": "number", "description": "The month of the person's birth.", "example": 3 }, "dob_year": { "type": "number", "description": "The year of the person's birth.", "example": 2000 } } }, "death": { "type": "object", "properties": { "is_deceased": { "type": "boolean", "description": "A value of \"true\" signifies that the person is deceased, while \"false\" signifies that the person is alive." }, "death_month": { "type": "number", "description": "The month of the person's death.", "example": 11 }, "death_year": { "type": "number", "description": "The year of the person's death.", "example": 2010 }, "death_age": { "type": "number", "description": "The age of the person at death.", "example": 58 } } }, "divorce": { "type": "object", "properties": { "divorce_month": { "type": "number", "description": "The person's divorce month.", "example": 3 }, "divorce_year": { "type": "number", "description": "The person's divorce year.", "example": 2025 } } }, "marital_status": { "type": "string", "description": "The person's marital status.", "example": "Married" }, "marriage": { "type": "object", "properties": { "marriage_month": { "type": "number", "description": "The person's marriage month.", "example": 3 }, "marriage_year": { "type": "number", "description": "The person's marriage year.", "example": 2020 } } }, "addresses": { "type": "array", "description": "Addresses associated with the person.", "items": { "type": "object", "properties": { "is_current": { "type": "boolean", "description": "A value of \"true\" signifies that this is the person’s current address, while “false” signifies that it is not." }, "state": { "type": "string", "description": "The state associated with the person.", "example": "PA" }, "street_address": { "type": "string", "description": "The street address associated with the person.", "example": "123 Main St" }, "city": { "type": "string", "description": "The city associated with the person.", "example": "Anytown" }, "county": { "type": "string", "description": "The county associated with the person.", "example": "Allegheny" }, "latitude": { "type": "number", "description": "The latitude of the address associated with the person.", "example": 40.689247 }, "longitude": { "type": "number", "description": "The longitude of the address associated with the person.", "example": -74.0451471 }, "zip": { "type": "string", "description": "The ZIP code associated with the person.", "example": 11111 }, "is_new": { "type": "boolean", "description": "Indicates if this address is newly added.", "example": true }, "is_new_rank_one": { "type": "boolean", "description": "Indicates if this address is newly ranked as rank one.", "example": true }, "street_url_path": { "type": "string", "description": "The URL path for the street address.", "example": "/Main+St+Anytown+CA+addresses" }, "url_path": { "type": "string", "description": "The URL path for the person.", "example": "/CA/Anytown/123-Main-St" }, "property": { "type": "object", "properties": { "zoned_use": { "type": "string", "example": "Single Family Residence" }, "use_type": { "type": "string", "example": "Residential" }, "market_value": { "type": "number", "example": 1776000 }, "last_sold_date": { "type": "string", "example": "2023-09-04" }, "living_area": { "type": "number", "example": 742 }, "bath_total_count": { "type": "number", "example": 2 }, "bath_partial_count": { "type": "number", "example": 1 }, "bed_count": { "type": "number", "example": 3 }, "area_lot": { "type": "number", "example": 742 }, "year_built": { "type": "number", "example": 1952 }, "ownership_start_date": { "type": "string", "example": "2000-01-03" }, "last_sold_price": { "type": "number", "example": 156000 }, "sellability": { "type": "object", "properties": { "retail_score": { "type": "number", "example": 982 } } }, "source_count": { "type": "number", "example": 2 }, "source_date": { "type": "string", "example": "1996-01-12" }, "owners_count": { "type": "number", "example": 1 }, "valuations": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "example": "2021-11-24" }, "market_value": { "type": "number", "example": 1776000 } } } } } } } } }, "address_delta_count": { "type": "number", "description": "Number of address changes for this person.", "example": 2 }, "emails": { "type": "array", "description": "Email addresses associated with the person.", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email associated with the person.", "example": "username@email.com" }, "type": { "type": "string", "description": "Returns whether the email is Personal or Commercial.", "example": "Commercial" }, "domain_name": { "type": "string", "description": "The organization or individual associated with the email.", "example": "gmail" }, "source_count": { "type": "number", "description": "The number of data sources used to generate the email information.", "example": 1 }, "source_date": { "type": "string", "description": "The date when the email information was sourced.", "example": "2023-01-15" }, "confidence_score": { "type": "number", "description": "The confidence score of the email information.", "example": 64.25 }, "is_new": { "type": "boolean", "description": "Indicates if the email is new.", "example": true }, "is_new_rank_one": { "type": "boolean", "description": "Indicates if the email is newly ranked as rank one.", "example": false } } } }, "email_record_delta_count": { "type": "number", "description": "Number of email record changes for this person.", "example": 1 }, "social_profiles": { "type": "array", "description": "Social profiles associated with the person.", "items": { "type": "object", "properties": { "network_name": { "type": "string", "description": "The name of a social network associated with the person.", "example": "Twitter" }, "url": { "type": "string", "description": "The URL of a social profile associated with the person.", "example": "http://twitter.com/" }, "photo_url": { "type": "string", "description": "The URL of a social profile photo associated with the person.", "example": "https://graph.facebook.com/123/picture?type=large&redirect=true" }, "display_name": { "type": "string", "description": "The display name of the social profile.", "example": "John Doe" }, "last_seen_date": { "type": "string", "description": "The last seen date of the social profile.", "example": "2023-01-15" }, "source_count": { "type": "number", "description": "The number of data sources used to generate the social profile information.", "example": 1 } } } }, "phones": { "type": "array", "description": "Phone numbers associated with the person.", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone Number associated with the person.", "example": 5551234567 }, "activity_status": { "type": "string", "description": "Returns whether the phone line is “Active” or “Inactive”.", "example": "Active" }, "line_type": { "type": "string", "description": "Returns whether the phone line is “Landline”, “Wireless”, or “VOIP”.", "example": "Wireless" }, "city": { "type": "string", "description": "The city associated with the phone number's area code.", "example": "Anytown" }, "state": { "type": "string", "description": "The state associated with the phone number's area code.", "example": "PA" }, "listing_type": { "type": "string", "description": "Returns whether the phone service is “Residential”, “Business”, or “Special Services”.", "example": "Unknown" }, "carrier": { "type": "string", "description": "The company providing the phone service.", "example": "AT&T Mobility" }, "source_count": { "type": "number", "description": "The number of data sources used to generate the phone information.", "example": 1 }, "is_valid": { "type": "boolean", "description": "A value of \"true\" signifies that the phone number is properly formed and assigned to a carrier.", "example": true }, "reputation": { "type": "object", "properties": { "risk_level": { "type": "string", "description": "The risk level associated with the phone number.", "example": "Low" } } }, "source_date": { "type": "string", "description": "The date when the phone information was sourced.", "example": "2023-01-15" }, "time_zone_name": { "type": "string", "description": "The time zone name associated with the phone number.", "example": "America/New_York" }, "confidence_score": { "type": "number", "description": "A score indicating the confidence level of the phone information.", "example": 58.36 }, "is_new": { "type": "boolean", "description": "Indicates if the phone number is new.", "example": true }, "is_new_rank_one": { "type": "boolean", "description": "Indicates if the phone number is newly ranked as rank one.", "example": false }, "start_date": { "type": "string", "description": "The start date of the phone number association.", "example": "2020-01-01" }, "end_date": { "type": "string", "description": "The end date of the phone number association.", "example": "2023-12-31" } } } }, "phone_record_delta_count": { "type": "number", "description": "The number of changes made to the phone record.", "example": 2 }, "relatives": { "type": "array", "description": "Relatives associated with the person.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique Spokeo identifier associated with the relative. Input this ID into Person ID Search to retrieve person data, including contact information.", "example": 1234567890 }, "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "The relative’s full name.", "example": "Jane Joan Doe Jr." }, "first_name": { "type": "string", "description": "The relative’s first name.", "example": "Jane" }, "middle_name": { "type": "string", "description": "The relative’s middle name.", "example": "Joan" }, "last_name": { "type": "string", "description": "The relative’s last name.", "example": "Doe" }, "suffix": { "type": "string", "description": "The relative’s suffix.", "example": "Jr." }, "name_type": { "type": "string", "description": "The name type of this record.", "example": "main" } } } }, "dob_month": { "type": "number", "description": "The month of the relative's date of birth.", "example": 5 }, "dob_year": { "type": "number", "description": "The year of the relative's date of birth.", "example": 1950 }, "is_deceased": { "type": "boolean", "description": "A value of \"true\" signifies that the relative is deceased, while \"false\" signifies that the relative is alive." }, "death_year": { "type": "number", "description": "The year of the relative’s death.", "example": 2010 }, "death_month": { "type": "number", "description": "The month of the relative’s death.", "example": 11 }, "gender": { "type": "string", "description": "The relative’s gender.", "example": "Female" }, "marital_status": { "type": "string", "description": "The relative's marital status.", "example": "Married" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street_address": { "type": "string", "description": "The street address associated with the relative.", "example": "123 Main St" }, "city": { "type": "string", "description": "The city associated with the relative.", "example": "Anytown" }, "state": { "type": "string", "description": "The state associated with the relative.", "example": "SC" }, "start_year": { "type": "number", "description": "The year the relative started living at this address.", "example": 2000 }, "start_month": { "type": "number", "description": "The month the relative started living at this address.", "example": 6 }, "end_year": { "type": "number", "description": "The year the relative stopped living at this address.", "example": 2010 }, "end_month": { "type": "number", "description": "The month the relative stopped living at this address.", "example": 12 }, "coresidence_start_year": { "type": "number", "description": "The year the relative started living with the person.", "example": 2005 }, "coresidence_start_month": { "type": "number", "description": "The month the relative started living with the person.", "example": 3 }, "coresidence_end_year": { "type": "number", "description": "The year the relative stopped living with the person.", "example": 2015 }, "coresidence_end_month": { "type": "number", "description": "The month the relative stopped living with the person.", "example": 8 } } } } } } }, "work_history": { "type": "array", "description": "Jobs the person held.", "items": { "type": "object", "properties": { "is_current": { "type": "boolean", "description": "A value of \"true\" signifies that the person is still employed in the job, while \"false\" signifies that the person is not." }, "start_date": { "type": "string", "description": "The date the person started working at the job.", "example": "2003-04-28" }, "end_date": { "type": "string", "description": "The date the person finished working at the job.", "example": "2003-04-28" }, "company_name": { "type": "string", "description": "The name of the company.", "example": "Company Name Inc" }, "title": { "type": "string", "description": "The job title of the person.", "example": "Software Engineer" } } } }, "schools": { "type": "array", "description": "Schools the person attended.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The school the person attended.", "example": "Anytown University" }, "start_date": { "type": "string", "description": "The date the person starting attending the school.", "example": 2025 }, "type": { "type": "string", "description": "The type of school the person attended.", "example": "post-secondary institution" }, "location": { "type": "string", "description": "The location of the school the person attended", "example": "Anytown, CA" }, "majors": { "type": "array", "description": "The major(s) the person studied at the school", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "business" } } } } } } }, "certifications": { "type": "array", "description": "Certifications the person received.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of certification the person attained.", "example": "certified software engineer" }, "organization": { "type": "string", "description": "The name of organation the person attained certication.", "example": "some coding school" }, "start_date": { "type": "string", "description": "The date the person started the certification program.", "example": "2020-06" }, "end_date": { "type": "string", "description": "The date the person ended the certication program.", "example": "2022-08" } } } }, "languages": { "type": "array", "description": "Languages the person speaks.", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "The name of the language.", "example": "English" }, "proficiency": { "type": "string", "description": "The proficiency level in the language.", "example": "fluent" } } } }, "historical_records": { "type": "array", "description": "Historical records of the person.", "items": { "type": "object", "properties": { "record_type": { "type": "string", "description": "The type of historical record.", "example": "census" }, "event_year": { "type": "number", "description": "The year of the historical record.", "example": 1996 }, "event_month": { "type": "number", "description": "The month of the historical record.", "example": 3 }, "relatives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique person identifier.", "example": 1234567890 }, "relation_type": { "type": "string", "description": "The type of relationship to the person.", "example": "spouse" }, "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "The person's full name.", "example": "Jane Joan Doe" }, "first_name": { "type": "string", "description": "The person's first name.", "example": "Jane" }, "middle_name": { "type": "string", "description": "The person's middle name.", "example": "Joan" }, "last_name": { "type": "string", "description": "The person's last name.", "example": "Doe" }, "maiden_name": { "type": "string", "description": "The person's maiden name.", "example": "Smith" } } } } } } }, "names": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "The person's full name.", "example": "John James Doe" }, "first_name": { "type": "string", "description": "The person's first name.", "example": "John" }, "middle_name": { "type": "string", "description": "The person's middle name.", "example": "James" }, "last_name": { "type": "string", "description": "The person's last name.", "example": "Doe" }, "maiden_name": { "type": "string", "description": "The person's maiden name.", "example": "Smith" } } } }, "birth": { "type": "object", "properties": { "dob_month": { "type": "number", "description": "The month of birth.", "example": 12 }, "dob_year": { "type": "number", "description": "The year of birth.", "example": 1980 }, "dob_zodiac": { "type": "string", "description": "The zodiac sign of the person.", "example": "Sagittarius" } } }, "death": { "type": "object", "properties": { "is_deceased": { "type": "boolean", "description": "Indicates if the person is deceased.", "example": true } } }, "address": { "type": "object", "properties": { "city": { "type": "string", "description": "The city of the person's address.", "example": "Anytown" }, "location": { "type": "string", "description": "The location of the person's address.", "example": "Greater Anytown" }, "state": { "type": "string", "description": "The state of the person's address.", "example": "CA" } } } } } } } } } }, "metadata": { "type": "object" } } }, "Email": { "type": "object", "properties": { "data": { "type": "object", "properties": { "owners": { "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The person's first name.", "example": "John" }, "last_name": { "type": "string", "description": "The person's last name.", "example": "Smith" }, "id": { "type": "string", "description": "A unique Spokeo identifier associated with the person. Input this ID into **[Person ID Search](/apis/openapi/person-id-search)** to retrieve person data, including contact information.\n", "example": 1234567890 }, "phones": { "type": "array", "description": "Phone numbers associated with the person.", "items": { "example": "555-555-1234" } }, "age": { "type": "number", "description": "The person’s current age or age at death.", "example": 62 }, "dob_month": { "type": "number", "description": "The person's birth month.", "example": 3 }, "dob_year": { "type": "number", "description": "The person's birth year.", "example": 1960 }, "current_address": { "type": "object", "description": "Address associated with the person.", "properties": { "street_address": { "type": "string", "description": "The street address associated with the person.", "example": "123 Main St" }, "city": { "type": "string", "description": "The city associated with the person.", "example": "Anytown" }, "latitude": { "type": "number", "description": "The latitude of the address associated with the person.", "example": 40.689247 }, "longitude": { "type": "number", "description": "The longitude of the address associated with the person.", "example": -74.0451471 }, "state": { "type": "string", "description": "The state associated with the person.", "example": "AN" }, "zip": { "type": "string", "description": "The ZIP code associated with the person.", "example": 12345 } } }, "emails": { "type": "array", "description": "Other email addresses associated with the person.", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address associated with the person.", "example": "someone@gmail.com" }, "chronology_rank": { "type": "number", "description": "The rank of the email address associated with the person.", "example": 1 } } } }, "social_profiles": { "type": "array", "description": "Social profiles associated with the person.", "items": { "type": "object", "properties": { "profile_url": { "type": "string", "description": "The URL of a social media profile associated with the person.", "example": "https://www.facebook.com/tangtalks" }, "profile_photo_url": { "type": "string", "description": "The URL of a social media profile photo associated with the person.", "example": "https://graph.facebook.com/123/picture?type=large&redirect=true" }, "network": { "type": "string", "description": "The social media network associated with the person.", "example": "facebook" }, "username": { "type": "string", "description": "The username associated with the person.", "example": "tangtalks" }, "display_name": { "type": "string", "description": "The display name associated with the person.", "example": "TangTalks" } } } }, "work_history": { "type": "array", "description": "Jobs the person held.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The person’s job title.", "example": "Product Manager" }, "company_name": { "type": "string", "description": "The name of the company.", "example": "Spokeo" }, "is_current": { "type": "boolean", "description": "A value of \"true\" signifies that the person is still employed in the job, while \"false\" signifies that the person is not." }, "start_date": { "type": "string", "description": "The date the person started working at the job.", "example": 2010 }, "end_date": { "type": "string", "description": "The date the person finished working at the job.", "example": 2012 } } } }, "schools": { "type": "array", "description": "Schools the person attended.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The school the person attended.", "example": "California State University" }, "start_date": { "type": "string", "description": "The date the person started attending the school.", "example": 2010 }, "end_date": { "type": "string", "description": "The date the person finished attending the school.", "example": 2012 }, "degrees": { "type": "array", "description": "The type of degree(s) the person obtained from the school.", "example": "master of science" } } } } } } }, "social_profiles": { "type": "array", "items": { "type": "object", "properties": { "profile_url": { "type": "string", "description": "The URL of a social media profile associated with the social profile", "example": "https://www.facebook.com/tangtalks" }, "profile_photo_url": { "type": "string", "description": "The URL of a social media profile photo associated with the social profile", "example": "https://graph.facebook.com/123/picture?type=large&redirect=true" }, "network": { "type": "string", "description": "The social media network associated with the social profile", "example": "facebook" }, "username": { "type": "string", "description": "The username associated with the social profile", "example": "tangtalks" }, "display_name": { "type": "string", "description": "The display name associated with the social profile", "example": "TangTalks" }, "search_term": { "type": "string", "description": "The matching search term. It can be either a username or email.", "example": "someone@gmail.com" }, "is_primary_match": { "type": "boolean", "description": "A value of \"true\" signifies that the social profile was matched by the search query.", "example": true }, "match_type": { "type": "string", "description": "This indicates whether the match type is by email or username", "example": "email" } } } } } }, "metadata": { "type": "object", "properties": { "total_owner_count": { "type": "number", "description": "The total count in the array of owners returned based on your search inputs.", "example": 1 }, "total_social_profiles": { "type": "number", "description": "The total count in the array of social profiles returned based on your search inputs.", "example": 1 } } } } }, "Username": { "type": "object", "properties": { "data": { "type": "object", "properties": { "social_profiles": { "type": "array", "items": { "type": "object", "properties": { "profile_url": { "type": "string", "example": "https://www.facebook.com/tangtalks", "description": "The URL of a social media profile associated with the social profile" }, "profile_photo_url": { "type": "string", "example": "https://graph.facebook.com/123/picture?type=large&redirect=true", "description": "The URL of a social media profile photo associated with the social profile" }, "network": { "type": "string", "example": "facebook", "description": "The social media network associated with the social profile" }, "username": { "type": "string", "example": "tangtalks", "description": "The username associated with the social profile" }, "display_name": { "type": "string", "example": "TangTalks", "description": "The display name associated with the social profile" }, "search_term": { "type": "string", "example": "tangtalks", "description": "The matching search term. It can be either a username or email." }, "is_primary_match": { "type": "boolean", "example": true, "description": "A value of \"true\" signifies that the social profile was matched by the search query." }, "match_type": { "type": "string", "example": "username", "description": "This indicates whether the match type is by email or username" } } } } } }, "metadata": { "type": "object", "properties": { "total_social_profiles": { "type": "number", "description": "The total count in the array of social profiles returned based on your search inputs.", "example": 1 } } } } } } } }