--- title: "/essentials/v4" method: POST path: "/v4" --- # /essentials/v4 `POST /v4` Enhanced search with additional features and improved performance. ## Request body - V3Query - `search_terms` string — Can be any string you'd like to search on, including EIN, organization name, keywords, etc. - `from` integer — The offset from the first result. Defaults to 0. - `size` integer — The maximum number of hits to be returned. Defaults to 25. The maximum number allowed is 25. - `sort` V3Sort - `sort_by` 'organization_name' | 'bmf_gross_receipts' | 'bmf_assets' | 'distance' | 'year_founded' — Leave blank to sort by relevance. - `sort_order` 'asc' | 'desc' — Default value is ascending. Allowed values are "asc" (ascending) and "desc" (descending). - `filters` V3Filters - `geography` GeographyFilter - `state` string[] - `zip` string — Five digit ZIP code - `radius` integer — Radius from the specified ZIP code in miles. Allowed range is between 1 and 50 miles. Values exceeding 50 will default to a radius of 50 miles. - `msa` string[] - `city` string[] - `county` string[] - `organization` V3OrganizationFilter - `profile_levels` string[] — GuideStar seal levels, comma separated. - `subject_codes` string[] — Subject codes, comma separated. - `population_served_codes` string[] — Population served codes, comma separated. - `ntee_major_codes` string[] — National Taxonomy of Exempt Entities (NTEE) major codes, comma separated. - `ntee_minor_codes` string[] — National Taxonomy of Exempt Entities (NTEE) minor codes, comma separated. - `subsection_codes` string[] — IRS subsection codes and/or descriptions, comma separated. - `foundation_codes` string[] — Foundation codes and/or descriptions, comma separated. - `group_exemption` string[] — Group exemption codes, comma separated. - `number_of_employees` NumberRangeFilter - `min` integer — Minimum number - `max` integer — Maximum number - `ruling_year` NumberRangeFilter - `min` integer — Minimum number - `max` integer — Maximum number - `properties` V3OrgProperties - `bmf_status` boolean — Flag indicating the organization has the most recent IRS BMF. Defaults to null. Otherwise true or false. - `pub78_verified` boolean — Flag indicating the organization is pub78 verified. Value set as true or false. - `allow_online_giving` boolean — Flag indicating the organization allows online giving. Value set as true or false. - `dei_submitted` boolean — Flag indicating the organization has submitted demographics information. Value set as true or false. - `exclude_revoked_organizations` boolean — Flag to exclude revoked organizations. Value set as true or false. - `exclude_defunct_or_merged_organizations` boolean — Flag to exclude defunct or merged organizations. Value set as true or false. - `relationship_type` object - `parent` boolean — Flag indicating the organization is a parent. Value set as true or false. - `subordinate` boolean — Flag indicating the organization is a subordinate. Value set as true or false. - `independent` boolean — Flag indicating the organization is independent. Value set as true or false. - `headquarters` boolean — Flag indicating the organization is a headquarter. Value set as true or false. - `financials` V3FinancialsFilter - `most_recent_year` object - `form_types` object - `f990` boolean — Flag indicating the organization files a form 990. Value set as true or false. - `f990pf` boolean — Flag indicating the organization files a form 990-PF. Value set as true or false. - `f990ez` boolean — Flag indicating the organization files a form 990ez. Value set as true or false. - `f990n` boolean — Flag indicating the organization files a form 990n. Value set as true or false. - `total_revenue` NumberRangeFilter - `min` integer — Minimum number - `max` integer — Maximum number - `total_expenses` NumberRangeFilter - `min` integer — Minimum number - `max` integer — Maximum number - `total_assets` NumberRangeFilter - `min` integer — Minimum number - `max` integer — Maximum number - `required_to_file_990t` boolean — Flag indicating the organization is required to file a 990-T. Value set as true or false. - `a_133_audit_performed` boolean — Flag indicating the organization performed A-133 audit. Value set as true or false. - `last_updated` LastUpdated - `start_date` string — A filter, along with end_date, defines a range on date_type, in the format yyyy-MM-ddTHH:mm:ss. - `end_date` string — A filter, along with start_date, defines a range on date_type, in the format yyyy-MM-ddTHH:mm:ss. - `date_type` 'seal_last_modified' | 'profile_last_modified' | 'dei_last_modified' | 'financials_last_modified' | 'last_modified' — A filter, to specify updates made to a organization over the specified end_date and start_date. ## Response `200` OK - V4JsonResponse - `code` integer — Response Code - `message` string — Diagnostic message for response status - `took` integer — Time taken for request to process - `time` string — Time of API call. - `results_count` integer — Number of results returned by search - `page_count` integer — Number of pages returned by the search. - `errors` string[] — List of errors encountered - `hits` object[] - `organization` object - `candid_entity_id` string — A unique number identifying organizations and organizational entities in Candid, can be a different value than organization_id - `organization_id` string, nullable — DEPRECATED A unique number identifying organizations and organizational entities in GuideStar - `ein` string — Employer Identification Number - `organization_name` string — The public name recognized by the IRS - `also_known_as` string — Organization name Also Known As - `group_exemption` string — Four-digit number assigned to a group of organizations falling under a central/parent organization holding group exemption letters. - `mission` string — Mission statement for the organization - `website_url` string — URL for the organization's website - `logo_url` string — URL for the organization's logo - `donation_page` string — URL for organization's donation page - `profile_level` string — GuideStar seal level - `profile_year` number — GuideStar seal year - `profile_link` string — GuideStar's public profile URL - `profile_logo` string — GuideStar's seal logo - `leader_name` string — Name of leader - `leader_title` string — Leader's title - `contact_name` string — Name of the primary contact at the organization - `contact_email` string — Email of the primary contact at the organization - `contact_phone` string — Phone number of the primary contact at the organization - `contact_title` string — Title of the primary contact at the organization - `number_of_employees` number — Number of employees at the organization - `ruling_year` number — The year the IRS granted organization tax exempt status (a.k.a. Ruling Year) - `properties` object - `bmf_status` boolean — If the organization is present on the BMF - `pub78_verified` boolean — If the organization is Pub78 verified - `allow_online_giving` boolean — If the organization allows online giving - `dei_submitted` boolean — If the organization has submitted demographics information - `revoked` boolean — If the organization is revoked - `defuncted_or_merged` boolean — If the organization is defuncted or merged - `relationship_type` object - `parent` boolean — If the organization is a parent - `subordinate` boolean — If the organization is a subordinate - `independent` boolean — If the organization is independent - `headquarters` boolean — If the organization is a national headquarter - `geography` object - `address_line_1` string — Address line 1 of the organization - `address_line_2` string — Address line 2 of the organization - `city` string — City of the organization's address - `state` string — State (Abbreviation) of the organization's address - `zip` number — Zip code of the organization's address - `msa` string — Metropolitan statistical area of the organization's adresss - `congressional_district` string — Congressional district of the organization's address - `county` string — County of the organization's address - `latitude` number — latitude of the organization's adress - `longitude` number — longitude of the organization's adress - `taxonomies` object - `subject_codes` object[] - `subject_code` string — Subject code - `subject_code_description` string — Description of subject code - `population_served_codes` object[] - `population_served_code` string — Population served code - `population_served_description` string — Description of Population served code - `ntee_codes` object[] - `ntee_code` string — National Taxonomy of Exempt Entities - `ntee_code_description` string — Description of NTEE code - `subsection_code` object - `subsection_code` string — IRS subsection code of the organization - `subsection_code_description` string — Description of IRS subsection code - `foundation_code` object - `foundation_code` string — Foundation code that describes the organization - `foundation_code_description` string — Description of foundation code - `financials` object - `most_recent_year` object - `form_types` string — Tax form filing type - `fiscal_year` number — Fiscal year of the most recent tax filing - `total_revenue` number — Most recent year total revenue - `total_expenses` number — Most recent year total expenses - `total_assets` number — Most recent year total assets - `bmf_gross_receipts` number — Gross receipts of the organization reported on the BMF - `bmf_assets` number — Assets of the organization reported on the BMF - `required_to_file_990t` boolean — Flag indicating the organization is required to file a 990-T. - `a_133_audit_performed` boolean — Flag indicating the organization performed A-133 audit. - `dates` object - `seal_last_modified` string — Date when Candid seal status was last modified. - `profile_last_modified` string — Datetime of last update to Candid profile. - `dei_last_modified` string — Datetime of last update to organization demographics information - `financials_last_modified` string — Datetime of last update to organization's financial information - `last_modified` string — Datetime of organization's last publication ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — No Results Found - `406` — Not Acceptable - `429` — Too Many Requests - `500` — Internal Server Error --- [API](https://skmtc.dev/candid/apis/rfpapi.md) · [All operations](https://skmtc.dev/candid/apis/rfpapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/candid/rfpapi/revisions/bb9133e46de6/schema)