How to Use the Bid Banana API

◆ NOTE: API access, services and features are only available via the purchase of a dedicated Bid Banana API subscription. A Bid Banana Search subscription does not include API access or any API credits. The two are billed separately, and having one does not give you the other.

The Bid Banana API gives you programmatic access to the same data behind Search: more than 1.6 million open bids, closed bids and awarded contracts across all 50 US states, refreshed daily. It is one REST endpoint — you POST JSON containing your API key and search criteria, and JSON is returned. A subscription is $499.99 a year and covers 10,000 returned records per month. Visit the API tab in the navigation bar to read the full developer reference documentation, try a live query without a key, and/or review the checkout page for a standard API subscription.

What Is the Bid Banana API?

The Bid Banana API provides an access point to Bid Banana's bid database without the interface. Instead of typing a keyword into Search and reading result cards, your software sends a request and receives structured records it can store, filter, display or act on. It serves the same three datasets in the bid status toggle:

• Open bids: active solicitations that are still accepting responses.
• Closed bids: solicitations past their deadline, for research and timing.
• Awarded contracts: winning vendors, award values, and contract terms.

Examples of bid record fields include the title, agency, state, key dates, budget range, the buyer's contact, the source URL, and any attached documents.

Awarded contract records carry additional fields (examples include the winning vendor, the award value, and the contract dates).

Who Is the Bid Banana API For?

Like most APIs, the Bid Banana API is intended for anyone who would rather query the data than click through it. That could be anyone: a single subscriber building an integrated workflow to automate a weekly bid search; a team of developers collaborating on a new product.

💡 Tip: Use the Search tool if you are simply looking to find bids for your organization. It's the faster tool!

API plans come in two flavors: the default standard plan and the partner plan.

1. Standard: The Bid Banana API default subscription is accessible via a self-serve checkout. This is the plan you'll want if you're pulling data for your organization's internal users. No need to become a partner, fill out contact forms, or wait for approval or provisioning; just go directly to checkout.
2. Partner: The API partnership route exists for higher volume than the standard plan allows, or for redistributing our data to an audience of your own. Use the form on the API page to apply; reach out with any questions.

◆ NOTE: The Bid Banana Search subscription does not include API access or any API credits. The two are billed separately, and having one does not give you the other. You do need a Bid Banana account to purchase the API.

How Much Does the Bid Banana API Cost?

The default plan is called Bid Banana API — Standard. It's an annual plan that's available to Bid Banana subscribers for $499.99 a year.

💡 Tip: If you need higher limits, premium fields or a custom contract, you may want to look into our Enterprise plan. Use the Talk to us link on the API page.

How Do I Get Bid Banana API Access?

1. Click the API tab in the navigation bar.
2. Scroll down to the Get API access section and click the button.
3. Complete checkout. Enter your organization's name, a billing address, and payment details. There is no approval step and no waiting for provisioning.
4. Upon completing checkout, you'll be directed to your API dashboard, where you can create your keys and start making calls.

💡 Tip: Try it before you buy it. The playground under Try it right now on the same page runs live queries against real data with no key and no signup, so you can see exactly what comes back before you subscribe.

Where Do I Create My API Keys?

Create, manage, and adjust your API keys anytime by visiting Account Settings > API.

From your Account Settings API page, you can:

• Check your API subscription status and limits: See your account display name, status, and your monthly usage limits (Standard, 10,000 records a month)
• Create and manage your API keys: Click Create key to create your first API key. API keys begin with bbsk-.
• Quick start: Copy a ready-made request after you've made your first key. You'll also find links to the API docs and the live playground.

Every key on the page authenticates against the API, and deleting one revokes it immediately. When you rotate a key, create the replacement, then swap it in before you delete the old one.

◆ NOTE: There is no separate API user account to set up, and nothing to request. The key is the whole credential — send it in the request body and you are authenticated.

How Do I Make My First API Call?

Every request is a POST to https://v1.api.bidbanana.com with your key in the body alongside the search criteria. There are no per-resource paths to learn and no separate auth call — that is the whole integration.

