API Reference

Getting Started

Once you have an API key, you can make a simple request in seconds.

First request

curl "https://api.501see.app/api/v1/orgs/62-1348105" \
  -H "Authorization: Bearer YOUR_API_KEY"

Open in Postman

Access Tiers

Developer Free

EIN lookup
Latest filing lookup
Bounded organization name search
Rate limit: 2 requests per second

Developer Basic

Full read API access
Organizations, filings, grants, officers, and foundation discovery
Funder portfolios
MCP access
Rate limit: 30 requests per second

Developer Pro

Everything in Developer Basic
Webhooks
Exports up to 100,000 rows
Rate limit: 30 requests per second

Standards

Transport

API base URL: https://api.501see.app.
Responses are JSON over HTTPS.

Authentication

Send Authorization: Bearer YOUR_API_KEY on production requests.
API keys use the sk_live_ prefix.

Pagination

Use offset and limit on list endpoints.
Maximum limit is 500.
Paginated responses include data, total, offset, and limit.

Sorting

Use sort=field for ascending order.
Use sort=-field for descending order.
Each endpoint documents its supported sort keys.

Request construction

Put filters after ? and join them with &.
Repeat a parameter when the endpoint says it is repeatable.
Filing endpoints support preset=summary, preset=financials, preset=all, and fields=comma,separated,names.
fields overrides preset.

Errors

Errors use an { error: { code, message } } envelope.
Common statuses are 400, 401, 403, 404, 429, and 500.

Rate limits

Free - 2 requests per second.
Basic - 30 requests per second.
Pro - 30 requests per second.

Response Schemas

These are the high-use response shapes from the public contract. The OpenAPI document contains the full schema components and examples.

PaginatedResponse<T>

Generic list envelope used by search and list endpoints. `T` is the item type, so `PaginatedResponse<OrganizationListItem>` means `data` contains organization list rows.

Field	Type	Description
data required	T[]	Returned records for the current page.
total required	integer	Total number of matching records.
offset required	integer	Current offset.
limit required	integer	Current limit.
plan	string	Present on endpoints with plan-aware field behavior.

OrganizationListItem

Slim organization row returned by /api/v1/orgs. It is the item type inside PaginatedResponse<OrganizationListItem>, not the full Organization profile.

Field	Type	Description
ein required	string	Employer Identification Number.
name required	string	Organization name.
city	string	City.
state	string	State.
zip	string	ZIP code.
ntee_code	string	NTEE code.
website	string	Website URL when available.
phone	string	Phone number when available.
formation_year	integer	Founding year.
latest_tax_period_end	date	Latest filing period end date.
total_revenue	number \| null	Latest filing revenue.
total_expenses	number \| null	Latest filing expenses.
net_assets_eoy	number \| null	Latest filing net assets at year end.
form_type	990 \| 990-EZ \| 990-PF	Latest filing form type.

Organization

Organization profile and latest filing-derived indicators.

Field	Type	Description
ein required	string	Employer Identification Number.
name required	string	Organization name.
city, state, zip, country	string	Address fields.
phone, website	string	Contact fields when available.
formation_year, domicile_state	integer/string	Formation metadata.
ntee_code, subsection	string	Classification fields.
latest_tax_period_end, latest_object_id	date/string	Latest filing references.
operating_reserve_months	number \| null	Net assets divided by monthly expenses.
revenue_growth_pct, expense_growth_pct	number \| null	Year-over-year growth metrics.
program_expense_pct, admin_expense_pct, fundraising_expense_pct	number \| null	Expense mix metrics.
contributions_pct, program_revenue_pct, investment_income_pct	number \| null	Revenue mix metrics.

Filing

Dynamic filing response. The returned fields depend on preset or fields.

Field	Type	Description
object_id, ein, form_type, tax_year	string/integer	Filing identifiers.
tax_period_begin, tax_period_end	date	Tax period dates.
org_name, org_city, org_state, org_zip, org_phone, org_website	string/number	Organization fields captured on the filing.
mission	string	Mission text when reported.
total_revenue, total_revenue_py, total_expenses, total_expenses_py	number \| null	Revenue and expense totals.
contributions, program_revenue, investment_income	number \| null	Revenue detail fields.
grants_paid, salaries_and_wages, other_expenses	number \| null	Expense detail fields.
total_assets_eoy, total_liabilities_eoy, net_assets_eoy, net_assets_boy	number \| null	Balance sheet fields.
total_employees, total_volunteers, voting_members	integer \| null	People and governance counts.
signing_officer_name, signing_officer_title	string \| null	Signing officer fields.

