n8n-nodes-govinbox
n8n community node for GovInbox.
GovInbox watches U.S. federal contracting data and turns it into plain-English records you can search and automate: contract opportunities, award history, recompetes, SAM.gov exclusions, GAO bid protests, agency small business goals, SBA size standards and GSA labor rate bands. Set-aside programs (SDVOSB, 8(a), HUBZone, WOSB and others) are one of the filters you can apply, not a limit on what you can search.
This node connects n8n to the GovInbox REST API so you can pull that data into workflows, on a schedule or as a tool for an AI agent.
Install
In n8n, open Settings, Community nodes, Install and enter the package name:
n8n-nodes-govinbox
Accept the community node notice and install. For other installation methods, see n8n's guide to installing community nodes.
Once the package is approved for the verified list, it also appears directly in the nodes panel.
Credentials
The node authenticates with a personal GovInbox API token, sent as Authorization: Bearer <token>.
- Sign in at getgovinbox.com and open your account page.
- Generate an API token. It is shown once, so copy it right away.
- In n8n, create a GovInbox API credential and paste the token into the API Token field.
Saving the credential runs a test request (GET /v1/me) to confirm the token works. That request counts as one call against your allowance.
Operations
The node is built in n8n's declarative style: each operation is one request to the GovInbox REST API at https://api.getgovinbox.com.
| Resource | Operation | API request | What it does |
|---|
| Opportunity | Search | GET /v1/opportunities | Search opportunities by set-aside program, NAICS code, keyword, place-of-performance state, agency, work type and how recently they were first seen. |
| Opportunity | Get | GET /v1/opportunities/{notice_id} | One opportunity with its full record, early signals and contracting contacts. Optional receipts and headcount add a size standard comparison. |
| Opportunity | Get Contacts | GET /v1/opportunities/{notice_id}/contacts | Contracting contact cards published on the notice. |
| Opportunity | Get Contract History | GET /v1/opportunities/{notice_id}/contract-history | Prior awards for the same kind of work: who won, for how much and when. |
| Recompete | Get Many | GET /v1/recompetes | Opportunities flagged as likely recompetes, with the incumbent and the expiring award. |
| Recompete | Get for Opportunity | GET /v1/opportunities/{notice_id}/recompete | The recompete verdict for one opportunity, with candidate prior awards. |
| Exclusion | Check | GET /v1/exclusions/check | Is a firm or person on the SAM.gov exclusion list? Search by name, UEI or CAGE code. |
| Protest | Search | GET /v1/protests | GAO bid protest docket entries by solicitation number, agency and status. |
| Reference | Get Agency Goals | GET /v1/agency-goals | Which agencies are behind or ahead of their small business goal for a program. |
| Reference | Get Size Standard | GET /v1/size-standards/{naics} | SBA size standard for a NAICS code. |
| Reference | Get Labor Rates | GET /v1/labor-rates | GSA CALC ceiling-rate bands per labor category. |
| Reference | Get Set-Aside Programs | GET /v1/set-asides | Every program GovInbox tracks, with its official SAM.gov codes. |
| Reference |
Operations marked Write change your GovInbox account. Every other operation only reads data.
Parameter names sent to the API (program, naics, q, state, agency, days, limit, offset, work_type, min_confidence, include_awards, and so on) match the REST API exactly. Optional filters live under Additional Fields.
What the node does not cover yet
The node only wraps endpoints that the GovInbox REST API serves today. Award history is available through Opportunity, Get Contract History (prior awards by the same NAICS code) and through the recompete operations. Other GovInbox data, such as reported subawards and grants, is not exposed by the REST API at this time, so it has no node operation yet. New operations will be added as the API grows.
Example workflow
examples/daily-opportunity-digest.json is a small workflow you can import into n8n. It runs every morning, searches for opportunities first seen in the last day in NAICS 5617 (services to buildings) with work performed in Virginia, and passes each result to the next node. Replace the last node with Slack, email, a spreadsheet or a CRM.
To build it by hand:
- Add a Schedule Trigger.
- Add a GovInbox node: Resource Opportunity, Operation Search, and under Additional Fields set NAICS Code
5617, State VA and Days Since First Seen 1.
- Connect any node that should act on each opportunity.
Use as an AI agent tool
The GovInbox node is marked usableAsTool: true, so you can connect it to the Tools input of an n8n AI Agent node. The agent chooses the resource and operation and fills in the parameters from the conversation. Ask, for example, "Which opportunities for janitorial work were posted in Washington this week?" or "Is Acme Construction LLC on the SAM exclusion list?"
Notes:
- On self-hosted n8n, community nodes are offered as agent tools only when your instance allows it. See n8n's documentation for the setting that applies to your version.
- Each tool call is one API request and counts against your allowance (see below).
- The write operations (Watchlist create, delete and restore) are also available to the agent. If you do not want an agent changing your watchlists, give it a separate GovInbox node that only uses read operations, or review its tool calls.
Paging and output
List operations (Opportunity Search, Recompete Get Many, Protest Search, Reference Get Agency Goals, Watchlist Get Many) return one page.
- Limit sets the page size (1 to 100).
- Offset, under Additional Fields, skips results so you can fetch the next page. Add the Limit to the Offset for each following page and stop when a page returns fewer results than the limit.
- Split Into Items (on by default) returns each result as its own n8n item. Turn it off to receive the full API response as one item, including
total, limit and offset.
Operations that return one record, or reference data with its own as_of and status fields, return the response as a single item.
Usage allowance
Every authenticated API call, including the credential test, counts against the daily request allowance of the GovInbox account that owns the token. The allowance is shared with other ways of using the same account. When it is used up, the API answers with HTTP 429 and n8n shows the error on the node. Use Account, Get to see the remaining allowance.
Verification checklist
This section maps each n8n requirement for community nodes, and for the verified badge, to how this package meets it. The requirements were read from n8n's documentation (cited under each row); where n8n's pages have moved, both the current and the former address are given.
Sources:
- Verification guidelines: https://docs.n8n.io/connect/create-nodes/build-your-node/reference/verification-guidelines (former address: https://docs.n8n.io/integrations/creating-nodes/build/reference/verification-guidelines/)
- Submit community nodes: https://docs.n8n.io/connect/create-nodes/deploy-your-node/submit-community-nodes (former address: https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/)
- Using the
n8n-node tool: https://docs.n8n.io/connect/create-nodes/build-your-node/using-the-n8n-node-tool
- UX guidelines: https://docs.n8n.io/connect/create-nodes/build-your-node/reference/ux-guidelines
- Credentials files: https://docs.n8n.io/connect/create-nodes/build-your-node/reference/credentials-files
- Codex files: https://docs.n8n.io/connect/create-nodes/build-your-node/reference/codex-files
- Declarative-style tutorial: https://docs.n8n.io/connect/create-nodes/build-your-node/tutorial-build-a-declarative-style-node
- Starter repository: https://github.com/n8n-io/n8n-nodes-starter
- npm provenance: https://docs.npmjs.com/generating-provenance-statements
| # | n8n requirement | Source | How this package meets it |
|---|
| 1 | Package name starts with n8n-nodes- or @scope/n8n-nodes- | 2, 3 | Package name is n8n-nodes-govinbox. |
| 2 | n8n-community-node-package keyword in package.json | 2, 7 | Present in keywords. |
| 3 | Nodes and credentials listed in the n8n block of package.json | 2, 7, 8 | n8n.nodes points to dist/nodes/GovInbox/GovInbox.node.js; n8n.credentials points to dist/credentials/GovInboxApi.credentials.js; n8nNodesApiVersion is 1 and strict is true, as in the starter. |
| 4 | Generated with, and checked by, the n8n-node tool | 1, 3 | Uses @n8n/node-cli for build, lint, dev and release, with the starter's tsconfig.json, ESLint config and scripts. |
| 5 | Linter passes (npm run lint) | 2, 3 | npm run lint runs n8n-node lint and passes with no errors or warnings. |
| 6 | Declarative style preferred (needed for fast approval on n8n Cloud); triggers must be programmatic | 1, 3 | Declarative style only: every operation is a routing.request in the node description, with no custom execute code. The package has no trigger. |
| 7 | Integrates one third-party service and does not duplicate an existing node | 1 | One service: the GovInbox REST API. No existing n8n node for it. |
| 8 | No logic or flow-control nodes | 1 | Single action node. |
| 9 | No runtime dependencies | 1, 2 | dependencies is empty. n8n-workflow is a peer dependency; everything else is a development dependency. scripts/smoke.mjs asserts this. |
| 10 | No access to environment variables or the file system; pass data through node parameters |
Development
npm ci
npm run lint # n8n-node lint
npm run build # n8n-node build
npm run smoke # checks the built description (no network)
npm run dev # runs n8n with the node loaded (needs Docker or Podman)
npm run smoke loads the compiled node and credential from dist/ and asserts the resources, operations, request routes, parameter names and package contract. It makes no network calls.
Testing against the API
Any request the node sends can be reproduced with curl. For example, the Opportunity Search request for NAICS 5617 in Washington, first seen in the last 30 days:
curl -s -H "Authorization: Bearer $GOVINBOX_TOKEN" \
"https://api.getgovinbox.com/v1/opportunities?limit=5&naics=5617&state=WA&days=30"
End-to-end test of the built node
scripts/e2e/ runs the compiled node through n8n's own execution engine (n8n-core) against a GovInbox API and checks the response of every operation. It is not part of the published package and adds no dependencies to it.
npm run build
npm install --no-save n8n-core@latest [email protected]
GOVINBOX_TOKEN=... node scripts/e2e/e2e.cjs # read operations only
GOVINBOX_TOKEN=... E2E_WRITE=1 node scripts/e2e/e2e.cjs # also creates, deletes and restores a test watchlist
Set GOVINBOX_BASE to test against another API host. Every call counts against the allowance of the account that owns the token.
Publishing
Publishing is done from GitHub Actions only (see publish.yml):
- Create the public repository
AUsernameForYou/n8n-nodes-govinbox and push this code.
- Configure npm trusted publishing for the package, or add an
NPM_TOKEN repository secret.
- Set the version in
package.json, push, and publish a GitHub release tagged v<version>.
- Run
npx @n8n/scan-community-package n8n-nodes-govinbox and fix anything it reports.
- Submit the package in the n8n Creator Portal.
Links
License
MIT