In your Quick start block on your API page, you'll find a sample request asking for a list of relevant bids within a state that mention a key service or asset (for example: a sample request for the 25 most relevant bids in Texas that mention playground equipment).

With no category set, it returns open bids:

curl https://v1.api.bidbanana.com -d '{"api_key": "YOUR_API_KEY", "keywords": "playground equipment", "state": "TX", "max_results": 25}'

💡 Tip: Keep your key server-side. Because it travels in the request body, any call made from a browser exposes it to whoever is looking. Read it from an environment variable and call the API from your backend.

What Parameters Can I Send?

A specific service keyword or phrase beats a broad category. How to Search Using Keywords and Filters covers how to phrase one, and the same phrasing works well in the keywords parameter.

What Comes Back in a Response?

A JSON object with a response_id, timing values, an echo of the parameters you sent, a found_count and a results array. Each record in that array groups its fields into:

• Identity: title, agency, solicitation ID and type, industry, NAICS code and both a full and a short description.
• Dates: open and close dates; whether the close date renews; questions due; pre-bid meeting and site visit dates and whether they are mandatory; and project duration.
• Money: a human-readable budget, a low and high USD estimate and the rationale behind the estimate.
• Contact: the buyer's name, role, email and phone, and where the source published them.
• Links and documents: the original source URL, a Bid Banana page URL, flags for whether the source requires a login or payment and a doc_files array of attachments.

◆ NOTE: the download URLs inside doc_files are signed and short-lived. Download the file as soon as you have the response, and never store the URL or hand it to a browser — it will have expired by the time anything else tries to use it.

Most errors arrive as HTTP 200 with an error string in the body, so check for that field on every response rather than trusting the status code alone. A malformed body or unknown operation returns 400, a body over 64 KB returns 413 and an internal fault returns 500.

What Counts Against My 10,000 Monthly Records?

Records returned, not API calls. A single request that comes back with 117 matches uses 117 of your 10,000 records for the month. That makes max_results the parameter worth thinking about hardest: asking for 1,000 records to display 10 of them spends the other 990 for nothing.

Your usage sits on the API Billing page. If you exhaust the allowance, requests stop returning results until the next monthly period begins — nothing breaks, but nothing comes back either.

How Do I Keep My Copy of the Data in Sync?

Use the timestamps rather than re-pulling everything. Records are refreshed daily from their source agencies, and every result carries a last_updated_ms1970 value. Store the highest one you have seen, then send it back as updated_since_ms1970 on your next run, and you get only what has changed. A nightly incremental sync built this way costs a fraction of the records a full re-pull would.

Can I Show Bid Banana Data to My Own Users?

It depends on the volume and on how you present it, so treat it as a conversation rather than a yes or no. This data is Bid Banana's product, and we are deliberate about where it ends up. Every result does include a bb_page_url_partner link, which opens the bid on Bid Banana without blocking anonymous view counts — that is the intended way to hand a specific bid off to one of your users. For anything broader, use the partnership route.

How Do I Apply for a Bid Banana API Partnership?

Fill out the form at the bottom of the API tab. It asks for your company and website, what you are building and who your customers are, how you would use the data, roughly how many people would reach it through your product and what data you need. The more concretely you answer, the faster the conversation moves. Then:

1. A person reads it, usually within two business days.
2. If it looks like a fit, we scope your data access, rate limits and pricing together on a call.
3. You sign a partnership agreement, and your access is provisioned.

The strongest applications come from products that are past prototype, have a defined audience that would act on the opportunities and can point to where the data would sit in the product.

If you only need the data internally, you do not need any of this — subscribe to the standard plan instead.

Where Do I Get Help With the API?

Start with the full developer reference, which lists every parameter, every response field and the error behavior in detail (API settings tab in your Account Settings > API page links to it, and to the live playground, from the Quick start section. If something still looks wrong, email [email protected] or contact support the usual way, and include the response_id from the response you are asking about — it lets us find the exact call rather than guess at it.