Officer

Officer, director, trustee, or key employee from Part VII.

Field	Type	Description
name, title	string	Person name and title.
hours_per_week	number \| null	Reported weekly hours.
compensation, other_compensation, related_compensation, benefits, total_compensation	number \| null	Compensation fields.
is_officer, is_former, is_key_employee, is_highest_compensated	boolean	Role flags from the filing.

OfficerSearchResult

Expanded officer search row with organization context and compensation fields.

Field	Type	Description
name, title	string	Person name and title.
org_name	string	Organization name.
ein	string	Organization EIN.
city, state	string	Organization location.
ntee_code	string	Organization NTEE code.
tax_year	integer	Filing tax year.
object_id	string	Filing object ID.
hours_per_week	number \| null	Reported weekly hours.
compensation, total_compensation	number \| null	Compensation fields.
total_revenue	number \| null	Organization revenue from the latest filing.
is_officer, is_key_employee, is_highest_comp, is_trustee, is_former	boolean	Role flags.

GrantSearchResult

Unified grant result across Schedule I and 990-PF sources.

Field	Type	Description
funder_ein, funder_name	string	Funder identity.
recipient_name, recipient_city, recipient_state	string	Recipient identity and location.
amount	number \| null	Grant amount.
tax_year, tax_period_begin, tax_period_end	integer/date	Filing period fields.
object_id, source	string	Source filing and source type.

Export

Asynchronous CSV export job.

Field	Type	Description
id, account_id	string/integer	Export identifiers.
status	pending \| processing \| completed \| failed	Current job status.
resource_type	organizations \| grants \| officers	Exported resource type.
filters, fields	object/array	Applied filters and selected CSV fields.
row_count, file_url, file_size_bytes, error_message	varies \| null	Completion output or failure details.
notify_email, expires_at, created_at, completed_at	string/date-time \| null	Notification and lifecycle timestamps.

WebhookEndpoint

Signed webhook endpoint owned by an account. The secret is only returned on create.

Field	Type	Description
id, public_id, account_id	string/integer	Endpoint identifiers.
url	string	Destination URL for webhook deliveries.
secret	string	Webhook signing secret returned only once on create.
active	boolean	Whether the endpoint receives deliveries.
subscriptions	array<object>	Current webhook subscriptions for this endpoint.
created_at, updated_at	string/date-time	Lifecycle timestamps.

WebhookDelivery

Webhook delivery outbox row and delivery history entry.

Field	Type	Description
id, public_id, event_id, subscription_id, account_id, user_id	string/integer \| null	Delivery and ownership identifiers.
channel, destination, status	string	Delivery channel, URL, and state.
idempotency_key, attempts	string/integer	Retry identity and attempt count.
next_attempt_at, last_attempt_at, delivered_at	string/date-time \| null	Retry and completion timestamps.
response_status, response_body, error	number/string \| null	Last response or failure details.
payload	object	Canonical webhook payload.
created_at	string/date-time	Delivery creation time.

ErrorResponse

Standard error envelope.

Field	Type	Description
error.code required	bad_request \| not_found \| internal_error \| unauthorized \| plan_required \| developer_api_basic_required \| developer_api_pro_required \| rate_limited \| unavailable	Machine-readable error code.
error.message required	string	Human-readable error message.

Endpoints

Each endpoint below shows query parameters, response envelopes, and request and response examples together.

GET

Organizations

Nonprofit organizations from the IRS Business Master File.

GET

/api/v1/orgs

List organizations

List and filter nonprofit organizations. Joins to the latest filing for financial sort and filter fields. Name search uses trigram similarity.

Parameters

