Candid Lookup API
Operations for retrieving lookup values and filter metadata.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/candid:candid-lookup-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Essentials Lookup API
description: Search GuideStar's most common set of data about nonprofits to quickly find organizations most relevant to your users, and use those results to get more data from our other APIs. API returns search result in JSON format.
version: '1.0'
servers:
- url: https://api.candid.org/essentials
- url: https://apidata.guidestar.org/essentials
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Lookup
paths:
/lookup:
get:
summary: /essentials/lookup
description: Use the /lookup endpoint to retrieve a list of the tables that can be passed as a filter_name to the lookup detail endpoints. The tables and their contents can be used to generate dropdowns and filters in your system when using the Essentials API.
operationId: essentials_lookup
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: Response Code
example: 200
message:
type: string
description: Diagnostic message for response status
example: Request was processed successfully!
took:
type: integer
description: Time taken for request to process
example: 20
errors:
type: array
description: List of errors encountered
example: []
items:
type: string
description: error messaging
data:
type: array
items:
type: string
description: field names and values
example:
- ntee_minor
- msa_codes
- ntee_major
- subsections
- filing_type
- foundation_type
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
text/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
text/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Forbidden'
text/json:
schema:
$ref: '#/components/schemas/Forbidden'
'404':
description: No Results Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
text/json:
schema:
$ref: '#/components/schemas/NotFound'
'406':
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
text/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
text/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
text/json:
schema:
$ref: '#/components/schemas/InternalServerError'
tags:
- Lookup
/lookup/{filter_name}:
get:
summary: /essentials/lookup/{filter_name}
description: Provides a list of all the human-readable search values within a specific filter_name table, which can then be used in search queries with the Essentials endpoints. Each array contains a table key, name value, and search value. The resulting search_value(s) can be passed as search values in the Essentials API.
operationId: essentials_lookup_{filter_name}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP response status code.
example: 200
message:
type: string
example: Request was processed successfully!
took:
type: integer
example: 20
errors:
type: array
example: []
items:
type: string
description: error messaging
data:
type: array
description: A list of all the tables used as a filter_name with the Essentials Lookup endpoints
items:
type: object
description: Key value pair for filter name, value, and search_value
properties:
key:
type: string
description: Code for the filter_name results
example: A00
value:
type: string
description: Text for the filter_name results
example: Arts, Culture, and Humanities
search_value:
type: string
description: Value to pass in Essential's API filters
example: A_artsCulturesAndHumanities
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
text/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
text/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Forbidden'
text/json:
schema:
$ref: '#/components/schemas/Forbidden'
'404':
description: No Results Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
text/json:
schema:
$ref: '#/components/schemas/NotFound'
'406':
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
text/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
text/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
text/json:
schema:
$ref: '#/components/schemas/InternalServerError'
parameters:
- name: filter_name
x-global: true
in: path
example: ntee_major
required: true
schema:
type: string
tags:
- Lookup
/lookup/{filter_name}/{key_or_value}:
get:
summary: /essentials/lookup/{filter_name}/{key_or_value}
description: Lookup details on a specific filter using the known filter_name and key_or_value. The resulting search_value can be passed as a search value in the Essentials API.
operationId: essentials_lookup_{filter_name}_{key_or_value}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: Request was processed successfully!
took:
type: integer
example: 20
errors:
type: array
example: []
items:
type: string
description: Error messaging
data:
type: array
description: A list of all the tables used as a filter_name with the Essentials Lookup endpoints
items:
type: object
description: Key value pair for filter name, value, and search_value
properties:
key:
type: string
description: Code for the filter_name and key_or_value results
example: A00
value:
type: string
description: Text for the filter_name and key_or_value results
example: Arts, Culture, and Humanities
search_value:
type: string
description: Value to pass in Essential's API filters
example: A_artsCulturesAndHumanities
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
text/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
text/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Forbidden'
text/json:
schema:
$ref: '#/components/schemas/Forbidden'
'404':
description: No Results Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
text/json:
schema:
$ref: '#/components/schemas/NotFound'
'406':
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
text/json:
schema:
$ref: '#/components/schemas/NotAcceptable'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
text/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
text/json:
schema:
$ref: '#/components/schemas/InternalServerError'
parameters:
- name: filter_name
x-global: true
in: path
description: A list of all filters that can be used in Essentials endpoints. Found in the response of /essentials/lookup.
example: ntee_major
required: true
schema:
type: string
- name: key_or_value
x-global: true
in: path
description: Key of filterable items. Found in the response of /essentials/lookup/{filter_name}
example: C00
required: true
schema:
type: string
tags:
- Lookup
components:
schemas:
TooManyRequests:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 429
message:
type: string
example: Rate limit is exceeded. Try again later.
Forbidden:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 403
message:
type: string
example: Forbidden, we found insufficient permissions to grant access to the resources. Please check the detailed message of the response.
NotFound:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 404
message:
type: string
example: Request was processed successfully but we could not find the resource ein
NotAcceptable:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 406
message:
type: string
example: The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
BadRequest:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 400
message:
type: string
example: The request cannot be fulfilled due to bad syntax.
Unauthorized:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 401
message:
type: string
example: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
InternalServerError:
type: object
properties:
code:
type: string
description: HTTP response status code.
example: 500
message:
type: string
example: Oh no!, this is bad, something went wrong... please contact API support!
securitySchemes:
apiKeyHeader:
type: apiKey
name: Subscription-Key
in: header
apiKeyQuery:
type: apiKey
name: Subscription-Key
in: query
x-readme:
explorer-enabled: true
proxy-enabled: true
x-provenance:
method: harvested
publisher: Candid
source: https://developer.candid.org/openapi/essentials-25.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)