Quickstart

From an API key to a parsed response. Every sample below calls an operation that is live today.

1. Create a key

Keys are created from Settings, API keys inside the GFIN app. A key is shown once, at creation. We store a hash, not the key, so a lost key cannot be recovered and has to be replaced.

Start with a test key. It costs nothing, it is never billed, and it cannot touch real data.

2. Confirm the key works

GET /ping requires no scope. It is the fastest way to tell a bad key from a bad request.

curl
curl https://api.gofunditnow.com/v1/ping \
  -H "Authorization: Bearer $GFIN_API_KEY"
200 response
{
  "object": "ping",
  "credential_id": "cred_66d09a2b8f1e4c2a91b3f701",
  "organization_id": "org_4f2b18c7",
  "environment": "test",
  "scopes": ["opportunities:read", "eligibility:execute"]
}

If this returns 401 INVALID_CREDENTIAL, the key is wrong, revoked, or was copied with surrounding whitespace. If it returns 404, the surface is not enabled for your deployment.

3. Read the catalog

curl
curl -G https://api.gofunditnow.com/v1/opportunities \
  -H "Authorization: Bearer $GFIN_API_KEY" \
  --data-urlencode "q=workforce development" \
  --data-urlencode "state=NC" \
  --data-urlencode "limit=25"
200 response (truncated)
{
  "data": [
    {
      "id": "opp_66d09a2b8f1e4c2a91b3f701",
      "title": "Workforce Innovation and Opportunity Act, Youth Formula",
      "funder_name": "Department of Labor",
      "deadline": "2027-01-15T23:59:59Z",
      "award_min": 25000,
      "award_max": 150000,
      "eligible_applicant_types": ["nonprofit", "local_government"]
    }
  ],
  "page": { "has_more": true, "next_cursor": "66d09a2b8f1e4c2a91b3f701" }
}

Pagination

Cursor based. Pass page.next_cursor back as the cursor parameter and stop when has_more is false. Do not stop on an empty data array alone and do not construct a cursor yourself: it is an opaque token, and a malformed one is 400 INVALID_CURSOR.

Python, paginate
import os

from gfin_api import GFINClient

client = GFINClient(os.environ["GFIN_API_KEY"])

cursor, rows = None, []
while True:
    page = client.list_opportunities(state="NC", limit=100, cursor=cursor)
    rows.extend(page["data"])
    if not page["page"]["has_more"]:
        break
    cursor = page["page"]["next_cursor"]
deadline has two shapes and both break naive parsing. A dated deadline is an RFC 3339 timestamp (2027-01-15T23:59:59Z), not a date-only string, and a rolling deadline is the literal string Rolling. So date.fromisoformat(row["deadline"]) raises on every live row on Python before 3.11, and then raises again on the rolling ones. Check for Rolling first, then parse as a datetime.

4. Evaluate eligibility

The organization is taken from your credential and is not a parameter. This operation is metered, so send an Idempotency-Key: if the response is lost in transit, a retry with the same key replays the original result instead of evaluating and charging twice.

curl
curl -X POST https://api.gofunditnow.com/v1/eligibility/evaluate \
  -H "Authorization: Bearer $GFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0f4a-3b7e-4a21-9c55-8e0d2f77aa10" \
  -d '{"opportunity_id": "opp_66d09a2b8f1e4c2a91b3f701"}'

Generate the key once per logical call and reuse it across retries of that call. Reusing one key for a different body is 409 IDEMPOTENCY_CONFLICT, which is the store telling you two different requests are wearing the same name. Replay is implemented for this operation; see Idempotency for where it does and does not apply today.

A verdict is one of likely_eligible, not_eligible or needs_profile. There is no “eligible”: a single unknown gate withholds a positive verdict rather than guessing past it, and needs_profile means we could not decide, which is not the same as no.

Use an SDK instead

Both SDKs carry the two rules that are easy to get wrong by hand: every POST gets an idempotency key generated once and reused across retries, and a quota error is never retried, because a backoff cannot restore a monthly allowance.

Install
pip install gfin-api
npm install @gofunditnow/api
TypeScript
import { GFINClient } from "@gofunditnow/api";

const client = new GFINClient(process.env.GFIN_API_KEY!);
const page = await client.listOpportunities({ q: "workforce development", limit: 25 });
The SDKs are not published to PyPI or npm yet. Until they are, install them from the repository. We would rather say that than print an install command that fails.

Test and live keys

A gfin_test_ key is served a small fixed set of synthetic fixtures and never reads the real catalog. The schemas, pagination and error semantics are identical to live, so integration code written against the sandbox behaves the same in production, but the records are obviously fake: source gfin_sandbox, titles prefixed Sandbox. They are not real funding opportunities and must never be shown to your users as such.

Sandbox usage is recorded but is never billed and never counts against your quota. Filters behave as they do live, with one documented exception: sandbox q is a case-insensitive substring match rather than the live keyword index. It is the more permissive of the two, so a sandbox query may return fewer rows in production, never more.

The environment is a property of the credential, not a request parameter. There is no header or flag that switches a live key into the sandbox.