Name	In	Type	Description
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.
sort	query	string, default name	Sort field. Prefix with `-` for descending.
state	query	array	Filter by two-letter state code. Repeat to match multiple states.
city	query	string	Filter by city using a case-insensitive substring match.
ntee	query	string	Filter by NTEE code prefix.
subsection	query	string	Filter by 501(c) subsection numeric suffix, such as `03` for 501(c)(3).
name	query	string	Search by organization name.
min_revenue	query	number	Minimum total revenue from the latest filing.
max_revenue	query	number	Maximum total revenue from the latest filing.
min_expenses	query	number	Minimum total expenses from the latest filing.
max_expenses	query	number	Maximum total expenses from the latest filing.
min_net_assets	query	number	Minimum end-of-year net assets from the latest filing.
max_net_assets	query	number	Maximum end-of-year net assets from the latest filing.
form_type	query	string	Filter by filing form type.
min_program_expense_pct	query	number	Minimum program expense ratio from 0 to 100.
max_program_expense_pct	query	number	Maximum program expense ratio from 0 to 100.
min_contributions_pct	query	number	Minimum contributions as a percent of revenue from 0 to 100.
max_contributions_pct	query	number	Maximum contributions as a percent of revenue from 0 to 100.
min_formation_year	query	integer	Minimum founding year.
max_formation_year	query	integer	Maximum founding year.
min_employees	query	integer	Minimum total employees. Self-reported and often sparse.
max_employees	query	integer	Maximum total employees.
mission	query	string	Full-text keyword search against the latest mission statement.

Example request

curl "https://api.501see.app/api/v1/orgs?name=food%20bank&state=GA&min_revenue=1000000&sort=-total_revenue&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "ein": "12-3456789",
      "name": "Atlanta Food Bank",
      "city": "Atlanta",
      "state": "GA",
      "ntee_code": "K30",
      "latest_tax_period_end": "2023-12-31",
      "total_revenue": 5000000,
      "total_expenses": 4800000,
      "net_assets_eoy": 6000000,
      "form_type": "990"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated list of organizations.
400	ErrorResponse	Invalid request parameters.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
429	ErrorResponse	Rate limit exceeded.

GET

/api/v1/orgs/{ein}

Get organization by EIN

Parameters

Name	In	Type	Description
ein required	path	string	Employer Identification Number formatted as `XX-XXXXXXX`.

Example request

curl "https://api.501see.app/api/v1/orgs/62-1348105" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "ein": "12-3456789",
  "name": "Atlanta Food Bank",
  "city": "Atlanta",
  "state": "GA",
  "website": "https://atlantafb.org",
  "formation_year": 1990,
  "latest_tax_period_end": "2023-12-31",
  "latest_object_id": "202303559349300000",
  "operating_reserve_months": 4.8,
  "program_expense_pct": 89.4,
  "contributions_pct": 78.2
}

Responses

Status	Schema	Description
200	Organization	Organization details.
401	ErrorResponse	Authentication required.
404	ErrorResponse	Resource not found.
429	ErrorResponse	Rate limit exceeded.

GET

/api/v1/orgs/{ein}/grants-received

List grants received by an organization

Returns a summary of grants received by the organization from Schedule I, 990-PF Part XV, and Federal Audit Clearinghouse sources.

Parameters

Name	In	Type	Description
ein required	path	string	Employer Identification Number formatted as `XX-XXXXXXX`.
limit	query	integer, default 20, min 1, max 100	Max grants to return (1-100, default 20).

Example request

curl "https://api.501see.app/api/v1/orgs/62-1348105/grants-received?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "grants": [
    {
      "funder_ein": "13-1837418",
      "funder_name": "Community Foundation of Atlanta",
      "amount": 25000,
      "purpose": "Operating support",
      "tax_year": 2023
    }
  ],
  "total_grant_count": 24,
  "total_amount": 250000,
  "funder_count": 8,
  "most_recent_year": 2024
}

Responses

Status	Schema	Description
200	GrantsReceivedSummary	Grants received summary and recent grant records.
400	ErrorResponse	Invalid request parameters.

GET

Filings

IRS 990/990-EZ/990-PF tax filings with dynamic field selection.

GET

/api/v1/orgs/{ein}/filings

List filings for an organization

Returns filings for the given EIN. Response fields are dynamic and driven by the `preset` or `fields` parameter.

Parameters

