---
title: "/essentials/v2"
method: POST
path: "/v2"
---

# /essentials/v2

`POST /v2`

Find nonprofits using variable search criteria and explore essential information.

## Request body

- Query
  - `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` Sort
    - `sort_by` 'organization_name' | 'bmf_gross_receipts' | 'bmf_assets' — Leave blank to sort by relevance.
    - `ascending` boolean — Default value is true (ascending). Set to false to sort by descending value.
  - `filters` Filters
    - `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` OrganizationFilter
      - `profile_levels` string[] — GuideStar seal levels, 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.
      - `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.
      - `affiliation_type` AffiliationTypeFilter
        - `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.
        - `headquarter` boolean — Flag indicating the organization is a headquarter. Value set as true or false.
      - `specific_exclusions` SpecificExclusionsFilter
        - `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.
      - `number_of_employees_range` NumberRangeFilter
        - `min` integer — Minimum number
        - `max` integer — Maximum number
      - `form_types` IrsFormTypesFilter
        - `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 990 EZ. Value set as true or false.
        - `f990n` boolean — Flag indicating the organization files a form 990N. Value set as true or false.
        - `required_to_file_990t` boolean — Flag indicating the organization is required to file a 990-T. Value set as true or false.
      - `audits` AuditsFilter
        - `a_133_audit_performed` boolean — Flag indicating the organization performed A-133 audit. Value set as true or false.
    - `financials` FinancialsFilter
      - `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

## Response `200`

OK

- V2JsonResponse
  - `code` integer — Response Code
  - `message` string — Diagnostic message for response status
  - `took` integer — Time taken for request to process
  - `errors` string[] — List of errors encountered
  - `data` object
    - `took` integer — Elapsed time to calculate results
    - `total_hits` integer — Number of results returned by search
    - `hits` object[]
      - `organization_id` string — A unique number identifying organizations and organizational entities
      - `bridge_id` string — Deprecated Bridge ID
      - `ein` string — Employer Identification Number
      - `organization_name` string — The public name recognized by the IRS
      - `also_known_as` string — Organization name Also Known As
      - `mission` string — Mission statement for the organization
      - `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` string — Zip code of the organization's address
      - `county` string — County of the organization's address
      - `msa` string — Metropolitan statistical area of the organization's adresss
      - `lat_long` string — latitude and longitude of the organization's adress
      - `ntee_code` string — National Taxonomy of Exempt Entities
      - `profile_level` 'bronze' | 'silver' | 'gold' | 'platinum' — GuideStar seal levels.
      - `public_report` string — GuideStar's public profile URL
      - `subsection_code` string — IRS subsection code of the organization
      - `number_of_employees` string — Number of employees at the organization
      - `form_type` string — Tax form filing type.
      - `website_url` string — URL for the organization's website
      - `logo_url` string — URL for the organization's logo
      - `foundation_code` string — Foundation code that describes the organization
      - `parent_orgs` string — Names of parent organizations, comma seperated
      - `bmf_gross_receipts` string — Gross receipts of the organization reported on the BMF
      - `bmf_assets` string — Assets of the organization reported on the BMF
      - `form990_total_revenue` string — Total revenue filed on the most recent Form 990, 990-PF, or 990-EZ filing
      - `form990_total_expenses` string — Total expenses filed on the most recent Form 990, 990-PF, or 990-EZ filing
      - `form990_total_assets` string — Total assets filed on the most recent Form 990, 990-PF, or 990-EZ filing
      - `contact_email` string — Email of the primary contact at the organization
      - `contact_name` string — Name 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
      - `properties` object
        - `parent` boolean — If the organization is a parent
        - `subordinate` boolean — If the organization is a subordinate
        - `independent` boolean — If the organization is independent
        - `national_hq` boolean — If the organization is a national headquarter
        - `revoked` boolean — If the organization is revoked
        - `defuncted_or_merged` boolean — If the organization is defuncted or merged
        - `audit_a133_performed` boolean — If the organization performed a A-133 audit
        - `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

## 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)