> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.wealthatlas.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.wealthatlas.com/_mcp/server. # Search people POST https://api.wealthatlas.com/v1/partners/search Content-Type: application/json Search for people using either natural language or structured search criteria. Set mode to 'natural-language' and provide search_query to describe people in plain English, or set mode to 'structured' and provide person_description with filters for location, giving capacity, net worth, affiliations, education, employment, political donations, and more. Returns paginated results with relevance explanations. Only person search is supported; any nonprofit criteria are ignored. See the [Profile Schema](/guides/profile) guide for details on the person data model. **Cost: 1 credit.** Reference: https://developer.wealthatlas.com/api-reference/search/people ## Authentication - `x-api-key` header (required) — Your WealthAtlas API key. Contact support@wealthatlas.com to get started. ## Request ### Body (application/json) This endpoint expects a Search_people_Request. - `Search_people_Request` - `mode`: `natural-language` (natural-language) - `search_query` (string, required) — Natural language query describing the people you're looking for - `excluded_list_ids` (list of string, optional, nullable) — Exclude people in these lists. IDs must identify your team's own lists (see GET /lists); unknown IDs are rejected with a 400 - `included_list_ids` (list of string, optional, nullable) — Only return people in these lists. IDs must identify your team's own lists (see GET /lists); unknown IDs are rejected with a 400 - `only_in_network` (boolean, optional, default: false) — Only return people in the team's network - `page_number` (integer, optional, default: 1) — Page number (1-indexed) - `page_size` (integer, optional, default: 10) — Results per page (1-100) - `sort_fields` (list of SortField, optional, nullable) — Sort results by: 'relevance', 'giving\_capacity', 'age', 'total\_links' (network connections count), 'net\_worth\_max', 'npo\_predicted\_annual\_giving' (predicted nonprofit giving). When omitted, a query that asks for the top of a ranking ("the wealthiest people in Palm Beach") is sorted by net worth ('net\_worth\_max'), highest first. Any other query is sorted by relevance. Pass \[\{"field": "relevance"}], or an empty list, to keep relevance order for a ranking query - `mode`: `structured` (structured) - `person_description` (PersonSearchCriteria, required) — Structured person search criteria - `excluded_list_ids` (list of string, optional, nullable) — Exclude people in these lists. IDs must identify your team's own lists (see GET /lists); unknown IDs are rejected with a 400 - `included_list_ids` (list of string, optional, nullable) — Only return people in these lists. IDs must identify your team's own lists (see GET /lists); unknown IDs are rejected with a 400 - `only_in_network` (boolean, optional, default: false) — Only return people in the team's network - `page_number` (integer, optional, default: 1) — Page number (1-indexed) - `page_size` (integer, optional, default: 10) — Results per page (1-100) - `sort_fields` (list of SortField, optional, nullable) — Sort results by: 'relevance' (default), 'giving_capacity', 'age', 'total_links' (network connections count), 'net_worth_max', 'npo_predicted_annual_giving' (predicted nonprofit giving) ## Response ### 200 Successful Response - `total_count` (integer, required) — Total number of matching people - `page_number` (integer, required) — Current page number - `page_size` (integer, required) — Results per page - `results` (list of PersonResult, optional) — Page of person results - `sentenced_schema` (string, optional, nullable) — Human-readable summary of the search criteria - `sort_fields` (list of SortField, optional, nullable) — The order these results are in: the sort you posted, or, when you posted none, the one a ranking query chose ("the wealthiest people in Palm Beach" sorts by its measure, highest first). Null means relevance order. A natural-language query is read afresh on every request, so to keep one order across pages, post the sort this field reports with the next page (an empty list when it is null) ## Errors ### 400 Bad Request Error Invalid search schema, could not parse query, unknown list IDs, or page exceeds results - `any` ### 402 Payment Required Error Out of credits in the bucket this endpoint charges (buckets are strictly isolated) - `error` (string, required) - `message` (string, required) - `bucket` (string, required) — The credit bucket that was exhausted - `available_credits` (integer, required) ### 422 Unprocessable Entity Error Validation error (missing fields, invalid types) - `any` ### 503 Service Unavailable Error Search service unavailable - `any` ## Types ### SortField Represents a sort field. Parameters ---------- field : str The logical field to sort on. Numeric fields sort directly; ``relevance`` sorts on the search's own score, the order an unsorted search returns; ``first`` and ``last`` sort alphabetically on their ``.keyword`` subfield. direction : str ``asc`` or ``desc``. Defaults to ``desc`` - `field` (enum, required) - Allowed values: `relevance`, `giving_capacity`, `age`, `total_links`, `net_worth_max`, `npo_predicted_annual_giving`, `first`, `last` - `direction` (enum, optional, default: desc) - Allowed values: `asc`, `desc` ### PersonSearchCriteria Structured search criteria for finding people. All fields are optional -- combine any subset to build your search. Multiple values in a list field are combined with OR logic - `name` (NameFilter, optional, nullable) — Filter by person name - `locations` (list of LocationFilter, optional, nullable) — Filter by location (multiple locations are OR'd) - `age` (AmountRange, optional, nullable) — Filter by age in years - `sex` (enum, optional, nullable) — Filter by sex - Allowed values: `Male`, `Female` - `is_deceased` (boolean, optional, nullable) — Filter by deceased status - `giving_capacity` (AmountRange, optional, nullable) — Filter by predicted political giving capacity in dollars - `nonprofit_giving_capacity` (AmountRange, optional, nullable) — Filter by predicted nonprofit giving capacity in dollars - `net_worth` (AmountRange, optional, nullable) — Filter by estimated net worth in dollars - `liquidity` (AmountRange, optional, nullable) — Filter by estimated liquid assets (accessible within roughly 12 months) in dollars - `employers` (list of EmployerFilter, optional, nullable) — Filter by current or past employers (multiple are OR'd) - `schools` (list of SchoolFilter, optional, nullable) — Filter by schools attended (multiple are OR'd) - `board_affiliations` (list of NonprofitFilter, optional, nullable) — Filter by nonprofit board memberships (multiple are OR'd) - `political_donations` (list of PoliticalDonationFilter, optional, nullable) — Filter by political donation history (multiple are OR'd) - `nonprofit_donations` (list of NonprofitDonationFilter, optional, nullable) — Filter by nonprofit donation history (multiple are OR'd) - `interests` (list of InterestFilter, optional, nullable) — Filter by philanthropic interests (multiple are OR'd) ### PersonResult A single person result from a search query - `id` (string, required) — WealthAtlas person ID - `name` (string, optional, default: ) — Full name - `bio` (string, optional, default: ) — Short biography - `city` (string, optional, default: ) — City of residence - `state` (string, optional, default: ) — State of residence - `giving_capacity` (integer, optional, nullable) — Estimated giving capacity - `net_worth_min` (integer, optional, nullable) — Minimum estimated net worth - `net_worth_max` (integer, optional, nullable) — Maximum estimated net worth - `liquidity_min` (integer, optional, nullable) — Minimum estimated liquid assets (accessible within roughly 12 months) in dollars - `liquidity_max` (integer, optional, nullable) — Maximum estimated liquid assets (accessible within roughly 12 months) in dollars - `primary_photo` (string, optional, nullable) — A signed URL for the primary photo, valid for at least an hour. Fetch the image when you need it rather than storing the URL - `explanation` (list of string, optional) — Why this person matched the search ### NameFilter Filter people by name - `title` (string, optional, nullable) — Name title (e.g., 'Mr.', 'Dr.', 'Rev.') - `first` (string, optional, nullable) — First name - `middle` (string, optional, nullable) — Middle name - `last` (string, optional, nullable) — Last name - `suffix` (string, optional, nullable) — Name suffix (e.g., 'Jr.', 'III', 'Esq.') ### LocationFilter Filter people by location - `street_address` (string, optional, nullable) — Street address - `street_address_line_2` (string, optional, nullable) — Street address line 2 (apt, suite, etc.) - `city` (string, optional, nullable) — City name - `state` (string, optional, nullable) — Two-letter U.S. state code (e.g., 'NY', 'CA') - `zip_code` (string, optional, nullable) — ZIP code ### AmountRange A numeric range filter (e.g., for giving capacity, net worth, age) - `min` (integer, optional, nullable) — Minimum value (inclusive) - `max` (integer, optional, nullable) — Maximum value (inclusive) - `exact` (integer, optional, nullable) — Exact value. Dollar-amount filters (net worth, giving capacities, donation amounts) treat this as a minimum and match at or above it — dollar figures in the data are estimates, bands, and running totals, so a point equality would match almost nothing. Age matches exactly ### EmployerFilter Filter people by employer - `company_name` (string, optional, nullable) — Company name to match - `job_title` (string, optional, nullable) — Job title to match ### SchoolFilter Filter people by education - `school_name` (string, optional, nullable) — School or university name to match ### NonprofitFilter Filter people by nonprofit affiliation (board membership or volunteering) - `name` (string, optional, nullable) — Nonprofit organization name to match - `ein` (string, optional, nullable) — 9-digit Employer Identification Number (no dashes) - `location` (LocationFilter, optional, nullable) — Location of the nonprofit ### PoliticalDonationFilter Filter people by political donation history - `candidate_name` (string, optional, nullable) — Candidate name to match - `political_party` (enum, optional, nullable) — Political party of the recipient - Allowed values: `democrat`, `republican`, `libertarian`, `green`, `independent` - `location` (LocationFilter, optional, nullable) — Location of the candidate or PAC - `cumulative_amount` (AmountRange, optional, nullable) — Cumulative donation amount in dollars - `year_range` (YearRangeFilter, optional, nullable) — Year range of donations ### NonprofitDonationFilter Filter people by nonprofit donation history - `name` (string, optional, nullable) — Nonprofit organization name to match - `ein` (string, optional, nullable) — 9-digit Employer Identification Number (no dashes) - `location` (LocationFilter, optional, nullable) — Location of the nonprofit - `cumulative_amount` (AmountRange, optional, nullable) — Cumulative donation amount in dollars - `year_range` (YearRangeFilter, optional, nullable) — Year range of donations ### InterestFilter Filter people by philanthropic interests - `interest` (string, required) — Interest or cause area (e.g., 'education', 'environment', 'healthcare') ### YearRangeFilter A year range filter - `min` (integer, optional, nullable) — Earliest year (inclusive) - `max` (integer, optional, nullable) — Latest year (inclusive) ## Examples **Request** ```json { "search_query": "wealthy people in New York who give to education" } ``` **Response** ```json { "total_count": 1, "page_number": 1, "page_size": 1, "results": [ { "id": "string", "name": "", "bio": "", "city": "", "state": "", "giving_capacity": 1, "net_worth_min": 1, "net_worth_max": 1, "liquidity_min": 1, "liquidity_max": 1, "primary_photo": "string", "explanation": [ "string" ] } ], "sentenced_schema": "string", "sort_fields": [ { "field": "relevance", "direction": "desc" } ] } ``` **SDK Code** ```python import requests url = "https://api.wealthatlas.com/v1/partners/search" payload = { "search_query": "wealthy people in New York who give to education" } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.wealthatlas.com/v1/partners/search'; const options = { method: 'POST', headers: {'x-api-key': '', 'Content-Type': 'application/json'}, body: '{"search_query":"wealthy people in New York who give to education"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.wealthatlas.com/v1/partners/search" payload := strings.NewReader("{\n \"search_query\": \"wealthy people in New York who give to education\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.wealthatlas.com/v1/partners/search") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"search_query\": \"wealthy people in New York who give to education\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.wealthatlas.com/v1/partners/search") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"search_query\": \"wealthy people in New York who give to education\"\n}") .asString(); ``` ```php request('POST', 'https://api.wealthatlas.com/v1/partners/search', [ 'body' => '{ "search_query": "wealthy people in New York who give to education" }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.wealthatlas.com/v1/partners/search"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"search_query\": \"wealthy people in New York who give to education\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = ["search_query": "wealthy people in New York who give to education"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.wealthatlas.com/v1/partners/search")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```