Name	In	Type	Description
ein required	path	string	Employer Identification Number formatted as `XX-XXXXXXX`.
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.
preset	query	string, default summary	Field preset for filing responses. Ignored if `fields` is provided.
fields	query	string	Comma-separated list of fields to return. Overrides `preset`.
sort	query	string, default -tax_year	Sort field. Prefix with `-` for descending.
tax_year	query	integer	Filter by tax year.
form_type	query	string	Filter by form type.

Example request

curl "https://api.501see.app/api/v1/orgs/62-1348105/filings?preset=financials&sort=-tax_year&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "object_id": "202303559349300000",
      "ein": "62-1348105",
      "form_type": "990",
      "tax_year": 2023,
      "total_revenue": 5000000,
      "total_expenses": 4800000,
      "mission": "To reduce hunger in our community."
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 5,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated list of filings with dynamic field set.
400	ErrorResponse	Invalid request parameters.
401	ErrorResponse	Authentication required.
429	ErrorResponse	Rate limit exceeded.

GET

/api/v1/orgs/{ein}/filings/latest

Get latest filing for an organization

Returns the most recent filing by tax year for the given EIN.

Parameters

Name	In	Type	Description
ein required	path	string	Employer Identification Number formatted as `XX-XXXXXXX`.
preset	query	string, default summary	Field preset for filing responses. Ignored if `fields` is provided.
fields	query	string	Comma-separated list of fields to return. Overrides `preset`.

Example request

curl "https://api.501see.app/api/v1/orgs/62-1348105/filings/latest?fields=tax_year,total_revenue,total_expenses,mission" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "object_id": "202303559349300000",
  "ein": "62-1348105",
  "form_type": "990",
  "tax_year": 2023,
  "total_revenue": 5000000,
  "total_expenses": 4800000,
  "mission": "To reduce hunger in our community."
}

Responses

Status	Schema	Description
200	Filing	Latest filing.
404	ErrorResponse	Resource not found.

GET

/api/v1/filings/{object_id}

Get filing by object ID

Parameters

Name	In	Type	Description
object_id required	path	string	IRS e-file object ID.
preset	query	string, default summary	Field preset for filing responses. Ignored if `fields` is provided.
fields	query	string	Comma-separated list of fields to return. Overrides `preset`.

Example response

{
  "object_id": "202303559349300000",
  "ein": "62-1348105",
  "form_type": "990",
  "tax_year": 2023,
  "mission": "To reduce hunger in our community."
}

Responses

Status	Schema	Description
200	Filing	Filing details.
401	ErrorResponse	Authentication required.
404	ErrorResponse	Resource not found.
429	ErrorResponse	Rate limit exceeded.

GET

Officers

Officers, directors, trustees, and key employees (Part VII).

GET

/api/v1/filings/{object_id}/officers

List officers for a filing

Returns Part VII officers, directors, and trustees for one filing.

Parameters

Name	In	Type	Description
object_id required	path	string	IRS e-file object ID.
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.

Example request

curl "https://api.501see.app/api/v1/filings/202303559349300000/officers?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "name": "Jordan Smith",
      "title": "Development Director",
      "hours_per_week": 40,
      "compensation": 125000,
      "other_compensation": 3000,
      "related_compensation": 1500,
      "benefits": 2000,
      "is_officer": true,
      "is_former": false,
      "is_key_employee": false,
      "is_highest_compensated": false,
      "total_compensation": 131500
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated list of officers.
400	ErrorResponse	Invalid request parameters.

GET

/api/v1/officers

Search officers across all filings

Search officers by role, title, organization, year, revenue, and compensation. Defaults to paid staff with non-zero pay. Compensation fields are hidden for anonymous and free-plan callers.

Parameters

Name	In	Type	Description
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.
sort	query	string, default -compensation	Sort field. Prefix with `-` for descending.
name	query	string	Search by officer name.
title	query	string	Free-text title keyword.
role	query	string	Role category mapped to curated title keywords.
role_type	query	string, default staff	Position type filter.
ein	query	string	Filter by organization EIN.
state	query	string	Filter by two-letter organization state code.
ntee	query	string	Filter by organization NTEE code or major-group prefix.
min_revenue	query	number	Minimum organization revenue.
max_revenue	query	number	Maximum organization revenue.
min_year	query	integer	Minimum tax year.
max_year	query	integer	Maximum tax year.
min_compensation	query	number	Minimum total compensation.
max_compensation	query	number	Maximum total compensation.

