GFIN API
Search normalized funding opportunities, evaluate eligibility against an organization profile, and receive change events. REST over HTTPS, JSON in and out.
1.0.0-preview and the surface is not yet generally available. Operations not listed below are marked x-gfin-status: planned in the OpenAPI document and are not implemented; calling one returns 404. We publish what is live rather than what is intended.What is live today
Six operations. This is the complete set: nothing else on the /v1 surface responds yet.
| Operation | Method and path | What it does |
|---|---|---|
ping | GET /ping | Confirms a credential is valid and shows its identity and scopes. No scope required. |
listOpportunities | GET /opportunities | The unpersonalized catalog, with keyword, funder, source, state and deadline filters. |
evaluateEligibility | POST /eligibility/evaluate | Evaluates one opportunity against your organization profile. |
getUsage | GET /usage | Metered usage for the current period, per capability. |
listWebhookEndpoints | GET /webhook-endpoints | Your organization’s webhook subscriptions. |
Not yet enabled
These are published in the contract, with their request and response shapes final, but they do not work yet. They are listed separately rather than mixed into the table above, because an operation you can read about and cannot call is worth knowing about before you build against it.
| Operation | Method and path | What happens if you call it |
|---|---|---|
createWebhookEndpoint | POST /webhook-endpoints | Answers 503 with code UNSUPPORTED_OPERATION for every caller. Webhook delivery is not switched on yet, and registering an endpoint that could never receive anything would leave you believing you were subscribed. GET /webhook-endpoints works and returns an empty list. |
Base URL
Three things that will surprise you
Most of this API behaves the way you expect. These three do not, and each one has bitten someone already.
| Behaviour | Why |
|---|---|
deadline is not always a date | A dated deadline is an RFC 3339 timestamp, not a date-only string, and a rolling one is the literal string Rolling. Date-window filters are type bracketed, so deadline_from and deadline_to exclude rolling rows: a rolling deadline is not “before October”. |
| Absence is a value | A missing fact is null, never a zero, a default or an empty string standing in for one. If we cannot read an award ceiling we say null. A score is never fabricated to fill a field. |
| Test keys never see real data | A gfin_test_ key is served a small fixed set of synthetic fixtures and never reads the catalog. Same schemas, same pagination, same filters, same errors, so your integration code behaves the same in production. The one exception is q, which matches on substring in the sandbox rather than the live keyword index. See test and live keys. |
Where to go next
The quickstart takes you from a key to a parsed response. Authentication covers key format, scopes and rate limits. Errors is the reference for every code the surface emits.
| Page | Read it when |
|---|---|
| Quickstart | You want a working call in the next few minutes. |
| Authentication | You are wiring up credentials, scopes, or handling a 401 or 429. |
| Errors | You got a status you did not expect and want to know whether to retry. |
| Changelog | You want to know what changed in the contract and how we handle breaking changes. |