Example request

curl "https://api.501see.app/api/v1/officers?role=development&state=GA&min_revenue=500000&sort=-compensation" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "name": "Jordan Smith",
      "title": "Development Director",
      "org_name": "Atlanta Food Bank",
      "ein": "62-1348105",
      "city": "Atlanta",
      "state": "GA",
      "tax_year": 2023,
      "object_id": "202303559349300000",
      "compensation": 125000,
      "total_compensation": 131500,
      "total_revenue": 5000000,
      "is_officer": true,
      "is_key_employee": false,
      "is_highest_comp": false,
      "is_trustee": false,
      "is_former": false
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated officer search results.
400	ErrorResponse	Invalid request parameters.

GET

/api/v1/compensation-benchmark

Compensation percentile benchmarks by role

Returns P25, median, P75, and mean total compensation for a given role filtered by sector, state, and/or org revenue range. Data is pulled from the officer_search materialized view (paid staff on latest filings). No authentication required.

Parameters

Name	In	Type	Description
role required	query	string	Role group key (e.g. executive, development, finance, programs).
ntee	query	string	NTEE major category letter (e.g. B for Education, E for Health).
state	query	string	Two-letter US state code.
min_revenue	query	number	Minimum org revenue filter.
max_revenue	query	number	Maximum org revenue filter.

Example response

{
  "count": 124,
  "p25": 82000,
  "median": 114000,
  "p75": 156000,
  "mean": 118750
}

Responses

Status	Schema	Description
200	object	Compensation benchmark statistics.
400	ErrorResponse	Invalid request parameters.

GET

Grants

Schedule I grants and cross-filing grant search.

GET

/api/v1/filings/{object_id}/grants

List Schedule I grants for a filing

Returns Schedule I grants paid from a 990 filing.

Parameters

Name	In	Type	Description
object_id required	path	string	IRS e-file object ID.
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.

Example response

{
  "data": [
    {
      "recipient_name": "Community Food Project",
      "recipient_city": "Nashville",
      "recipient_state": "TN",
      "recipient_ein": "62-1348105",
      "cash_amount": 25000,
      "purpose": "Operating support"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated list of Schedule I grants.
400	ErrorResponse	Invalid request parameters.

GET

/api/v1/grants

Search grants across all filings

Cross-filing grant search across Schedule I, 990-PF Part XV, and related funder metadata.

Parameters

Name	In	Type	Description
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.
sort	query	string, default -amount	Sort field. Prefix with `-` for descending.
funder_ein	query	string	Filter by funder EIN.
funder_name	query	string	Search by funder organization name.
funder_ntee	query	string	Filter by funder NTEE major category.
funder_state	query	array	Filter by funder home state. Repeat for multiple states.
recipient_ntee	query	string	Filter by recipient NTEE major category or full code.
recipient_ein	query	string	Filter by recipient EIN.
similar_to	query	string	Filter to funders that also fund orgs similar to this EIN.
recipient_name	query	string	Search by recipient name.
recipient_city	query	string	Case-insensitive recipient city substring.
min_amount	query	number	Minimum grant amount.
max_amount	query	number	Maximum grant amount.
state	query	array	Filter by recipient state. Repeat for multiple states.
tax_year	query	integer	Filter by exact tax year.
min_year	query	integer	Minimum tax year, inclusive.
max_year	query	integer	Maximum tax year, inclusive.
foundation_type	query	string	Filter by foundation type. Use `990-PF` for private foundations or `990` for charitable foundations.
hide_preselected	query	boolean	When true, excludes grants from funders whose latest portfolio data explicitly marks them as closed to unsolicited applications. Funders with unknown application status are kept.
purpose	query	string	Full-text search against grant purpose.
query	query	string	Keyword search across recipient name and grant purpose.

Example request

curl "https://api.501see.app/api/v1/grants?state=TN&min_amount=10000&source=990-PF&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "funder_ein": "38-1359217",
      "funder_name": "Smith Family Foundation",
      "recipient_name": "Community Food Project",
      "recipient_city": "Nashville",
      "recipient_state": "TN",
      "recipient_ein": "62-1348105",
      "amount": 25000,
      "tax_year": 2023,
      "tax_period_begin": "2023-01-01",
      "tax_period_end": "2023-12-31",
      "object_id": "202303559349300000",
      "source": "990-PF",
      "purpose": "Operating support"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 5,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated grant search results.
400	ErrorResponse	Invalid request parameters.

GET

/api/v1/foundation-grant-landscape

Get a limited foundation grant landscape

Returns aggregate grant-history statistics and a small representative funder preview for the public Foundation Grant Search page. This is a deliberately partial response. It does not support pagination, arbitrary filters, raw grant rows, or unrestricted identifiers. Each bounded preview item includes its public EIN so it can link to the public organization profile. No authentication is required for anonymous web use. Direct API-key callers require a paid Developer API entitlement.

Parameters

Name	In	Type	Description
q	query	string	Mission, program, recipient name, or recipient EIN to search.
state	query	string	Optional recipient state filter.

Responses

Status	Schema	Description
200	object	Partial foundation grant landscape.
400	ErrorResponse	Invalid request parameters.
429	ErrorResponse	Rate limit exceeded.

GET

Private Foundations

990-PF specific data and Part XV grants paid.

GET

/api/v1/filings/{object_id}/pf

Get 990-PF financials for a filing

Returns 990-PF-specific financial data for one filing.

Parameters

Name	In	Type	Description
object_id required	path	string	IRS e-file object ID.
preset	query	string, default summary	Field preset for filing responses. Ignored if `fields` is provided.
fields	query	string	Comma-separated list of fields to return. Overrides `preset`.

Example request

curl "https://api.501see.app/api/v1/filings/202303559349300000/pf?fields=tax_year,total_revenue,total_expenses,net_assets_eoy" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "object_id": "202303559349300000",
  "ein": "38-1359217",
  "form_type": "990-PF",
  "tax_year": 2023,
  "total_revenue": 2500000,
  "total_expenses": 1800000,
  "net_assets_eoy": 12000000,
  "contributors_preselected": true
}

Responses

Status	Schema	Description
200	object	PF filing data.
404	ErrorResponse	Resource not found.

GET

/api/v1/filings/{object_id}/pf/grants

List Part XV foundation grants paid

Returns grants paid from 990-PF Part XV.

Parameters

Name	In	Type	Description
object_id required	path	string	IRS e-file object ID.
offset	query	integer, default 0, min 0	Number of items to skip (for pagination).
limit	query	integer, default 50, min 1, max 500	Maximum number of items to return.

Example response

{
  "data": [
    {
      "recipient_name": "Community Food Project",
      "recipient_city": "Nashville",
      "recipient_state": "TN",
      "recipient_ein": "62-1348105",
      "amount": 25000,
      "purpose": "Operating support",
      "relationship": "independent",
      "status": "paid"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50,
  "plan": "free"
}

Responses

Status	Schema	Description
200	object	Paginated list of PF grants paid.
400	ErrorResponse	Invalid request parameters.

POST

Exports

Asynchronous CSV exports.

POST

/api/v1/exports

Create a CSV export job

Creates an asynchronous export job for the given resource type and filters. Poll `GET /api/v1/exports/{id}` until `status=completed`, then download the file from `file_url`. Requires Developer Pro. Each export is capped at 100,000 rows. If the matching result set is larger, the export completes with the first 100,000 rows and reports the exported count in `row_count`.

Request body

Field	Type	Description
resource_type required	string
filters	object	Same filter params as the corresponding list/search endpoint.
notify_email	string	Optional email address for completion notification.

Example request

curl "https://api.501see.app/api/v1/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_type":"grants","filters":{"state":"TN","min_amount":10000}}'

Example response

{
  "id": "exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
  "account_id": "acct_01J3NQ0G3P4V8C7H2K6W1M9D8X",
  "status": "pending",
  "resource_type": "grants",
  "filters": {
    "state": "TN",
    "min_amount": 10000
  },
  "fields": [],
  "created_at": "2026-06-03T12:00:00Z"
}

Responses

Status	Schema	Description
202	Export	Export job accepted
400	ErrorResponse	Invalid request parameters.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
429	ErrorResponse	Rate limit exceeded.

GET

/api/v1/exports

List exports for the authenticated account

Example request

curl "https://api.501see.app/api/v1/exports" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
      "account_id": "acct_01J3NQ0G3P4V8C7H2K6W1M9D8X",
      "status": "completed",
      "resource_type": "grants",
      "row_count": 124,
      "file_url": "https://files.501see.app/exports/exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2.csv",
      "created_at": "2026-06-03T12:00:00Z",
      "completed_at": "2026-06-03T12:02:11Z"
    }
  ]
}

Responses

Status	Schema	Description
200	object	Exports for the current account
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.

GET

/api/v1/exports/{id}

Get an export job by ID

Parameters

Name	In	Type	Description
id required	path	string

Example request

curl "https://api.501see.app/api/v1/exports/exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": "exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
  "account_id": "acct_01J3NQ0G3P4V8C7H2K6W1M9D8X",
  "status": "completed",
  "resource_type": "grants",
  "row_count": 124,
  "file_url": "https://files.501see.app/exports/exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2.csv",
  "created_at": "2026-06-03T12:00:00Z",
  "completed_at": "2026-06-03T12:02:11Z"
}

Responses

Status	Schema	Description
200	Export	Export job
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
404	ErrorResponse	Resource not found.

DELETE

/api/v1/exports/{id}

Delete an export job by ID

Parameters

Name	In	Type	Description
id required	path	string

Example request

curl -X DELETE "https://api.501see.app/api/v1/exports/exp_01J3NQ2Z2T7B7R3Y1QW8T8G5F2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "status": "ok"
}

Responses

Status	Schema	Description
200	object	Deleted
401	ErrorResponse	Authentication required.
404	ErrorResponse	Resource not found.

GET

Webhooks

GET

/api/v1/webhooks

List webhook endpoints

Returns webhook endpoints for the authenticated account. Secrets are omitted after creation.

Example request

curl "https://api.501see.app/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "public_id": "wh_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
      "account_id": 123,
      "url": "https://example.test/webhook",
      "active": true,
      "subscriptions": [
        {
          "event_type": "foundation.grant.created",
          "target_type": "funder",
          "target_key": "12-3456789",
          "active": true
        }
      ],
      "created_at": "2026-07-22T12:00:00Z",
      "updated_at": "2026-07-22T12:00:00Z"
    }
  ]
}

Responses

Status	Schema	Description
200	object	Webhook endpoints for the authenticated account.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
429	ErrorResponse	Rate limit exceeded.

POST

/api/v1/webhooks

Create a webhook endpoint

Creates a signed webhook endpoint. If subscriptions are omitted, the endpoint defaults to `data.refresh.completed` on the account.

Request body

Field	Type	Description
url required	string	HTTPS destination URL. localhost loopback HTTP is allowed in development.
subscriptions	array	Webhook subscription objects with event_type, target_type, and optional target_key.
active	boolean	Optional active flag.

Example request

curl -X POST "https://api.501see.app/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.test/webhook",
    "subscriptions": [
      {
        "event_type": "data.refresh.completed",
        "target_type": "account"
      },
      {
        "event_type": "foundation.grant.created",
        "target_type": "funder",
        "target_key": "12-3456789"
      }
    ],
    "active": true
  }'

Example response

{
  "public_id": "wh_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
  "account_id": 123,
  "url": "https://example.test/webhook",
  "secret": "whsec_9b6a0d1a2f3c4e5f6789012345678901",
  "active": true,
  "subscriptions": [
    {
      "event_type": "data.refresh.completed",
      "target_type": "account",
      "active": true
    },
    {
      "event_type": "foundation.grant.created",
      "target_type": "funder",
      "target_key": "12-3456789",
      "active": true
    }
  ],
  "created_at": "2026-07-22T12:00:00Z",
  "updated_at": "2026-07-22T12:00:00Z"
}

Responses

Status	Schema	Description
201	WebhookEndpoint	Created webhook endpoint. The secret is returned only on this response.
400	ErrorResponse	Invalid request parameters.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
429	ErrorResponse	Rate limit exceeded.

PATCH

/api/v1/webhooks/{id}

Update a webhook endpoint

Update the URL, active flag, subscriptions, or any combination of those fields. At least one field is required.

Parameters

Name	In	Type	Description
id required	path	string

Request body

Field	Type	Description
url	string
active	boolean
subscriptions	array	Replaces the endpoint's subscriptions when provided. An empty array resets to the default account-level refresh subscription.

Example request

curl -X PATCH "https://api.501see.app/api/v1/webhooks/wh_01J3NQ2Z2T7B7R3Y1QW8T8G5F2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "subscriptions": [
      {
        "event_type": "data.refresh.completed",
        "target_type": "account"
      }
    ]
  }'

Example response

{
  "public_id": "wh_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
  "account_id": 123,
  "url": "https://example.test/webhook-v2",
  "active": false,
  "subscriptions": [
    {
      "event_type": "data.refresh.completed",
      "target_type": "account",
      "active": true
    }
  ],
  "created_at": "2026-07-22T12:00:00Z",
  "updated_at": "2026-07-22T12:15:00Z"
}

Responses

Status	Schema	Description
200	WebhookEndpoint	Updated webhook endpoint.
400	ErrorResponse	Invalid request parameters.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
404	ErrorResponse	Resource not found.
429	ErrorResponse	Rate limit exceeded.

DELETE

/api/v1/webhooks/{id}

Delete a webhook endpoint

Deactivates the endpoint and all webhook subscriptions attached to it.

Parameters

Name	In	Type	Description
id required	path	string

Example request

curl -X DELETE "https://api.501see.app/api/v1/webhooks/wh_01J3NQ2Z2T7B7R3Y1QW8T8G5F2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "status": "ok"
}

Responses

Status	Schema	Description
200	object	Webhook endpoint deactivated.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
404	ErrorResponse	Resource not found.
429	ErrorResponse	Rate limit exceeded.

GET

/api/v1/webhook-deliveries

List webhook deliveries

Returns delivery history for the authenticated account. Filter by `endpoint_id` to scope to one endpoint.

Parameters

Name	In	Type	Description
endpoint_id	query	string	Optional webhook endpoint public ID.
limit	query	integer, default 50, min 1, max 100	Maximum deliveries to return.

Example request

curl "https://api.501see.app/api/v1/webhook-deliveries?endpoint_id=wh_01J3NQ2Z2T7B7R3Y1QW8T8G5F2&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "public_id": "ndl_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
      "channel": "webhook",
      "destination": "https://example.test/webhook",
      "status": "delivered",
      "attempts": 1,
      "payload": {
        "event_id": "evt_01J3NQ2Z2T7B7R3Y1QW8T8G5F2",
        "event_type": "foundation.grant.created"
      },
      "created_at": "2026-07-22T12:30:00Z"
    }
  ]
}

Responses

Status	Schema	Description
200	object	Webhook deliveries for the authenticated account.
400	ErrorResponse	Invalid request parameters.
401	ErrorResponse	Authentication required.
403	ErrorResponse	Plan or Developer API tier is insufficient for this operation.
429	ErrorResponse	Rate limit exceeded.

GET

MCP

GET

/mcp

Open MCP SSE session

Opens a remote MCP-over-SSE session using the same API key auth and endpoint gates as the public REST API. The exposed toolset is limited to public developer API capabilities.

Responses

Status	Schema	Description
200	object	SSE stream established.
401	object	Missing or invalid API key.
403	object	API key is valid but the requested MCP capability is not available.
429	ErrorResponse	Rate limit exceeded.

POST

/mcp

Send MCP message

Sends an MCP message to an existing SSE session. Uses the same API key auth and endpoint gates as the public REST API.

Responses

Status	Schema	Description
200	object	Message accepted.
401	object	Missing or invalid API key.
403	object	API key is valid but the requested MCP capability is not available.
429	ErrorResponse	Rate limit exceeded.

Integrations

These integration surfaces are designed for both human workflows and agent workflows. Start with the OpenAPI schema when you want a formal contract, then use MCP for tool-driven automation.

OpenAPI schema

Use the OpenAPI document for code generation, SDKs, and tools that need a machine-readable contract.

Download OpenAPI schema

Postman collection

Fork the public collection into your Postman workspace to explore requests, set your API key, and make your first call.

Open in Postman

Remote MCP configuration

{
  "mcpServers": {
    "501see": {
      "type": "sse",
      "url": "https://api.501see.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}