[{"procedure":"whoami","versions":[{"version":"2026-07-20","description":"Who the caller is: the signed-in user (when the credential names one), the organization the credential belongs to, and that organization's subscription and plan. CALL THIS FIRST, before any other procedure. It answers three things nothing else does: who you are talking to and what to call them, which organization's data every other procedure will read and rank against, and — most importantly — what plan they are on, which decides whether the other procedures return results or an upgrade message. Knowing the plan up front means you can tell the user what is available instead of discovering it by calling a procedure and failing. It also returns the organization's matching profiles, so a single call gives you the `matchingProfileId` the search procedures require alongside the location filters and NAICS codes that explain their results. `user` is null when authenticating with a REST API key, which is issued to an organization rather than a person — that is expected, and the organization and subscription are still fully populated. Takes no request body. Available on every plan, including the free plan. Unexpected failures return 500.","plans":["free","starter","professional","business"],"requestSchema":null,"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"plan":{"description":"The organization's Bidscope tier, and the field to branch on. \"free\" means most procedures will return an upgrade message instead of results; \"starter\" and above unlock all of them. Derived from the active subscription, so it is reliable even when `subscription.plan` is null or unrecognised. Example: \"professional\".","type":"string","enum":["free","starter","professional","business"]},"user":{"description":"The person behind the credential, or null when there is no person to name. Null is an EXPECTED result, not an error: a REST API key is issued to an organization and carries no user, so it always returns null here. An MCP connection authorized through Bidscope's OAuth flow is granted by a signed-in user and returns their record. When this is null, `organization` and `subscription` are still fully populated — describe the caller by their organization instead, and do not report a failure or ask the user to re-authenticate.","anyOf":[{"type":"object","properties":{"id":{"description":"The user's Bidscope id. Example: \"9f3c1a20-7d84-4b16-a5e9-2c07f8d3b641\".","type":"string"},"email":{"description":"The email the user signs in with, with Bidscope's internal whitelabel-tenant prefix removed. Null only for an account with no email on file. Example: \"dana@acme-contracting.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"firstName":{"description":"The user's first name. Null if the user has no profile record yet — a rare state for an account that has finished signing up. Example: \"Dana\".","anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"description":"The user's last name. Null under the same conditions as `firstName`. Example: \"Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"description":"The phone number on the user's profile. Null when they never supplied one — it is optional at signup. Example: \"+15125550147\".","anyOf":[{"type":"string"},{"type":"null"}]},"company":{"description":"The company name the user typed at signup. This is free text they entered about themselves, and can differ from `organization.name`, which is the Bidscope workspace they actually work in. Prefer `organization.name` when naming the business. Example: \"Acme Contracting LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the user's profile record was created, as a UTC ISO-8601 timestamp. Example: \"2026-01-09T15:41:02.318Z\"."},"firstSignedInAt":{"type":["string","null"],"format":"date-time","description":"When the user first signed in, as a UTC ISO-8601 timestamp. Null if they have been invited but have never signed in. Example: \"2026-01-09T15:52:44.907Z\"."},"lastVisitedAt":{"type":["string","null"],"format":"date-time","description":"When the user last opened the Bidscope app, as a UTC ISO-8601 timestamp. Not updated by API or MCP calls, so it can look stale for someone who works entirely through an assistant. Example: \"2026-07-19T08:12:36.550Z\"."}},"required":["id","email","firstName","lastName","phoneNumber","company","createdAt","firstSignedInAt","lastVisitedAt"],"additionalProperties":false},{"type":"null"}]},"organization":{"description":"The organization the credential belongs to — always present, and always exactly one. Every other procedure reads and ranks against this organization, so its location filters, NAICS codes, and matching profiles explain why searches return what they return.","type":"object","properties":{"id":{"description":"The organization's Bidscope id. Example: \"4b2e7c19-8a03-4f65-9d21-6e0c5a7b3d84\".","type":"string"},"name":{"description":"The organization's name — the Bidscope workspace the credential belongs to. Example: \"Acme Contracting\".","type":"string"},"website":{"description":"The organization's website. Null if never set. Example: \"https://acme-contracting.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"When the organization was created, as a UTC ISO-8601 timestamp. Example: \"2026-01-09T15:58:11.204Z\"."},"createdByUserId":{"description":"The Bidscope id of the user who created the organization. Not necessarily the caller. Example: \"9f3c1a20-7d84-4b16-a5e9-2c07f8d3b641\".","type":"string"},"locationName":{"description":"The organization's home location, as a display name. Null until they configure one. Example: \"Austin, TX, USA\".","anyOf":[{"type":"string"},{"type":"null"}]},"locationPlaceId":{"description":"The Google Places id backing `locationName`. Null when no location is set. Example: \"ChIJLwPMoJm1RIYRetVp1EtGm10\".","anyOf":[{"type":"string"},{"type":"null"}]},"locationLatitude":{"description":"The home location's latitude. Null when unset. Example: 30.267153.","anyOf":[{"type":"number"},{"type":"null"}]},"locationLongitude":{"description":"The home location's longitude. Null when unset. Example: -97.743057.","anyOf":[{"type":"number"},{"type":"null"}]},"hasConfiguredLocation":{"description":"Whether the organization has finished setting up its location. False means the location fields are defaults, not deliberate choices. Example: true.","type":"boolean"},"locationFilterType":{"description":"How the organization limits opportunities geographically: \"none\" for no limit, \"radius\" for within `locationFilterRadiusMi` of the home location, or a region/country match. Example: \"radius\".","type":"string"},"locationFilterRadiusMi":{"description":"The radius in miles used when `locationFilterType` is \"radius\". Null otherwise. Example: 250.","anyOf":[{"type":"number"},{"type":"null"}]},"countries":{"description":"The countries the organization wants opportunities from. Null means never configured, which is NOT the same as an empty list (configured to none). Example: [\"United States\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"regions":{"description":"The states or regions the organization wants opportunities from. Null means never configured, distinct from an empty list. Example: [\"Texas\", \"Oklahoma\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"naicsCodes":{"description":"The NAICS codes the organization works under. Empty when they have not set any. Example: [\"236220\", \"238210\"].","type":"array","items":{"type":"string"}},"capabilityStatementKeys":{"description":"Storage keys for the capability statements the organization uploaded, which Bidscope read to build their smart codes. Null when none were uploaded. The documents themselves are not retrievable through this API.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"whitelabelTenantCode":{"description":"Set only for organizations on a white-labelled Bidscope deployment; null for everyone on Bidscope proper. Example: null.","anyOf":[{"type":"number"},{"type":"null"}]},"hasSmartCodesInitialized":{"description":"Whether the organization's smart codes have been set up at all. False for a brand-new organization that has not finished onboarding — searches will not be meaningfully ranked yet. Example: true.","type":"boolean"},"hasFinishedInitialSmartCodeInitialization":{"description":"Whether the FIRST smart-code build has completed. Distinct from `hasSmartCodesInitialized`, which flips as soon as the build starts. Example: true.","type":"boolean"},"isProcessingSmartCodes":{"description":"True while Bidscope is rebuilding the organization's smart codes. Searches keep working during a rebuild but may not reflect the newest edits. Example: false.","type":"boolean"},"smartCodeProcessingProgress":{"description":"How far a rebuild has got, from 0 to 1. Null when no rebuild has run. Example: 1.","anyOf":[{"type":"number"},{"type":"null"}]},"smartCodesInitialSource":{"description":"What the first smart codes were built from — a capability statement, the organization's website, or codes typed by hand. Null if never set. Example: \"website\".","anyOf":[{"type":"string"},{"type":"null"}]},"smartCodesLastUpdatedAt":{"type":["string","null"],"format":"date-time","description":"When the organization's smart codes last changed, as a UTC ISO-8601 timestamp. Null if they have never been built. Example: \"2026-06-30T11:07:52.663Z\"."},"shouldEmailOnTrackedRfpUpdate":{"description":"Whether Bidscope emails the organization when an opportunity they track changes. Example: true.","type":"boolean"},"shouldEmailGlobal":{"description":"Whether every member of the organization still accepts Bidscope email. The master email switch is per person — each member can unsubscribe themselves — so this is false once any one of them has, and silencing applies only to the members who opted out. Example: true.","type":"boolean"},"shouldEmailMilestones":{"description":"Whether Bidscope emails the organization about upcoming deadlines on the opportunities they track. Example: true.","type":"boolean"},"milestonesLastProcessedAt":{"type":"string","format":"date-time","description":"When Bidscope last swept this organization's tracked opportunities for milestones, as a UTC ISO-8601 timestamp. Example: \"2026-07-20T06:00:03.119Z\"."},"acceptedMemberProratedBillingNotice":{"description":"Whether the organization has acknowledged the notice about prorated charges when adding a member mid-cycle. Example: false.","type":"boolean"},"matchingProfiles":{"description":"The organization's matching profiles — the saved descriptions of what it wants to win — default first, then oldest first. Use a profile's `id` as the `matchingProfileId` the search procedures require. Each profile is identified by name only; the underlying smart codes Bidscope ranks against are not exposed, so pick a profile by its name rather than trying to inspect what it targets.","type":"array","items":{"type":"object","properties":{"id":{"description":"The profile's Bidscope id. This is the value every `matchingProfileId` in the search procedures expects. Example: \"c8b3a5e1-9d47-4f26-8a03-1e7b6d2f4c95\".","type":"string"},"name":{"description":"The name the organization gave the profile. Not unique. Example: \"IT Services — Federal\".","type":"string"},"isDefault":{"description":"True for the organization's default profile — the one the app selects when the user has not picked another. Exactly one profile carries true. Example: true.","type":"boolean"},"isProcessingSmartCodes":{"description":"True while Bidscope is still rebuilding this profile's smart codes. Searches against it still work but may not reflect the newest edits yet. Example: false.","type":"boolean"},"createdAt":{"type":"string","format":"date-time","description":"When the profile was created, as a UTC ISO-8601 timestamp. Example: \"2026-03-14T18:22:07.412Z\"."},"matchThreshold":{"description":"The minimum match score an opportunity must reach to count as a match for this profile. Null when the organization has not overridden Bidscope's default. Example: 0.62.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","name","isDefault","isProcessingSmartCodes","createdAt","matchThreshold"],"additionalProperties":false}},"trackingColumns":{"description":"The columns on the organization's opportunity tracking board, in display order. Empty when they have not customised it.","type":"array","items":{"type":"object","properties":{"id":{"description":"The column's Bidscope id. Example: \"1d5f8b03-4a67-4c92-b0e8-7f3a2d6c9051\".","type":"string"},"name":{"description":"The column's name, as the organization set it. Example: \"Proposal owner\".","type":"string"},"displayOrder":{"description":"Where the column sits on the organization's tracking board, ascending. Example: 2.","type":"number"}},"required":["id","name","displayOrder"],"additionalProperties":false}}},"required":["id","name","website","createdAt","createdByUserId","locationName","locationPlaceId","locationLatitude","locationLongitude","hasConfiguredLocation","locationFilterType","locationFilterRadiusMi","countries","regions","naicsCodes","capabilityStatementKeys","whitelabelTenantCode","hasSmartCodesInitialized","hasFinishedInitialSmartCodeInitialization","isProcessingSmartCodes","smartCodeProcessingProgress","smartCodesInitialSource","smartCodesLastUpdatedAt","shouldEmailOnTrackedRfpUpdate","shouldEmailGlobal","shouldEmailMilestones","milestonesLastProcessedAt","acceptedMemberProratedBillingNotice","matchingProfiles","trackingColumns"],"additionalProperties":false},"subscription":{"description":"The organization's active subscription, or null when it has none — which is exactly what puts them on the free plan. Null here always pairs with `plan: \"free\"`. No trial dates, renewal dates, or usage quotas are tracked, so none are returned.","anyOf":[{"type":"object","properties":{"id":{"description":"The subscription's Bidscope id. Example: \"6c0b4e83-2f19-4a75-8d36-1b9e7c0a5f42\".","type":"string"},"isActive":{"description":"Always true when a subscription object is present — an inactive subscription is reported as `subscription: null` instead. Kept so the shape matches the record the app reads. Example: true.","type":"boolean"},"createdAt":{"type":"string","format":"date-time","description":"When the subscription started, as a UTC ISO-8601 timestamp. Example: \"2026-02-01T09:15:27.884Z\"."},"plan":{"description":"The plan name recorded on the billing record. Null on older subscriptions that predate the column. Prefer the top-level `plan` field for any decision about what the caller can do — this one is raw billing data and can be null or unrecognised. Example: \"professional\".","anyOf":[{"type":"string"},{"type":"null"}]},"cadence":{"description":"How often the organization is billed. Null if not recorded. Example: \"yearly\".","anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"description":"How many seats the organization pays for. Example: 5.","type":"number"}},"required":["id","isActive","createdAt","plan","cadence","quantity"],"additionalProperties":false},{"type":"null"}]}},"required":["plan","user","organization","subscription"],"additionalProperties":false},"examples":[{"title":"An MCP caller on a paid plan","description":"A connection authorized through Bidscope's OAuth flow names a real user, so `user` is populated. `plan: \"professional\"` means every other tool is available; the `matchingProfiles[0].id` here is the value to pass as `matchingProfileId` when searching.","request":null,"response":{"plan":"professional","user":{"id":"9f3c1a20-7d84-4b16-a5e9-2c07f8d3b641","email":"dana@acme-contracting.com","firstName":"Dana","lastName":"Whitfield","phoneNumber":"+15125550147","company":"Acme Contracting LLC","createdAt":"2026-01-09T15:41:02.318Z","firstSignedInAt":"2026-01-09T15:52:44.907Z","lastVisitedAt":"2026-07-19T08:12:36.550Z"},"organization":{"id":"4b2e7c19-8a03-4f65-9d21-6e0c5a7b3d84","name":"Acme Contracting","website":"https://acme-contracting.com","createdAt":"2026-01-09T15:58:11.204Z","createdByUserId":"9f3c1a20-7d84-4b16-a5e9-2c07f8d3b641","locationName":"Austin, TX, USA","locationPlaceId":"ChIJLwPMoJm1RIYRetVp1EtGm10","locationLatitude":30.267153,"locationLongitude":-97.743057,"hasConfiguredLocation":true,"locationFilterType":"radius","locationFilterRadiusMi":250,"countries":["United States"],"regions":["Texas","Oklahoma"],"naicsCodes":["236220","238210"],"capabilityStatementKeys":["org/4b2e7c19/capability-statement.pdf"],"whitelabelTenantCode":null,"hasSmartCodesInitialized":true,"hasFinishedInitialSmartCodeInitialization":true,"isProcessingSmartCodes":false,"smartCodeProcessingProgress":1,"smartCodesInitialSource":"website","smartCodesLastUpdatedAt":"2026-06-30T11:07:52.663Z","shouldEmailOnTrackedRfpUpdate":true,"shouldEmailGlobal":true,"shouldEmailMilestones":true,"milestonesLastProcessedAt":"2026-07-20T06:00:03.119Z","acceptedMemberProratedBillingNotice":false,"matchingProfiles":[{"id":"c8b3a5e1-9d47-4f26-8a03-1e7b6d2f4c95","name":"IT Services — Federal","isDefault":true,"isProcessingSmartCodes":false,"createdAt":"2026-03-14T18:22:07.412Z","matchThreshold":0.62}],"trackingColumns":[{"id":"1d5f8b03-4a67-4c92-b0e8-7f3a2d6c9051","name":"Proposal owner","displayOrder":2}]},"subscription":{"id":"6c0b4e83-2f19-4a75-8d36-1b9e7c0a5f42","isActive":true,"createdAt":"2026-02-01T09:15:27.884Z","plan":"professional","cadence":"yearly","quantity":5}}},{"title":"A REST API key on the free plan","description":"An API key is issued to an organization, not a person, so `user` is null — expected, not a failure. No active subscription means `subscription` is null and `plan` is \"free\", so most other procedures will return an upgrade message; say so up front rather than calling them to find out.","request":null,"response":{"plan":"free","user":null,"organization":{"id":"7e0a2c84-3b96-4d51-8f27-6c1d9b4e0a38","name":"Northwind Builders","website":null,"createdAt":"2026-07-16T14:01:52.330Z","createdByUserId":"2a6f9d51-0c38-4e77-b924-8d1e5f3a7c60","locationName":null,"locationPlaceId":null,"locationLatitude":null,"locationLongitude":null,"hasConfiguredLocation":false,"locationFilterType":"none","locationFilterRadiusMi":null,"countries":null,"regions":null,"naicsCodes":[],"capabilityStatementKeys":null,"whitelabelTenantCode":null,"hasSmartCodesInitialized":true,"hasFinishedInitialSmartCodeInitialization":false,"isProcessingSmartCodes":true,"smartCodeProcessingProgress":0.4,"smartCodesInitialSource":"manual","smartCodesLastUpdatedAt":"2026-07-16T14:03:29.771Z","shouldEmailOnTrackedRfpUpdate":true,"shouldEmailGlobal":true,"shouldEmailMilestones":true,"milestonesLastProcessedAt":"2026-07-20T06:00:03.119Z","acceptedMemberProratedBillingNotice":false,"matchingProfiles":[{"id":"7e0a2c84-3b96-4d51-8f27-6c1d9b4e0a38","name":"Default","isDefault":true,"isProcessingSmartCodes":true,"createdAt":"2026-07-16T14:03:29.771Z","matchThreshold":null}],"trackingColumns":[]},"subscription":null}}]}]},{"procedure":"opportunities.search","versions":[{"version":"2026-07-05","description":"Search opportunities (RFPs), scored against one of your organization's matching profiles. One item is one opportunity, flattened into display columns keyed like `\"rfps.rfp_inferences.title\"`.\n\nResults are NOT restricted to open opportunities. To search only open ones, add a `rfps.status` / `enum.eq` / `\"open\"` leaf to `search.filters`; that filter also excludes anything whose due date has already passed, which reading the raw `rfps.status` field does not. The same filter is what makes `total` a real count.\n\nOrdering is `search.orderBy` + `search.sort`, NULLs last — `orderBy: \"score\"`, `sort: \"desc\"` is the usual \"best matches first\". Paging is 1-based `page` × `search.pageSize` (which must be exactly 1, 10, 25, 50, or 100). A search exposes at most 1,000 results in total: a page starting beyond that returns `{ total: 0, items: [] }`, and the page straddling the ceiling is truncated to it.\n\n`total` is `-1` (unknown) unless `search.filters` contains the open-status filter and `skipCountTotal` is unset; `-1` is normal, not an error, so page until `items` is empty. Private opportunities belonging to other organizations are never returned. Returns 404 when `matchingProfileId` does not exist, and 403 when it belongs to another organization.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"One of your organization's matching profiles. Every result's `score` measures how close the opportunity is to this profile, and `orderBy: \"score\"` ranks by it. Returns 404 when no profile with this id exists and 403 when it belongs to another organization. Example: \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query state, the same object the Bidscope app persists on a saved view. `orderBy` is one of the sortable column keys (see the enum) and `sort` is `\"asc\"` or `\"desc\"`; results are ordered by that column with NULLs last. `pageSize` must be exactly 1, 10, 25, 50, or 100. `quickSearch` is optional free text matched case-insensitively against the source title, solicitation identifier, legacy buyer name, inferred title, and buyer hierarchy name. `filters` is the recursive filter tree (`null` for no filtering) — leaves name a column and an operator, groups combine children with `isAnd`. `filterMeta` is an opaque bag the app uses to remember how the UI built the tree; the API ignores it. Example: {\"orderBy\":\"score\",\"sort\":\"desc\",\"pageSize\":25,\"filters\":null}.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["rfps.date_due","rfps.date_posted","rfps.status","rfps.customers.pretty_name","rfps.buyer.id","rfps.buyer.name_pretty","rfps.buyer.root_type","rfps.rfp_inferences.title","rfps.rfp_inferences.description","rfps.rfp_inferences.places.pretty_name","rfps.rfp_inferences.places.latitude","rfps.rfp_inferences.places.longitude","rfps.rfp_inferences.places.country","rfps.rfp_inferences.places.region","rfps.rfp_inferences.contact_full_name","rfps.rfp_inferences.contact_email_address","rfps.rfp_inferences.contact_phone_number","rfps.rfp_inferences.contact_mailing_address","rfps.rfp_inferences.rfp_set_asides.type","rfps.rfp_inferences.cage_codes","rfps.rfp_inferences.national_stock_numbers","rfps.rfp_inferences.type","rfps.rfp_inferences.level","rfps.rfp_inferences.submission_information_type","rfps.rfp_inferences.top_clearance","rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents","rfps.rfp_inferences.naics_codes.code","rfps.rfp_inferences.psc_codes.code","rfps.rfp_inferences.is_off_the_shelf","rfps.rfp_inferences.in_person","rfps.rfp_inferences.is_supply","rfps.rfp_inferences.is_service","rfps.rfp_inferences.has_local_preference","rfps.rfp_inferences.local_preference_level","rfps.rfp_inferences.local_preference_distance","rfps.rfp_inferences.max_education_required","rfps.rfp_inferences.has_max_education_required","rfps.rfp_inferences.has_insurance_requirements","rfps.rfp_inferences.has_past_performance_requirements","rfps.rfp_inferences.past_performance_strictness","rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents","rfps.is_private","score","distance","rfps.created_at","rfps.notification_eligible_at","rfps.id","box_area","has_documents","is_contactable","is_submittable"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Combined with `search.pageSize` it selects the slice of ranked results to return; at most 1,000 results are reachable in total, so a page that starts past result 1,000 comes back empty. Example: 1.","type":"number","minimum":1},"classifications":{"description":"Filters on your organization's own per-opportunity classifications (currently just hidden/not hidden). Pass `null` to apply no classification filtering at all. Example: null.","anyOf":[{"type":"object","properties":{"isHidden":{"description":"When true, return ONLY opportunities your organization has hidden; when false, return only opportunities it has not hidden; when null, ignore hidden state entirely. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["isHidden"],"additionalProperties":false},{"type":"null"}]},"skipCountTotal":{"description":"When true, skip counting the full result set so the query can stop as soon as the page is filled — much faster on large profiles, at the cost of `total` coming back as `-1` (unknown). Defaults to false. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page","classifications"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Total number of opportunities matching the search, or `-1` when the total is unknown. It is only counted when `search.filters` contains an open-status filter and `skipCountTotal` is not set; every other combination returns `-1`. `-1` is not an error — page until `items` comes back empty. Example: 137.","type":"number"},"items":{"description":"The requested page of opportunities, ordered by `search.orderBy` and `search.sort` with NULLs last. Each item is one opportunity, flattened into columns keyed by where the value comes from: `rfps.*` is the core record, `rfps.rfp_inferences.*` is its latest AI inference, `rfps.buyer.*` is the consolidated buyer, and `score`/`distance` are computed per request. Empty when the page is past the end of the results or past the 1,000-result ceiling.","type":"array","items":{"type":"object","properties":{"rfps.id":{"description":"The opportunity's Bidscope id; pass it to `opportunities.get`, `opportunities.get-awards`, and `opportunities.get-followers`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"rfps.date_due":{"type":["string","null"],"format":"date-time","description":"The submission deadline. Null when the source published no deadline — those opportunities stay open until they are pruned as expired rather than as past due. Example: \"2026-08-14T17:00:00.000Z\"."},"rfps.date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer published the solicitation, null when the source published no posting date. Example: \"2026-07-10T13:00:00.000Z\"."},"rfps.status":{"description":"The stored status column. Note this is the last-written value: an opportunity whose `date_due` has already passed can still read \"open\" until the nightly prune closes it, so filter on the `rfps.status` column (which also tests the due date) rather than reading this field to decide whether you can still bid. Examples: \"open\", \"closed\".","type":"string"},"rfps.status_reason":{"description":"A short free-text reason for a closed status, null while the opportunity is open. Examples: \"past due\", \"expired\", \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.private_metadata":{"description":"Source-specific metadata carried on private opportunities (the shape depends on the source), null for public ones. Example: { \"type\": \"ebuy\" }.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"rfps.is_private":{"description":"True when the opportunity is private to your organization (it came from a source only you have access to). Private opportunities belonging to other organizations are never returned. Example: false.","type":"boolean"},"rfps.customers.pretty_name":{"description":"The legacy per-source customer/portal account the opportunity was collected under. Superseded by `rfps.buyer.name_pretty`, which is the consolidated buyer. Example: \"SAM.gov\".","type":"string"},"rfps.buyer.id":{"description":"The consolidated buyer-tier id for the first raw buyer linked to the opportunity's latest inference (ordered by when the link was created). Null while that raw buyer is still awaiting consolidation. Filtering `rfps.buyer.id` with `string.eq` matches this tier and every tier beneath it, so you can select a whole parent agency. Example: \"6d9c2b41-08fe-4a7d-9c33-2b8e5f1a0d47\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.name_pretty":{"description":"The buyer's full hierarchy display name (each tier joined with \" > \"), falling back to the raw root buyer name when the buyer has not been consolidated yet. Null when the opportunity has no buyer at all. Example: \"Department of Defense > Defense Logistics Agency > DLA Land and Maritime\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.root_type":{"description":"The government level/type of the buyer's root organization, null when the buyer is unconsolidated or has no root. Examples: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", \"private\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.title":{"description":"A cleaned-up title for the opportunity, written by Bidscope's AI inference from the solicitation and its documents (not the raw source title). Example: \"Facility HVAC Maintenance Services\".","type":"string"},"rfps.rfp_inferences.blurb":{"description":"A one- or two-sentence AI summary of the opportunity, null when none has been generated yet. Example: \"Annual preventive maintenance and emergency repair of HVAC systems across three depot buildings.\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.description":{"description":"The long-form AI description of the scope of work, null when none has been generated yet. Example: \"The contractor shall provide all labor, materials, tools, and equipment necessary to perform scheduled preventive maintenance ...\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.pretty_name":{"description":"Display name of the inferred place of performance, null when no location could be resolved. Example: \"Columbus, Ohio, United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.latitude":{"description":"Latitude of the inferred place of performance in decimal degrees (WGS 84), null when no location was resolved. Example: 39.9612.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.places.longitude":{"description":"Longitude of the inferred place of performance in decimal degrees (WGS 84), null when no location was resolved. Example: -82.9988.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.places.country":{"description":"Country of the inferred place of performance, as the full name returned by the geocoder. Null when no location was resolved. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.region":{"description":"First-level administrative region (US state) of the inferred place of performance, as the full name returned by the geocoder. Null when no location was resolved. Example: \"Ohio\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_full_name":{"description":"Legacy single inferred point of contact for the solicitation, null when none was found. Superseded by the structured contacts on `opportunities.get`. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_email_address":{"description":"Legacy inferred contact email address, null when none was found. Example: \"dana.whitfield@example.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_phone_number":{"description":"Legacy inferred contact phone number, formatted as the source published it. Null when none was found. Example: \"+1-555-0142\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_mailing_address":{"description":"Legacy inferred contact mailing address as a single line, null when none was found. Example: \"3990 E Broad St, Columbus, OH 43213\".","anyOf":[{"type":"string"},{"type":"null"}]},"score":{"description":"How well the opportunity matches `matchingProfileId`, from 0 (no match) to 1 (perfect match). When the search includes an open-status filter this is the precomputed match score; otherwise it is estimated on the fly from the distance between the opportunity's and the profile's embedding centroids, so the two can differ slightly for the same opportunity. Example: 0.82.","type":"number"},"distance":{"description":"Straight-line distance in METERS from your organization's configured location to the opportunity's place of performance. Null when your organization has no location set or the opportunity has no resolved place. Example: 41230.5 (about 25.6 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.local_preference_distance":{"description":"Meters your organization's location falls OUTSIDE the opportunity's local-preference area — the distance to the local-preference place minus that preference's radius, floored at 0. So 0 means you are inside the preference area. Null when your organization has no location set or the opportunity declares no local-preference place. Example: 12500.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.rfp_set_asides.type":{"description":"Every set-aside/preference program the opportunity is reserved for, as inferred. Empty array when it is unrestricted. Current values are \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\", \"Native-Owned Business\", and \"Other\"; older records may still carry legacy long-form labels such as \"HUBZone Small Business\". Example: [\"Small Business\"].","type":"array","items":{"type":"string"}},"rfps.rfp_inferences.cage_codes":{"description":"CAGE codes referenced by the solicitation (typically the approved-source list on a defense supply buy). Null when none were found. Example: [\"1ABC5\", \"7XY22\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.national_stock_numbers":{"description":"National Stock Numbers of the items being bought, null when the solicitation names none. Example: [\"5330-01-234-5678\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.type":{"description":"The kind of notice, inferred from the solicitation. Null when it could not be determined. Examples: \"Request for Proposal (RFP)\", \"Request for Quote/Qualifications (RFQ)\", \"Request for Information (RFI)\", \"Invitation for/to Bid (IFB/ITB)\", \"Sole Source\", \"Sale\", \"Award Notice\", \"Sources Sought (SS)\", \"Event\", \"Grant\", \"Other\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.level":{"description":"The level of government running the procurement, inferred from the solicitation (independent of the consolidated buyer's `root_type`). Null when undetermined. Examples: \"Federal\", \"State\", \"Local\", \"Private\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.submission_information_type":{"description":"How bids must be submitted, null when the solicitation does not say. Examples: \"online\", \"email\", \"mail\", \"other\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.top_clearance":{"description":"The highest personnel security clearance the work requires, null when none is required or none was found. Examples: \"Confidential\", \"Secret\", \"Top Secret\", \"TS/SCI\", \"TS/SAP\", \"Public Trust\", \"DOE Q\", \"DOE L\", \"NATO Secret / TS\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":{"description":"The maximum budget or award amount the solicitation states explicitly, in integer USD cents, serialized as a STRING because it is a 64-bit value. Null when the solicitation names no amount (which is the common case). Example: \"150000000\" (i.e. $1,500,000.00).","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.is_off_the_shelf":{"description":"True when what is being bought is a commercially available off-the-shelf product rather than custom work. Null when it could not be determined — the field is genuinely tri-state, so treat null as unknown rather than false. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.in_person":{"description":"True when the work must be performed on site rather than remotely. Null when undetermined (tri-state). Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.is_supply":{"description":"True when the opportunity buys goods/supplies. Null when undetermined (tri-state). An opportunity can be both a supply and a service buy. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.is_service":{"description":"True when the opportunity buys services. Null when undetermined (tri-state). An opportunity can be both a supply and a service buy. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.has_local_preference":{"description":"Derived: true when the opportunity declares any local-preference program, i.e. `local_preference_level` is non-null. Never null. Example: false.","type":"boolean"},"rfps.rfp_inferences.local_preference_level":{"description":"How strong the local preference is, null when the opportunity declares none. Examples: \"required\", \"preferred\", \"encouraged-to-apply\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.max_education_required":{"description":"The highest formal education level the solicitation requires of any proposed personnel, null when it states no education requirement. Examples: \"High school diploma or equivalent (e.g., GED)\", \"Associate degree\", \"Bachelor's degree\", \"Master's degree\", \"Professional degree (e.g., MD, JD)\", \"Doctorate (PhD, EdD, etc.)\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.has_max_education_required":{"description":"Derived: true when `max_education_required` is non-null, i.e. the solicitation states an education requirement at all. Never null. Example: false.","type":"boolean"},"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":{"description":"The largest minimum coverage limit across all insurance policies the solicitation requires, in integer USD cents. Null when it requires no insurance or names no limits. Example: 100000000 (i.e. $1,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.has_insurance_requirements":{"description":"Derived: true when the solicitation states insurance requirements at all (independent of whether a coverage limit was extracted). Never null. Example: true.","type":"boolean"},"rfps.rfp_inferences.has_past_performance_requirements":{"description":"Derived: true when the solicitation asks for past performance at all, i.e. `past_performance_strictness` is non-null. Never null. Example: true.","type":"boolean"},"rfps.rfp_inferences.past_performance_strictness":{"description":"How past performance is used in the evaluation, null when the solicitation does not ask for it. Examples: \"required\" (a pass/fail gate), \"scored\" (part of the evaluation score), \"informational\" (requested but not evaluated).","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.naics_codes.code":{"description":"The single primary NAICS industry code inferred for the opportunity, null when none could be assigned. Only the primary code is returned here — use `opportunities.get` for the full list. Example: \"238220\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.psc_codes.code":{"description":"The single primary Product and Service Code (PSC/FSC) inferred for the opportunity, null when none could be assigned. Only the primary code is returned here — use `opportunities.get` for the full list. Example: \"J041\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["rfps.id","rfps.date_due","rfps.date_posted","rfps.status","rfps.status_reason","rfps.private_metadata","rfps.is_private","rfps.customers.pretty_name","rfps.buyer.id","rfps.buyer.name_pretty","rfps.buyer.root_type","rfps.rfp_inferences.title","rfps.rfp_inferences.blurb","rfps.rfp_inferences.description","rfps.rfp_inferences.places.pretty_name","rfps.rfp_inferences.places.latitude","rfps.rfp_inferences.places.longitude","rfps.rfp_inferences.places.country","rfps.rfp_inferences.places.region","rfps.rfp_inferences.contact_full_name","rfps.rfp_inferences.contact_email_address","rfps.rfp_inferences.contact_phone_number","rfps.rfp_inferences.contact_mailing_address","score","distance","rfps.rfp_inferences.local_preference_distance","rfps.rfp_inferences.rfp_set_asides.type","rfps.rfp_inferences.cage_codes","rfps.rfp_inferences.national_stock_numbers","rfps.rfp_inferences.type","rfps.rfp_inferences.level","rfps.rfp_inferences.submission_information_type","rfps.rfp_inferences.top_clearance","rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents","rfps.rfp_inferences.is_off_the_shelf","rfps.rfp_inferences.in_person","rfps.rfp_inferences.is_supply","rfps.rfp_inferences.is_service","rfps.rfp_inferences.has_local_preference","rfps.rfp_inferences.local_preference_level","rfps.rfp_inferences.max_education_required","rfps.rfp_inferences.has_max_education_required","rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents","rfps.rfp_inferences.has_insurance_requirements","rfps.rfp_inferences.has_past_performance_requirements","rfps.rfp_inferences.past_performance_strictness","rfps.rfp_inferences.naics_codes.code","rfps.rfp_inferences.psc_codes.code"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best matches for a profile, unfiltered","description":"The simplest possible search: rank everything by match score. With no open-status filter, `total` comes back as `-1` — page until `items` is empty.","request":{"matchingProfileId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1,"classifications":null},"response":{"total":-1,"items":[{"rfps.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","rfps.date_due":"2026-08-14T17:00:00.000Z","rfps.date_posted":"2026-07-10T13:00:00.000Z","rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":false,"rfps.customers.pretty_name":"SAM.gov","rfps.buyer.id":"6d9c2b41-08fe-4a7d-9c33-2b8e5f1a0d47","rfps.buyer.name_pretty":"Department of Defense > Defense Logistics Agency > DLA Land and Maritime","rfps.buyer.root_type":"federal","rfps.rfp_inferences.title":"Facility HVAC Maintenance Services","rfps.rfp_inferences.blurb":"Annual preventive maintenance and emergency repair of HVAC systems across three depot buildings.","rfps.rfp_inferences.description":"The contractor shall provide all labor, materials, tools, and equipment necessary to perform scheduled preventive maintenance and unscheduled repair of heating, ventilation, and air-conditioning systems at the installation.","rfps.rfp_inferences.places.pretty_name":"Columbus, Ohio, United States","rfps.rfp_inferences.places.latitude":39.9612,"rfps.rfp_inferences.places.longitude":-82.9988,"rfps.rfp_inferences.places.country":"United States","rfps.rfp_inferences.places.region":"Ohio","rfps.rfp_inferences.contact_full_name":"Dana Whitfield","rfps.rfp_inferences.contact_email_address":"dana.whitfield@example.gov","rfps.rfp_inferences.contact_phone_number":"+1-555-0142","rfps.rfp_inferences.contact_mailing_address":"3990 E Broad St, Columbus, OH 43213","score":0.82,"distance":41230.5,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":["Small Business"],"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":"Request for Proposal (RFP)","rfps.rfp_inferences.level":"Federal","rfps.rfp_inferences.submission_information_type":"online","rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":"150000000","rfps.rfp_inferences.is_off_the_shelf":false,"rfps.rfp_inferences.in_person":true,"rfps.rfp_inferences.is_supply":false,"rfps.rfp_inferences.is_service":true,"rfps.rfp_inferences.has_local_preference":false,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":false,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":100000000,"rfps.rfp_inferences.has_insurance_requirements":true,"rfps.rfp_inferences.has_past_performance_requirements":true,"rfps.rfp_inferences.past_performance_strictness":"scored","rfps.rfp_inferences.naics_codes.code":"238220","rfps.rfp_inferences.psc_codes.code":"J041"},{"rfps.id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","rfps.date_due":"2026-09-02T22:00:00.000Z","rfps.date_posted":"2026-07-15T16:30:00.000Z","rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":false,"rfps.customers.pretty_name":"City of Fairhaven Procurement","rfps.buyer.id":"b0f14e73-2c69-49aa-a4c1-8f7d6b2e5309","rfps.buyer.name_pretty":"City of Fairhaven > Department of Public Works","rfps.buyer.root_type":"city","rfps.rfp_inferences.title":"Custodial Services for Municipal Buildings","rfps.rfp_inferences.blurb":"Nightly janitorial services for eight city-owned facilities under a three-year base contract.","rfps.rfp_inferences.description":null,"rfps.rfp_inferences.places.pretty_name":"Fairhaven, Ohio, United States","rfps.rfp_inferences.places.latitude":39.7589,"rfps.rfp_inferences.places.longitude":-84.1916,"rfps.rfp_inferences.places.country":"United States","rfps.rfp_inferences.places.region":"Ohio","rfps.rfp_inferences.contact_full_name":null,"rfps.rfp_inferences.contact_email_address":"purchasing@example-city.gov","rfps.rfp_inferences.contact_phone_number":null,"rfps.rfp_inferences.contact_mailing_address":null,"score":0.71,"distance":96540.2,"rfps.rfp_inferences.local_preference_distance":0,"rfps.rfp_inferences.rfp_set_asides.type":[],"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":"Invitation for/to Bid (IFB/ITB)","rfps.rfp_inferences.level":"Local","rfps.rfp_inferences.submission_information_type":"email","rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":null,"rfps.rfp_inferences.is_off_the_shelf":null,"rfps.rfp_inferences.in_person":true,"rfps.rfp_inferences.is_supply":false,"rfps.rfp_inferences.is_service":true,"rfps.rfp_inferences.has_local_preference":true,"rfps.rfp_inferences.local_preference_level":"preferred","rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":false,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":null,"rfps.rfp_inferences.has_insurance_requirements":true,"rfps.rfp_inferences.has_past_performance_requirements":false,"rfps.rfp_inferences.past_performance_strictness":null,"rfps.rfp_inferences.naics_codes.code":"561720","rfps.rfp_inferences.psc_codes.code":"S201"}]}},{"title":"Open city/county work, due this quarter, set-aside eligible","description":"The filter shape the Bidscope app's simple search produces: one top-level AND group whose children are bare leaves (status, the two due-date bounds, the match-score floor) plus one OR group per multi-select facet (buyer type, set-asides). Because the open-status leaf is present and `skipCountTotal` is unset, `total` is a real count.","request":{"matchingProfileId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","search":{"orderBy":"score","sort":"desc","pageSize":25,"quickSearch":"grounds maintenance","filters":{"type":"group","isAnd":true,"filters":[{"type":"filter","column":"rfps.status","filter":{"operator":"enum.eq","value":"open"}},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"rfps.buyer.root_type","filter":{"operator":"enum.eq","value":"city"}},{"type":"filter","column":"rfps.buyer.root_type","filter":{"operator":"enum.eq","value":"county"}}]},{"type":"filter","column":"rfps.date_due","filter":{"operator":"date.after","value":"2026-07-18T00:00:00.000Z"}},{"type":"filter","column":"rfps.date_due","filter":{"operator":"date.before","value":"2026-10-01T00:00:00.000Z"}},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"rfps.rfp_inferences.rfp_set_asides.type","filter":{"operator":"enum.eq","value":"Small Business"}},{"type":"filter","column":"rfps.rfp_inferences.rfp_set_asides.type","filter":{"operator":"enum.eq","value":"Woman-Owned Business"}}]},{"type":"filter","column":"score","filter":{"operator":"number.gt","value":0.55}}]}},"page":1,"classifications":{"isHidden":false}},"response":{"total":1,"items":[{"rfps.id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","rfps.date_due":"2026-09-18T21:00:00.000Z","rfps.date_posted":"2026-07-16T14:05:00.000Z","rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":false,"rfps.customers.pretty_name":"Marbury County Purchasing","rfps.buyer.id":"4e77c1a8-9d02-4b56-bb3f-15c8a9e6d7f0","rfps.buyer.name_pretty":"Marbury County > Parks and Recreation Department","rfps.buyer.root_type":"county","rfps.rfp_inferences.title":"Grounds Maintenance and Landscaping Services for County Parks","rfps.rfp_inferences.blurb":"Mowing, trimming, irrigation upkeep, and seasonal planting across fourteen county park sites.","rfps.rfp_inferences.description":"The County seeks a qualified contractor to provide comprehensive grounds maintenance, including turf care, tree and shrub pruning, irrigation system inspection, and litter removal, on a recurring schedule for the duration of the contract.","rfps.rfp_inferences.places.pretty_name":"Marbury County, Ohio, United States","rfps.rfp_inferences.places.latitude":40.0992,"rfps.rfp_inferences.places.longitude":-83.0925,"rfps.rfp_inferences.places.country":"United States","rfps.rfp_inferences.places.region":"Ohio","rfps.rfp_inferences.contact_full_name":"Priya Raman","rfps.rfp_inferences.contact_email_address":"priya.raman@example-county.gov","rfps.rfp_inferences.contact_phone_number":"(555) 010-8823","rfps.rfp_inferences.contact_mailing_address":"120 County Center Dr, Suite 300, Marbury, OH 43004","score":0.77,"distance":18320.9,"rfps.rfp_inferences.local_preference_distance":0,"rfps.rfp_inferences.rfp_set_asides.type":["Small Business","Woman-Owned Business"],"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":"Request for Proposal (RFP)","rfps.rfp_inferences.level":"Local","rfps.rfp_inferences.submission_information_type":"online","rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":"48000000","rfps.rfp_inferences.is_off_the_shelf":false,"rfps.rfp_inferences.in_person":true,"rfps.rfp_inferences.is_supply":false,"rfps.rfp_inferences.is_service":true,"rfps.rfp_inferences.has_local_preference":true,"rfps.rfp_inferences.local_preference_level":"preferred","rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":false,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":200000000,"rfps.rfp_inferences.has_insurance_requirements":true,"rfps.rfp_inferences.has_past_performance_requirements":true,"rfps.rfp_inferences.past_performance_strictness":"required","rfps.rfp_inferences.naics_codes.code":"561730","rfps.rfp_inferences.psc_codes.code":"S208"}]}}]},{"version":"2026-07-20","description":"Search opportunities (RFPs), scored against one of your organization's matching profiles. One item is one opportunity, flattened into display columns keyed like `\"rfps.rfp_inferences.title\"`.\n\nWHAT YOU GET DEPENDS ON YOUR PLAN.\n\nOn a paid plan this behaves exactly like `opportunities.search@2026-07-05`. Results are NOT restricted to open opportunities — to search only open ones, add a `rfps.status` / `enum.eq` / `\"open\"` leaf to `search.filters`; that filter also excludes anything whose due date has already passed, which reading the raw `rfps.status` field does not. Ordering is `search.orderBy` + `search.sort`, NULLs last. Paging is 1-based `page` × `search.pageSize` (exactly 1, 10, 25, 50, or 100), and a search exposes at most 1,000 results in total. `total` is `-1` (unknown) unless `search.filters` contains the open-status filter and `skipCountTotal` is unset.\n\nOn the FREE plan the request is accepted but mostly ignored: `search` (filters, ordering, page size, quick search), `page`, `classifications`, and `skipCountTotal` have no effect. You always get the same fixed teaser — the 15 best-matching OPEN opportunities for the profile, ranked by score, excluding award notices and sales. Several elements of `items` come back `null` (withheld rows), and the rest carry only `rfps.id`, `rfps.status`, `rfps.rfp_inferences.title`, `rfps.buyer.name_pretty`, `rfps.date_due`, and `score`, with every other key present but null. `total` is a truthful count of everything matching, so it will be far larger than the number of rows you can see. Do not present the free-plan result as a complete or filtered answer — say that filtering, sorting, and the full record require a paid Bidscope plan, and point the user at https://app.bidscopeai.com/billing.\n\nPrivate opportunities belonging to other organizations are never returned. Returns 404 when `matchingProfileId` does not exist, and 403 when it belongs to another organization.","plans":["free","starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"One of your organization's matching profiles. Every result's `score` measures how close the opportunity is to this profile, and `orderBy: \"score\"` ranks by it. Returns 404 when no profile with this id exists and 403 when it belongs to another organization. Example: \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query state, the same object the Bidscope app persists on a saved view. `orderBy` is one of the sortable column keys (see the enum) and `sort` is `\"asc\"` or `\"desc\"`; results are ordered by that column with NULLs last. `pageSize` must be exactly 1, 10, 25, 50, or 100. `quickSearch` is optional free text matched case-insensitively against the source title, solicitation identifier, legacy buyer name, inferred title, and buyer hierarchy name. `filters` is the recursive filter tree (`null` for no filtering) — leaves name a column and an operator, groups combine children with `isAnd`. `filterMeta` is an opaque bag the app uses to remember how the UI built the tree; the API ignores it. Example: {\"orderBy\":\"score\",\"sort\":\"desc\",\"pageSize\":25,\"filters\":null}.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["rfps.date_due","rfps.date_posted","rfps.status","rfps.customers.pretty_name","rfps.buyer.id","rfps.buyer.name_pretty","rfps.buyer.root_type","rfps.rfp_inferences.title","rfps.rfp_inferences.description","rfps.rfp_inferences.places.pretty_name","rfps.rfp_inferences.places.latitude","rfps.rfp_inferences.places.longitude","rfps.rfp_inferences.places.country","rfps.rfp_inferences.places.region","rfps.rfp_inferences.contact_full_name","rfps.rfp_inferences.contact_email_address","rfps.rfp_inferences.contact_phone_number","rfps.rfp_inferences.contact_mailing_address","rfps.rfp_inferences.rfp_set_asides.type","rfps.rfp_inferences.cage_codes","rfps.rfp_inferences.national_stock_numbers","rfps.rfp_inferences.type","rfps.rfp_inferences.level","rfps.rfp_inferences.submission_information_type","rfps.rfp_inferences.top_clearance","rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents","rfps.rfp_inferences.naics_codes.code","rfps.rfp_inferences.psc_codes.code","rfps.rfp_inferences.is_off_the_shelf","rfps.rfp_inferences.in_person","rfps.rfp_inferences.is_supply","rfps.rfp_inferences.is_service","rfps.rfp_inferences.has_local_preference","rfps.rfp_inferences.local_preference_level","rfps.rfp_inferences.local_preference_distance","rfps.rfp_inferences.max_education_required","rfps.rfp_inferences.has_max_education_required","rfps.rfp_inferences.has_insurance_requirements","rfps.rfp_inferences.has_past_performance_requirements","rfps.rfp_inferences.past_performance_strictness","rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents","rfps.is_private","score","distance","rfps.created_at","rfps.notification_eligible_at","rfps.id","box_area","has_documents","is_contactable","is_submittable"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Combined with `search.pageSize` it selects the slice of ranked results to return; at most 1,000 results are reachable in total, so a page that starts past result 1,000 comes back empty. Example: 1.","type":"number","minimum":1},"classifications":{"description":"Filters on your organization's own per-opportunity classifications (currently just hidden/not hidden). Pass `null` to apply no classification filtering at all. Example: null.","anyOf":[{"type":"object","properties":{"isHidden":{"description":"When true, return ONLY opportunities your organization has hidden; when false, return only opportunities it has not hidden; when null, ignore hidden state entirely. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["isHidden"],"additionalProperties":false},{"type":"null"}]},"skipCountTotal":{"description":"When true, skip counting the full result set so the query can stop as soon as the page is filled — much faster on large profiles, at the cost of `total` coming back as `-1` (unknown). Defaults to false. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page","classifications"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Total number of opportunities matching the search, or `-1` when the total is unknown. On a paid plan it is only counted when `search.filters` contains an open-status filter and `skipCountTotal` is not set; every other combination returns `-1`. On the free plan it is always a real count of the open opportunities matching your profile, which is typically far larger than the handful of rows returned. `-1` is not an error — page until `items` comes back empty. Example: 137.","type":"number"},"items":{"description":"The requested page of opportunities. Each item is one opportunity, flattened into columns keyed by where the value comes from: `rfps.*` is the core record, `rfps.rfp_inferences.*` is its latest AI inference, `rfps.buyer.*` is the consolidated buyer, and `score`/`distance` are computed per request.\n\nOn a paid plan every element is a full row and none are null. On the free plan the array is a fixed 15-row teaser: some elements are `null` (the row exists and is counted in `total`, but is withheld), and the rest carry only `rfps.id`, `rfps.status`, `rfps.rfp_inferences.title`, `rfps.buyer.name_pretty`, `rfps.date_due`, and `score` — every other key is present but null. Upgrade to see the withheld rows and fields.","type":"array","items":{"anyOf":[{"type":"object","properties":{"rfps.id":{"description":"The opportunity's Bidscope id; pass it to `opportunities.get`, `opportunities.get-awards`, and `opportunities.get-followers`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"rfps.date_due":{"type":["string","null"],"format":"date-time","description":"The submission deadline. Null when the source published no deadline — those opportunities stay open until they are pruned as expired rather than as past due. Example: \"2026-08-14T17:00:00.000Z\"."},"rfps.date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer published the solicitation, null when the source published no posting date. Example: \"2026-07-10T13:00:00.000Z\"."},"rfps.status":{"description":"The stored status column. Note this is the last-written value: an opportunity whose `date_due` has already passed can still read \"open\" until the nightly prune closes it, so filter on the `rfps.status` column (which also tests the due date) rather than reading this field to decide whether you can still bid. Examples: \"open\", \"closed\".","type":"string"},"rfps.status_reason":{"description":"A short free-text reason for a closed status, null while the opportunity is open. Examples: \"past due\", \"expired\", \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.private_metadata":{"description":"Source-specific metadata carried on private opportunities (the shape depends on the source), null for public ones. Example: { \"type\": \"ebuy\" }.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"rfps.is_private":{"description":"True when the opportunity is private to your organization (it came from a source only you have access to). Private opportunities belonging to other organizations are never returned. Example: false.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.customers.pretty_name":{"description":"The legacy per-source customer/portal account the opportunity was collected under. Superseded by `rfps.buyer.name_pretty`, which is the consolidated buyer. Example: \"SAM.gov\".\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.id":{"description":"The consolidated buyer-tier id for the first raw buyer linked to the opportunity's latest inference (ordered by when the link was created). Null while that raw buyer is still awaiting consolidation. Filtering `rfps.buyer.id` with `string.eq` matches this tier and every tier beneath it, so you can select a whole parent agency. Example: \"6d9c2b41-08fe-4a7d-9c33-2b8e5f1a0d47\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.name_pretty":{"description":"The buyer's full hierarchy display name (each tier joined with \" > \"), falling back to the raw root buyer name when the buyer has not been consolidated yet. Null when the opportunity has no buyer at all. Example: \"Department of Defense > Defense Logistics Agency > DLA Land and Maritime\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.root_type":{"description":"The government level/type of the buyer's root organization, null when the buyer is unconsolidated or has no root. Examples: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", \"private\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.title":{"description":"A cleaned-up title for the opportunity, written by Bidscope's AI inference from the solicitation and its documents (not the raw source title). Example: \"Facility HVAC Maintenance Services\".","type":"string"},"rfps.rfp_inferences.blurb":{"description":"A one- or two-sentence AI summary of the opportunity, null when none has been generated yet. Example: \"Annual preventive maintenance and emergency repair of HVAC systems across three depot buildings.\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.description":{"description":"The long-form AI description of the scope of work, null when none has been generated yet. Example: \"The contractor shall provide all labor, materials, tools, and equipment necessary to perform scheduled preventive maintenance ...\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.pretty_name":{"description":"Display name of the inferred place of performance, null when no location could be resolved. Example: \"Columbus, Ohio, United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.latitude":{"description":"Latitude of the inferred place of performance in decimal degrees (WGS 84), null when no location was resolved. Example: 39.9612.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.places.longitude":{"description":"Longitude of the inferred place of performance in decimal degrees (WGS 84), null when no location was resolved. Example: -82.9988.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.places.country":{"description":"Country of the inferred place of performance, as the full name returned by the geocoder. Null when no location was resolved. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.region":{"description":"First-level administrative region (US state) of the inferred place of performance, as the full name returned by the geocoder. Null when no location was resolved. Example: \"Ohio\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_full_name":{"description":"Legacy single inferred point of contact for the solicitation, null when none was found. Superseded by the structured contacts on `opportunities.get`. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_email_address":{"description":"Legacy inferred contact email address, null when none was found. Example: \"dana.whitfield@example.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_phone_number":{"description":"Legacy inferred contact phone number, formatted as the source published it. Null when none was found. Example: \"+1-555-0142\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_mailing_address":{"description":"Legacy inferred contact mailing address as a single line, null when none was found. Example: \"3990 E Broad St, Columbus, OH 43213\".","anyOf":[{"type":"string"},{"type":"null"}]},"score":{"description":"How well the opportunity matches `matchingProfileId`, from 0 (no match) to 1 (perfect match). When the search includes an open-status filter this is the precomputed match score; otherwise it is estimated on the fly from the distance between the opportunity's and the profile's embedding centroids, so the two can differ slightly for the same opportunity. Example: 0.82.","type":"number"},"distance":{"description":"Straight-line distance in METERS from your organization's configured location to the opportunity's place of performance. Null when your organization has no location set or the opportunity has no resolved place. Example: 41230.5 (about 25.6 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.local_preference_distance":{"description":"Meters your organization's location falls OUTSIDE the opportunity's local-preference area — the distance to the local-preference place minus that preference's radius, floored at 0. So 0 means you are inside the preference area. Null when your organization has no location set or the opportunity declares no local-preference place. Example: 12500.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.rfp_set_asides.type":{"description":"Every set-aside/preference program the opportunity is reserved for, as inferred. Empty array when it is unrestricted. Current values are \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\", \"Native-Owned Business\", and \"Other\"; older records may still carry legacy long-form labels such as \"HUBZone Small Business\". Example: [\"Small Business\"].\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.cage_codes":{"description":"CAGE codes referenced by the solicitation (typically the approved-source list on a defense supply buy). Null when none were found. Example: [\"1ABC5\", \"7XY22\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.national_stock_numbers":{"description":"National Stock Numbers of the items being bought, null when the solicitation names none. Example: [\"5330-01-234-5678\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.type":{"description":"The kind of notice, inferred from the solicitation. Null when it could not be determined. Examples: \"Request for Proposal (RFP)\", \"Request for Quote/Qualifications (RFQ)\", \"Request for Information (RFI)\", \"Invitation for/to Bid (IFB/ITB)\", \"Sole Source\", \"Sale\", \"Award Notice\", \"Sources Sought (SS)\", \"Event\", \"Grant\", \"Other\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.level":{"description":"The level of government running the procurement, inferred from the solicitation (independent of the consolidated buyer's `root_type`). Null when undetermined. Examples: \"Federal\", \"State\", \"Local\", \"Private\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.submission_information_type":{"description":"How bids must be submitted, null when the solicitation does not say. Examples: \"online\", \"email\", \"mail\", \"other\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.top_clearance":{"description":"The highest personnel security clearance the work requires, null when none is required or none was found. Examples: \"Confidential\", \"Secret\", \"Top Secret\", \"TS/SCI\", \"TS/SAP\", \"Public Trust\", \"DOE Q\", \"DOE L\", \"NATO Secret / TS\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":{"description":"The maximum budget or award amount the solicitation states explicitly, in integer USD cents, serialized as a STRING because it is a 64-bit value. Null when the solicitation names no amount (which is the common case). Example: \"150000000\" (i.e. $1,500,000.00).","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.is_off_the_shelf":{"description":"True when what is being bought is a commercially available off-the-shelf product rather than custom work. Null when it could not be determined — the field is genuinely tri-state, so treat null as unknown rather than false. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.in_person":{"description":"True when the work must be performed on site rather than remotely. Null when undetermined (tri-state). Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.is_supply":{"description":"True when the opportunity buys goods/supplies. Null when undetermined (tri-state). An opportunity can be both a supply and a service buy. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.is_service":{"description":"True when the opportunity buys services. Null when undetermined (tri-state). An opportunity can be both a supply and a service buy. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.has_local_preference":{"description":"Derived: true when the opportunity declares any local-preference program, i.e. `local_preference_level` is non-null. Example: false.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.local_preference_level":{"description":"How strong the local preference is, null when the opportunity declares none. Examples: \"required\", \"preferred\", \"encouraged-to-apply\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.max_education_required":{"description":"The highest formal education level the solicitation requires of any proposed personnel, null when it states no education requirement. Examples: \"High school diploma or equivalent (e.g., GED)\", \"Associate degree\", \"Bachelor's degree\", \"Master's degree\", \"Professional degree (e.g., MD, JD)\", \"Doctorate (PhD, EdD, etc.)\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.has_max_education_required":{"description":"Derived: true when `max_education_required` is non-null, i.e. the solicitation states an education requirement at all. Example: false.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":{"description":"The largest minimum coverage limit across all insurance policies the solicitation requires, in integer USD cents. Null when it requires no insurance or names no limits. Example: 100000000 (i.e. $1,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.has_insurance_requirements":{"description":"Derived: true when the solicitation states insurance requirements at all (independent of whether a coverage limit was extracted). Example: true.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.has_past_performance_requirements":{"description":"Derived: true when the solicitation asks for past performance at all, i.e. `past_performance_strictness` is non-null. Example: true.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.past_performance_strictness":{"description":"How past performance is used in the evaluation, null when the solicitation does not ask for it. Examples: \"required\" (a pass/fail gate), \"scored\" (part of the evaluation score), \"informational\" (requested but not evaluated).","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.naics_codes.code":{"description":"The single primary NAICS industry code inferred for the opportunity, null when none could be assigned. Only the primary code is returned here — use `opportunities.get` for the full list. Example: \"238220\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.psc_codes.code":{"description":"The single primary Product and Service Code (PSC/FSC) inferred for the opportunity, null when none could be assigned. Only the primary code is returned here — use `opportunities.get` for the full list. Example: \"J041\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["rfps.id","rfps.date_due","rfps.date_posted","rfps.status","rfps.status_reason","rfps.private_metadata","rfps.is_private","rfps.customers.pretty_name","rfps.buyer.id","rfps.buyer.name_pretty","rfps.buyer.root_type","rfps.rfp_inferences.title","rfps.rfp_inferences.blurb","rfps.rfp_inferences.description","rfps.rfp_inferences.places.pretty_name","rfps.rfp_inferences.places.latitude","rfps.rfp_inferences.places.longitude","rfps.rfp_inferences.places.country","rfps.rfp_inferences.places.region","rfps.rfp_inferences.contact_full_name","rfps.rfp_inferences.contact_email_address","rfps.rfp_inferences.contact_phone_number","rfps.rfp_inferences.contact_mailing_address","score","distance","rfps.rfp_inferences.local_preference_distance","rfps.rfp_inferences.rfp_set_asides.type","rfps.rfp_inferences.cage_codes","rfps.rfp_inferences.national_stock_numbers","rfps.rfp_inferences.type","rfps.rfp_inferences.level","rfps.rfp_inferences.submission_information_type","rfps.rfp_inferences.top_clearance","rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents","rfps.rfp_inferences.is_off_the_shelf","rfps.rfp_inferences.in_person","rfps.rfp_inferences.is_supply","rfps.rfp_inferences.is_service","rfps.rfp_inferences.has_local_preference","rfps.rfp_inferences.local_preference_level","rfps.rfp_inferences.max_education_required","rfps.rfp_inferences.has_max_education_required","rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents","rfps.rfp_inferences.has_insurance_requirements","rfps.rfp_inferences.has_past_performance_requirements","rfps.rfp_inferences.past_performance_strictness","rfps.rfp_inferences.naics_codes.code","rfps.rfp_inferences.psc_codes.code"],"additionalProperties":false},{"type":"null"}]}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best matches for a profile (paid plan)","description":"Rank everything by match score. With no open-status filter, `total` comes back as `-1` — page until `items` is empty. Every row is complete.","request":{"matchingProfileId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1,"classifications":null},"response":{"total":-1,"items":[{"rfps.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","rfps.date_due":"2026-08-14T17:00:00.000Z","rfps.date_posted":"2026-07-10T13:00:00.000Z","rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":false,"rfps.customers.pretty_name":"SAM.gov","rfps.buyer.id":"6d9c2b41-08fe-4a7d-9c33-2b8e5f1a0d47","rfps.buyer.name_pretty":"Department of Defense > Defense Logistics Agency > DLA Land and Maritime","rfps.buyer.root_type":"federal","rfps.rfp_inferences.title":"Facility HVAC Maintenance Services","rfps.rfp_inferences.blurb":"Annual preventive maintenance and emergency repair of HVAC systems across three depot buildings.","rfps.rfp_inferences.description":"The contractor shall provide all labor, materials, tools, and equipment necessary to perform scheduled preventive maintenance and unscheduled repair of heating, ventilation, and air-conditioning systems at the installation.","rfps.rfp_inferences.places.pretty_name":"Columbus, Ohio, United States","rfps.rfp_inferences.places.latitude":39.9612,"rfps.rfp_inferences.places.longitude":-82.9988,"rfps.rfp_inferences.places.country":"United States","rfps.rfp_inferences.places.region":"Ohio","rfps.rfp_inferences.contact_full_name":"Dana Whitfield","rfps.rfp_inferences.contact_email_address":"dana.whitfield@example.gov","rfps.rfp_inferences.contact_phone_number":"+1-555-0142","rfps.rfp_inferences.contact_mailing_address":"3990 E Broad St, Columbus, OH 43213","score":0.82,"distance":41230.5,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":["Small Business"],"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":"Request for Proposal (RFP)","rfps.rfp_inferences.level":"Federal","rfps.rfp_inferences.submission_information_type":"online","rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":"150000000","rfps.rfp_inferences.is_off_the_shelf":false,"rfps.rfp_inferences.in_person":true,"rfps.rfp_inferences.is_supply":false,"rfps.rfp_inferences.is_service":true,"rfps.rfp_inferences.has_local_preference":false,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":false,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":100000000,"rfps.rfp_inferences.has_insurance_requirements":true,"rfps.rfp_inferences.has_past_performance_requirements":true,"rfps.rfp_inferences.past_performance_strictness":"scored","rfps.rfp_inferences.naics_codes.code":"238220","rfps.rfp_inferences.psc_codes.code":"J041"}]}},{"title":"The same request on the free plan","description":"Identical arguments, including filters and a page size of 100 — all ignored. The response is the fixed teaser: withheld rows are null, visible rows carry six fields, and `total` still counts every match. Truncated here to the first five of the fifteen elements.","request":{"matchingProfileId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","search":{"orderBy":"rfps.date_due","sort":"asc","pageSize":100,"filters":{"type":"filter","column":"rfps.buyer.root_type","filter":{"operator":"enum.eq","value":"city"}}},"page":3,"classifications":null},"response":{"total":8341,"items":[null,{"rfps.id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","rfps.date_due":"2026-09-02T22:00:00.000Z","rfps.date_posted":null,"rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":null,"rfps.customers.pretty_name":null,"rfps.buyer.id":null,"rfps.buyer.name_pretty":"City of Fairhaven > Department of Public Works","rfps.buyer.root_type":null,"rfps.rfp_inferences.title":"Custodial Services for Municipal Buildings","rfps.rfp_inferences.blurb":null,"rfps.rfp_inferences.description":null,"rfps.rfp_inferences.places.pretty_name":null,"rfps.rfp_inferences.places.latitude":null,"rfps.rfp_inferences.places.longitude":null,"rfps.rfp_inferences.places.country":null,"rfps.rfp_inferences.places.region":null,"rfps.rfp_inferences.contact_full_name":null,"rfps.rfp_inferences.contact_email_address":null,"rfps.rfp_inferences.contact_phone_number":null,"rfps.rfp_inferences.contact_mailing_address":null,"score":0.71,"distance":null,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":null,"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":null,"rfps.rfp_inferences.level":null,"rfps.rfp_inferences.submission_information_type":null,"rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":null,"rfps.rfp_inferences.is_off_the_shelf":null,"rfps.rfp_inferences.in_person":null,"rfps.rfp_inferences.is_supply":null,"rfps.rfp_inferences.is_service":null,"rfps.rfp_inferences.has_local_preference":null,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":null,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":null,"rfps.rfp_inferences.has_insurance_requirements":null,"rfps.rfp_inferences.has_past_performance_requirements":null,"rfps.rfp_inferences.past_performance_strictness":null,"rfps.rfp_inferences.naics_codes.code":null,"rfps.rfp_inferences.psc_codes.code":null},null,null,{"rfps.id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","rfps.date_due":"2026-09-18T21:00:00.000Z","rfps.date_posted":null,"rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":null,"rfps.customers.pretty_name":null,"rfps.buyer.id":null,"rfps.buyer.name_pretty":"Marbury County > Parks and Recreation Department","rfps.buyer.root_type":null,"rfps.rfp_inferences.title":"Grounds Maintenance and Landscaping Services for County Parks","rfps.rfp_inferences.blurb":null,"rfps.rfp_inferences.description":null,"rfps.rfp_inferences.places.pretty_name":null,"rfps.rfp_inferences.places.latitude":null,"rfps.rfp_inferences.places.longitude":null,"rfps.rfp_inferences.places.country":null,"rfps.rfp_inferences.places.region":null,"rfps.rfp_inferences.contact_full_name":null,"rfps.rfp_inferences.contact_email_address":null,"rfps.rfp_inferences.contact_phone_number":null,"rfps.rfp_inferences.contact_mailing_address":null,"score":0.77,"distance":null,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":null,"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":null,"rfps.rfp_inferences.level":null,"rfps.rfp_inferences.submission_information_type":null,"rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":null,"rfps.rfp_inferences.is_off_the_shelf":null,"rfps.rfp_inferences.in_person":null,"rfps.rfp_inferences.is_supply":null,"rfps.rfp_inferences.is_service":null,"rfps.rfp_inferences.has_local_preference":null,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":null,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":null,"rfps.rfp_inferences.has_insurance_requirements":null,"rfps.rfp_inferences.has_past_performance_requirements":null,"rfps.rfp_inferences.past_performance_strictness":null,"rfps.rfp_inferences.naics_codes.code":null,"rfps.rfp_inferences.psc_codes.code":null}]}}]},{"version":"2026-08-19","description":"Search opportunities (RFPs), scored against one of your organization's matching profiles. One item is one opportunity, flattened into display columns keyed like `\"rfps.rfp_inferences.title\"`.\n\nWHAT YOU GET DEPENDS ON YOUR PLAN.\n\nOn a paid plan this behaves like `opportunities.search@2026-07-20`, plus one extra column: `rfps.rfp_inferences.can_middleman`, which is the only difference between the two versions. Results are NOT restricted to open opportunities — to search only open ones, add a `rfps.status` / `enum.eq` / `\"open\"` leaf to `search.filters`; that filter also excludes anything whose due date has already passed, which reading the raw `rfps.status` field does not. Ordering is `search.orderBy` + `search.sort`, NULLs last. Paging is 1-based `page` × `search.pageSize` (exactly 1, 10, 25, 50, or 100), and a search exposes at most 1,000 results in total. `total` is `-1` (unknown) unless `search.filters` contains the open-status filter and `skipCountTotal` is unset.\n\nOn the FREE plan the request is accepted but mostly ignored: `search` (filters, ordering, page size, quick search), `page`, `classifications`, and `skipCountTotal` have no effect. You always get the same fixed teaser — the 15 best-matching OPEN opportunities for the profile, ranked by score, excluding award notices and sales. Several elements of `items` come back `null` (withheld rows), and the rest carry only `rfps.id`, `rfps.status`, `rfps.rfp_inferences.title`, `rfps.buyer.name_pretty`, `rfps.date_due`, and `score`, with every other key present but null. `total` is a truthful count of everything matching, so it will be far larger than the number of rows you can see. Do not present the free-plan result as a complete or filtered answer — say that filtering, sorting, and the full record require a paid Bidscope plan, and point the user at https://app.bidscopeai.com/billing.\n\nPrivate opportunities belonging to other organizations are never returned. Returns 404 when `matchingProfileId` does not exist, and 403 when it belongs to another organization.","plans":["free","starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"One of your organization's matching profiles. Every result's `score` measures how close the opportunity is to this profile, and `orderBy: \"score\"` ranks by it. Returns 404 when no profile with this id exists and 403 when it belongs to another organization. Example: \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query state, the same object the Bidscope app persists on a saved view. `orderBy` is one of the sortable column keys (see the enum) and `sort` is `\"asc\"` or `\"desc\"`; results are ordered by that column with NULLs last. `pageSize` must be exactly 1, 10, 25, 50, or 100. `quickSearch` is optional free text matched case-insensitively against the source title, solicitation identifier, legacy buyer name, inferred title, and buyer hierarchy name. `filters` is the recursive filter tree (`null` for no filtering) — leaves name a column and an operator, groups combine children with `isAnd`. `filterMeta` is an opaque bag the app uses to remember how the UI built the tree; the API ignores it. Example: {\"orderBy\":\"score\",\"sort\":\"desc\",\"pageSize\":25,\"filters\":null}.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["rfps.date_due","rfps.date_posted","rfps.status","rfps.customers.pretty_name","rfps.buyer.id","rfps.buyer.name_pretty","rfps.buyer.root_type","rfps.rfp_inferences.title","rfps.rfp_inferences.description","rfps.rfp_inferences.places.pretty_name","rfps.rfp_inferences.places.latitude","rfps.rfp_inferences.places.longitude","rfps.rfp_inferences.places.country","rfps.rfp_inferences.places.region","rfps.rfp_inferences.contact_full_name","rfps.rfp_inferences.contact_email_address","rfps.rfp_inferences.contact_phone_number","rfps.rfp_inferences.contact_mailing_address","rfps.rfp_inferences.rfp_set_asides.type","rfps.rfp_inferences.cage_codes","rfps.rfp_inferences.national_stock_numbers","rfps.rfp_inferences.type","rfps.rfp_inferences.level","rfps.rfp_inferences.submission_information_type","rfps.rfp_inferences.top_clearance","rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents","rfps.rfp_inferences.naics_codes.code","rfps.rfp_inferences.psc_codes.code","rfps.rfp_inferences.is_off_the_shelf","rfps.rfp_inferences.in_person","rfps.rfp_inferences.is_supply","rfps.rfp_inferences.is_service","rfps.rfp_inferences.has_local_preference","rfps.rfp_inferences.local_preference_level","rfps.rfp_inferences.local_preference_distance","rfps.rfp_inferences.max_education_required","rfps.rfp_inferences.has_max_education_required","rfps.rfp_inferences.has_insurance_requirements","rfps.rfp_inferences.has_past_performance_requirements","rfps.rfp_inferences.past_performance_strictness","rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents","rfps.is_private","score","distance","rfps.created_at","rfps.notification_eligible_at","rfps.id","box_area","has_documents","is_contactable","is_submittable"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Combined with `search.pageSize` it selects the slice of ranked results to return; at most 1,000 results are reachable in total, so a page that starts past result 1,000 comes back empty. Example: 1.","type":"number","minimum":1},"classifications":{"description":"Filters on your organization's own per-opportunity classifications (currently just hidden/not hidden). Pass `null` to apply no classification filtering at all. Example: null.","anyOf":[{"type":"object","properties":{"isHidden":{"description":"When true, return ONLY opportunities your organization has hidden; when false, return only opportunities it has not hidden; when null, ignore hidden state entirely. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["isHidden"],"additionalProperties":false},{"type":"null"}]},"location":{"description":"Optional point to measure distances from. When supplied it replaces your organization's saved location as the center for the `distance` and `rfps.rfp_inferences.local_preference_distance` columns and for any distance filter, for this request only. Omit it (or pass null) to use the organization's saved location, which is the previous behaviour. Example: { \"latitude\": 30.267153, \"longitude\": -97.743057 }.","anyOf":[{"type":"object","properties":{"latitude":{"description":"Latitude in decimal degrees. Example: 30.267153.","type":"number","minimum":-90,"maximum":90},"longitude":{"description":"Longitude in decimal degrees. Example: -97.743057.","type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}]},"skipCountTotal":{"description":"When true, skip counting the full result set so the query can stop as soon as the page is filled — much faster on large profiles, at the cost of `total` coming back as `-1` (unknown). Defaults to false. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page","classifications"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Total number of opportunities matching the search, or `-1` when the total is unknown. On a paid plan it is only counted when `search.filters` contains an open-status filter and `skipCountTotal` is not set; every other combination returns `-1`. On the free plan it is always a real count of the open opportunities matching your profile, which is typically far larger than the handful of rows returned. `-1` is not an error — page until `items` comes back empty. Example: 137.","type":"number"},"items":{"description":"The requested page of opportunities. Each item is one opportunity, flattened into columns keyed by where the value comes from: `rfps.*` is the core record, `rfps.rfp_inferences.*` is its latest AI inference, `rfps.buyer.*` is the consolidated buyer, and `score`/`distance` are computed per request.\n\nOn a paid plan every element is a full row and none are null. On the free plan the array is a fixed 15-row teaser: some elements are `null` (the row exists and is counted in `total`, but is withheld), and the rest carry only `rfps.id`, `rfps.status`, `rfps.rfp_inferences.title`, `rfps.buyer.name_pretty`, `rfps.date_due`, and `score` — every other key is present but null. Upgrade to see the withheld rows and fields.","type":"array","items":{"anyOf":[{"type":"object","properties":{"rfps.id":{"description":"The opportunity's Bidscope id; pass it to `opportunities.get`, `opportunities.get-awards`, and `opportunities.get-followers`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"rfps.date_due":{"type":["string","null"],"format":"date-time","description":"The submission deadline. Null when the source published no deadline — those opportunities stay open until they are pruned as expired rather than as past due. Example: \"2026-08-14T17:00:00.000Z\"."},"rfps.date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer published the solicitation, null when the source published no posting date. Example: \"2026-07-10T13:00:00.000Z\"."},"rfps.status":{"description":"The stored status column. Note this is the last-written value: an opportunity whose `date_due` has already passed can still read \"open\" until the nightly prune closes it, so filter on the `rfps.status` column (which also tests the due date) rather than reading this field to decide whether you can still bid. Examples: \"open\", \"closed\".","type":"string"},"rfps.status_reason":{"description":"A short free-text reason for a closed status, null while the opportunity is open. Examples: \"past due\", \"expired\", \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.private_metadata":{"description":"Source-specific metadata carried on private opportunities (the shape depends on the source), null for public ones. Example: { \"type\": \"ebuy\" }.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"rfps.is_private":{"description":"True when the opportunity is private to your organization (it came from a source only you have access to). Private opportunities belonging to other organizations are never returned. Example: false.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.customers.pretty_name":{"description":"The legacy per-source customer/portal account the opportunity was collected under. Superseded by `rfps.buyer.name_pretty`, which is the consolidated buyer. Example: \"SAM.gov\".\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.id":{"description":"The consolidated buyer-tier id for the first raw buyer linked to the opportunity's latest inference (ordered by when the link was created). Null while that raw buyer is still awaiting consolidation. Filtering `rfps.buyer.id` with `string.eq` matches this tier and every tier beneath it, so you can select a whole parent agency. Example: \"6d9c2b41-08fe-4a7d-9c33-2b8e5f1a0d47\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.name_pretty":{"description":"The buyer's full hierarchy display name (each tier joined with \" > \"), falling back to the raw root buyer name when the buyer has not been consolidated yet. Null when the opportunity has no buyer at all. Example: \"Department of Defense > Defense Logistics Agency > DLA Land and Maritime\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.buyer.root_type":{"description":"The government level/type of the buyer's root organization, null when the buyer is unconsolidated or has no root. Examples: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", \"private\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.title":{"description":"A cleaned-up title for the opportunity, written by Bidscope's AI inference from the solicitation and its documents (not the raw source title). Example: \"Facility HVAC Maintenance Services\".","type":"string"},"rfps.rfp_inferences.blurb":{"description":"A one- or two-sentence AI summary of the opportunity, null when none has been generated yet. Example: \"Annual preventive maintenance and emergency repair of HVAC systems across three depot buildings.\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.description":{"description":"The long-form AI description of the scope of work, null when none has been generated yet. Example: \"The contractor shall provide all labor, materials, tools, and equipment necessary to perform scheduled preventive maintenance ...\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.pretty_name":{"description":"Display name of the inferred place of performance, null when no location could be resolved. Example: \"Columbus, Ohio, United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.latitude":{"description":"Latitude of the inferred place of performance in decimal degrees (WGS 84), null when no location was resolved. Example: 39.9612.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.places.longitude":{"description":"Longitude of the inferred place of performance in decimal degrees (WGS 84), null when no location was resolved. Example: -82.9988.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.places.country":{"description":"Country of the inferred place of performance, as the full name returned by the geocoder. Null when no location was resolved. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.places.region":{"description":"First-level administrative region (US state) of the inferred place of performance, as the full name returned by the geocoder. Null when no location was resolved. Example: \"Ohio\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_full_name":{"description":"Legacy single inferred point of contact for the solicitation, null when none was found. Superseded by the structured contacts on `opportunities.get`. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_email_address":{"description":"Legacy inferred contact email address, null when none was found. Example: \"dana.whitfield@example.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_phone_number":{"description":"Legacy inferred contact phone number, formatted as the source published it. Null when none was found. Example: \"+1-555-0142\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.contact_mailing_address":{"description":"Legacy inferred contact mailing address as a single line, null when none was found. Example: \"3990 E Broad St, Columbus, OH 43213\".","anyOf":[{"type":"string"},{"type":"null"}]},"score":{"description":"How well the opportunity matches `matchingProfileId`, from 0 (no match) to 1 (perfect match). When the search includes an open-status filter this is the precomputed match score; otherwise it is estimated on the fly from the distance between the opportunity's and the profile's embedding centroids, so the two can differ slightly for the same opportunity. Example: 0.82.","type":"number"},"distance":{"description":"Straight-line distance in METERS to the opportunity's place of performance, measured from the request's `location` when supplied and otherwise from your organization's configured location. Null when neither is available or the opportunity has no resolved place. Example: 41230.5 (about 25.6 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.local_preference_distance":{"description":"Meters the center falls OUTSIDE the opportunity's local-preference area — the distance to the local-preference place minus that preference's radius, floored at 0. So 0 means the center is inside the preference area. The center is the request's `location` when supplied, otherwise your organization's saved location. Null when neither is available or the opportunity declares no local-preference place. Example: 12500.","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.rfp_set_asides.type":{"description":"Every set-aside/preference program the opportunity is reserved for, as inferred. Empty array when it is unrestricted. Current values are \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\", \"Native-Owned Business\", and \"Other\"; older records may still carry legacy long-form labels such as \"HUBZone Small Business\". Example: [\"Small Business\"].\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.cage_codes":{"description":"CAGE codes referenced by the solicitation (typically the approved-source list on a defense supply buy). Null when none were found. Example: [\"1ABC5\", \"7XY22\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.national_stock_numbers":{"description":"National Stock Numbers of the items being bought, null when the solicitation names none. Example: [\"5330-01-234-5678\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"rfps.rfp_inferences.type":{"description":"The kind of notice, inferred from the solicitation. Null when it could not be determined. Examples: \"Request for Proposal (RFP)\", \"Request for Quote/Qualifications (RFQ)\", \"Request for Information (RFI)\", \"Invitation for/to Bid (IFB/ITB)\", \"Sole Source\", \"Sale\", \"Award Notice\", \"Sources Sought (SS)\", \"Event\", \"Grant\", \"Other\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.level":{"description":"The level of government running the procurement, inferred from the solicitation (independent of the consolidated buyer's `root_type`). Null when undetermined. Examples: \"Federal\", \"State\", \"Local\", \"Private\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.submission_information_type":{"description":"How bids must be submitted, null when the solicitation does not say. Examples: \"online\", \"email\", \"mail\", \"other\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.top_clearance":{"description":"The highest personnel security clearance the work requires, null when none is required or none was found. Examples: \"Confidential\", \"Secret\", \"Top Secret\", \"TS/SCI\", \"TS/SAP\", \"Public Trust\", \"DOE Q\", \"DOE L\", \"NATO Secret / TS\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":{"description":"The maximum budget or award amount the solicitation states explicitly, in integer USD cents, serialized as a STRING because it is a 64-bit value. Null when the solicitation names no amount (which is the common case). Example: \"150000000\" (i.e. $1,500,000.00).","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.is_off_the_shelf":{"description":"True when what is being bought is a commercially available off-the-shelf product rather than custom work. Null when it could not be determined — the field is genuinely tri-state, so treat null as unknown rather than false. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.in_person":{"description":"True when the work must be performed on site rather than remotely. Null when undetermined (tri-state). Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.is_supply":{"description":"True when the opportunity buys goods/supplies. Null when undetermined (tri-state). An opportunity can be both a supply and a service buy. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.is_service":{"description":"True when the opportunity buys services. Null when undetermined (tri-state). An opportunity can be both a supply and a service buy. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.has_local_preference":{"description":"Derived: true when the opportunity declares any local-preference program, i.e. `local_preference_level` is non-null. Example: false.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.local_preference_level":{"description":"How strong the local preference is, null when the opportunity declares none. Examples: \"required\", \"preferred\", \"encouraged-to-apply\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.max_education_required":{"description":"The highest formal education level the solicitation requires of any proposed personnel, null when it states no education requirement. Examples: \"High school diploma or equivalent (e.g., GED)\", \"Associate degree\", \"Bachelor's degree\", \"Master's degree\", \"Professional degree (e.g., MD, JD)\", \"Doctorate (PhD, EdD, etc.)\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.has_max_education_required":{"description":"Derived: true when `max_education_required` is non-null, i.e. the solicitation states an education requirement at all. Example: false.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":{"description":"The largest minimum coverage limit across all insurance policies the solicitation requires, in integer USD cents. Null when it requires no insurance or names no limits. Example: 100000000 (i.e. $1,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"rfps.rfp_inferences.has_insurance_requirements":{"description":"Derived: true when the solicitation states insurance requirements at all (independent of whether a coverage limit was extracted). Example: true.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.has_past_performance_requirements":{"description":"Derived: true when the solicitation asks for past performance at all, i.e. `past_performance_strictness` is non-null. Example: true.\n\nNull on the free plan, which withholds this field.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfps.rfp_inferences.past_performance_strictness":{"description":"How past performance is used in the evaluation, null when the solicitation does not ask for it. Examples: \"required\" (a pass/fail gate), \"scored\" (part of the evaluation score), \"informational\" (requested but not evaluated).","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.naics_codes.code":{"description":"The single primary NAICS industry code inferred for the opportunity, null when none could be assigned. Only the primary code is returned here — use `opportunities.get` for the full list. Example: \"238220\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.psc_codes.code":{"description":"The single primary Product and Service Code (PSC/FSC) inferred for the opportunity, null when none could be assigned. Only the primary code is returned here — use `opportunities.get` for the full list. Example: \"J041\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfps.rfp_inferences.can_middleman":{"description":"True when the winning vendor may hand the entire scope of work to another organization, false when it must be self-performed (an outright ban on subcontracting or brokers, a self-performance percentage floor such as FAR 52.219-14, or a manufacturer/authorized-dealer restriction on supply). Null when the solicitation is silent, which is the common case — the field is tri-state, so treat null as unknown rather than false. Null on the free plan, which withholds this field. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["rfps.id","rfps.date_due","rfps.date_posted","rfps.status","rfps.status_reason","rfps.private_metadata","rfps.is_private","rfps.customers.pretty_name","rfps.buyer.id","rfps.buyer.name_pretty","rfps.buyer.root_type","rfps.rfp_inferences.title","rfps.rfp_inferences.blurb","rfps.rfp_inferences.description","rfps.rfp_inferences.places.pretty_name","rfps.rfp_inferences.places.latitude","rfps.rfp_inferences.places.longitude","rfps.rfp_inferences.places.country","rfps.rfp_inferences.places.region","rfps.rfp_inferences.contact_full_name","rfps.rfp_inferences.contact_email_address","rfps.rfp_inferences.contact_phone_number","rfps.rfp_inferences.contact_mailing_address","score","distance","rfps.rfp_inferences.local_preference_distance","rfps.rfp_inferences.rfp_set_asides.type","rfps.rfp_inferences.cage_codes","rfps.rfp_inferences.national_stock_numbers","rfps.rfp_inferences.type","rfps.rfp_inferences.level","rfps.rfp_inferences.submission_information_type","rfps.rfp_inferences.top_clearance","rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents","rfps.rfp_inferences.is_off_the_shelf","rfps.rfp_inferences.in_person","rfps.rfp_inferences.is_supply","rfps.rfp_inferences.is_service","rfps.rfp_inferences.has_local_preference","rfps.rfp_inferences.local_preference_level","rfps.rfp_inferences.max_education_required","rfps.rfp_inferences.has_max_education_required","rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents","rfps.rfp_inferences.has_insurance_requirements","rfps.rfp_inferences.has_past_performance_requirements","rfps.rfp_inferences.past_performance_strictness","rfps.rfp_inferences.naics_codes.code","rfps.rfp_inferences.psc_codes.code","rfps.rfp_inferences.can_middleman"],"additionalProperties":false},{"type":"null"}]}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best matches for a profile (paid plan)","description":"Rank everything by match score. With no open-status filter, `total` comes back as `-1` — page until `items` is empty. Every row is complete.","request":{"matchingProfileId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1,"classifications":null},"response":{"total":-1,"items":[{"rfps.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","rfps.date_due":"2026-08-14T17:00:00.000Z","rfps.date_posted":"2026-07-10T13:00:00.000Z","rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":false,"rfps.customers.pretty_name":"SAM.gov","rfps.buyer.id":"6d9c2b41-08fe-4a7d-9c33-2b8e5f1a0d47","rfps.buyer.name_pretty":"Department of Defense > Defense Logistics Agency > DLA Land and Maritime","rfps.buyer.root_type":"federal","rfps.rfp_inferences.title":"Facility HVAC Maintenance Services","rfps.rfp_inferences.blurb":"Annual preventive maintenance and emergency repair of HVAC systems across three depot buildings.","rfps.rfp_inferences.description":"The contractor shall provide all labor, materials, tools, and equipment necessary to perform scheduled preventive maintenance and unscheduled repair of heating, ventilation, and air-conditioning systems at the installation.","rfps.rfp_inferences.places.pretty_name":"Columbus, Ohio, United States","rfps.rfp_inferences.places.latitude":39.9612,"rfps.rfp_inferences.places.longitude":-82.9988,"rfps.rfp_inferences.places.country":"United States","rfps.rfp_inferences.places.region":"Ohio","rfps.rfp_inferences.contact_full_name":"Dana Whitfield","rfps.rfp_inferences.contact_email_address":"dana.whitfield@example.gov","rfps.rfp_inferences.contact_phone_number":"+1-555-0142","rfps.rfp_inferences.contact_mailing_address":"3990 E Broad St, Columbus, OH 43213","score":0.82,"distance":41230.5,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":["Small Business"],"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":"Request for Proposal (RFP)","rfps.rfp_inferences.level":"Federal","rfps.rfp_inferences.submission_information_type":"online","rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":"150000000","rfps.rfp_inferences.is_off_the_shelf":false,"rfps.rfp_inferences.in_person":true,"rfps.rfp_inferences.is_supply":false,"rfps.rfp_inferences.is_service":true,"rfps.rfp_inferences.has_local_preference":false,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":false,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":100000000,"rfps.rfp_inferences.has_insurance_requirements":true,"rfps.rfp_inferences.has_past_performance_requirements":true,"rfps.rfp_inferences.past_performance_strictness":"scored","rfps.rfp_inferences.naics_codes.code":"238220","rfps.rfp_inferences.psc_codes.code":"J041","rfps.rfp_inferences.can_middleman":false}]}},{"title":"The same request on the free plan","description":"Identical arguments, including filters and a page size of 100 — all ignored. The response is the fixed teaser: withheld rows are null, visible rows carry six fields, and `total` still counts every match. Truncated here to the first five of the fifteen elements.","request":{"matchingProfileId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","search":{"orderBy":"rfps.date_due","sort":"asc","pageSize":100,"filters":{"type":"filter","column":"rfps.buyer.root_type","filter":{"operator":"enum.eq","value":"city"}}},"page":3,"classifications":null},"response":{"total":8341,"items":[null,{"rfps.id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","rfps.date_due":"2026-09-02T22:00:00.000Z","rfps.date_posted":null,"rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":null,"rfps.customers.pretty_name":null,"rfps.buyer.id":null,"rfps.buyer.name_pretty":"City of Fairhaven > Department of Public Works","rfps.buyer.root_type":null,"rfps.rfp_inferences.title":"Custodial Services for Municipal Buildings","rfps.rfp_inferences.blurb":null,"rfps.rfp_inferences.description":null,"rfps.rfp_inferences.places.pretty_name":null,"rfps.rfp_inferences.places.latitude":null,"rfps.rfp_inferences.places.longitude":null,"rfps.rfp_inferences.places.country":null,"rfps.rfp_inferences.places.region":null,"rfps.rfp_inferences.contact_full_name":null,"rfps.rfp_inferences.contact_email_address":null,"rfps.rfp_inferences.contact_phone_number":null,"rfps.rfp_inferences.contact_mailing_address":null,"score":0.71,"distance":null,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":null,"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":null,"rfps.rfp_inferences.level":null,"rfps.rfp_inferences.submission_information_type":null,"rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":null,"rfps.rfp_inferences.is_off_the_shelf":null,"rfps.rfp_inferences.in_person":null,"rfps.rfp_inferences.is_supply":null,"rfps.rfp_inferences.is_service":null,"rfps.rfp_inferences.has_local_preference":null,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":null,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":null,"rfps.rfp_inferences.has_insurance_requirements":null,"rfps.rfp_inferences.has_past_performance_requirements":null,"rfps.rfp_inferences.past_performance_strictness":null,"rfps.rfp_inferences.naics_codes.code":null,"rfps.rfp_inferences.psc_codes.code":null,"rfps.rfp_inferences.can_middleman":null},null,null,{"rfps.id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","rfps.date_due":"2026-09-18T21:00:00.000Z","rfps.date_posted":null,"rfps.status":"open","rfps.status_reason":null,"rfps.private_metadata":null,"rfps.is_private":null,"rfps.customers.pretty_name":null,"rfps.buyer.id":null,"rfps.buyer.name_pretty":"Marbury County > Parks and Recreation Department","rfps.buyer.root_type":null,"rfps.rfp_inferences.title":"Grounds Maintenance and Landscaping Services for County Parks","rfps.rfp_inferences.blurb":null,"rfps.rfp_inferences.description":null,"rfps.rfp_inferences.places.pretty_name":null,"rfps.rfp_inferences.places.latitude":null,"rfps.rfp_inferences.places.longitude":null,"rfps.rfp_inferences.places.country":null,"rfps.rfp_inferences.places.region":null,"rfps.rfp_inferences.contact_full_name":null,"rfps.rfp_inferences.contact_email_address":null,"rfps.rfp_inferences.contact_phone_number":null,"rfps.rfp_inferences.contact_mailing_address":null,"score":0.77,"distance":null,"rfps.rfp_inferences.local_preference_distance":null,"rfps.rfp_inferences.rfp_set_asides.type":null,"rfps.rfp_inferences.cage_codes":null,"rfps.rfp_inferences.national_stock_numbers":null,"rfps.rfp_inferences.type":null,"rfps.rfp_inferences.level":null,"rfps.rfp_inferences.submission_information_type":null,"rfps.rfp_inferences.top_clearance":null,"rfps.rfp_inferences.explicit_budget_or_award_amount_max_usd_cents":null,"rfps.rfp_inferences.is_off_the_shelf":null,"rfps.rfp_inferences.in_person":null,"rfps.rfp_inferences.is_supply":null,"rfps.rfp_inferences.is_service":null,"rfps.rfp_inferences.has_local_preference":null,"rfps.rfp_inferences.local_preference_level":null,"rfps.rfp_inferences.max_education_required":null,"rfps.rfp_inferences.has_max_education_required":null,"rfps.rfp_inferences.insurance_max_coverage_limit_usd_cents":null,"rfps.rfp_inferences.has_insurance_requirements":null,"rfps.rfp_inferences.has_past_performance_requirements":null,"rfps.rfp_inferences.past_performance_strictness":null,"rfps.rfp_inferences.naics_codes.code":null,"rfps.rfp_inferences.psc_codes.code":null,"rfps.rfp_inferences.can_middleman":null}]}}]}]},{"procedure":"opportunities.get","versions":[{"version":"2026-07-05","description":"The complete details record for one opportunity. Everything outside `rfp.rfp_inferences` is sourced verbatim from the buyer or portal — status, dates, titles, identifiers, published classification codes, attachments, per-source records, and legal notices. Everything inside `rfp.rfp_inferences` is AI-extracted from the solicitation text and its documents: the cleaned title and description, set-asides, smart codes, bonds and insurance, past-performance and local-preference rules, contract periods, submission mechanics, place of performance, buyer hierarchy, and contacts. Only the latest inference is returned, so `rfp_inferences` holds exactly one element once the opportunity has been processed and is empty before that. Up to 5 linked contract awards are embedded in `rfp.awards`, newest link first, with `rfp.award_count` giving the true total; `rfp.awards_next_cursor` is set when more than 5 exist, but `opportunities.get-awards` takes no cursor and returns the first 10 linked awards directly, so treat the cursor as a \"there are more\" marker (its mirror image, `awards.get`'s `solicitations_next_cursor`, does feed `awards.get-solicitations`). Opportunities private to an organization are visible only to that organization's tokens. Returns 404 when the opportunity does not exist or is private to another organization.","plans":["free","starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The opportunity's Bidscope id (`rfps.id`, as returned by `opportunities.search` as `\"rfps.id\"`). Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rfp":{"type":"object","properties":{"status":{"description":"Whether the opportunity is still accepting bids: \"open\" or \"closed\". Example: \"open\".","anyOf":[{"type":"string"},{"type":"null"}]},"status_reason":{"description":"A one-to-three-word explanation of why the opportunity is closed — the source's own wording, or one Bidscope assigns: \"past due\" (the deadline passed), \"expired\" (no deadline, but too old), or \"pruned\" (retired by an administrator). Always null while the opportunity is open. Example: \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"source_url":{"description":"The canonical link to the opportunity on the buyer's or portal's own site. When several sources describe the same opportunity, this is the winning one; per-source links are in `crawled_rfps`. Example: \"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view\".","anyOf":[{"type":"string"},{"type":"null"}]},"date_due":{"type":["string","null"],"format":"date-time","description":"The bid submission deadline. Null when the source published no deadline (common on Sources Sought and Award Notices). Example: \"2026-08-21T21:00:00.000Z\"."},"date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer published the solicitation — not when Bidscope first saw it. Null when the source published no date. Example: \"2026-07-14T00:00:00.000Z\"."},"title":{"description":"The opportunity's title exactly as the source published it, unedited. For a cleaned-up version see `rfp_inferences[0].title`. Example: \"HVAC PREVENTIVE MAINT SVCS - DEPOT OPS\". Null when the source published no title.","anyOf":[{"type":"string"},{"type":"null"}]},"solicitation_identifier":{"description":"The buyer's own reference number for the solicitation, as published. Null when the source publishes none. Example: \"SPE8EH-26-R-0142\".","anyOf":[{"type":"string"},{"type":"null"}]},"private_metadata":{"description":"Extra metadata carried on opportunities that are private to a single organization. In practice the only key is `type`, marking the private channel the opportunity arrived through. Null for ordinary public opportunities, which is the overwhelming majority. Example: { \"type\": \"ebuy\" }.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"customers":{"description":"The legacy buyer record, deduplicated only by exact name match and superseded by the buyer hierarchy under `rfp_inferences[].inferred_rfp_raw_buyers[]` — prefer that for identifying who is buying. Every opportunity carries one, so this is rarely null.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"The legacy buyer's display name. Example: \"State of Illinois\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["pretty_name"],"additionalProperties":false},{"type":"null"}]},"explicit_naics_codes":{"description":"The NAICS code the source itself published for this opportunity, verbatim rather than inferred. Null when the source published none — which is normal outside federal portals. For Bidscope's own classification see `rfp_inferences[].inferred_naics_codes`.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"explicit_psc_codes":{"description":"The PSC/FSC code the source itself published, verbatim rather than inferred. Null when the source published none. For Bidscope's own classification see `rfp_inferences[].inferred_psc_codes`.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"has_external_documents":{"description":"True when the source links to solicitation attachments that Bidscope could not download itself — typically because they sit behind a registration or login wall, or are not fetchable files. Set by the collector, not by the AI, and sticky across merges: once any source reports external documents it stays true. When this is true, follow `source_url` or `rfp_inferences[].document_download_instructions` to obtain the rest of the package. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfp_inferences":{"description":"The AI-extracted view of the opportunity. Filtered to the latest inference only, so this array holds exactly one element for any opportunity that has been processed, and is empty for one that has not been (or whose inference was superseded and not yet replaced). Everything in here is model output derived from the solicitation text and its documents; everything outside it is sourced verbatim.","type":"array","items":{"type":"object","properties":{"is_latest":{"description":"Whether this is the current inference for the opportunity. The query filters on `is_latest = true`, so in this response it is always true — superseded inferences are never returned. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"inferred_naics_codes":{"description":"The single NAICS code the AI judged to best classify the work, chosen even when the buyer published none. Compare with the top-level `explicit_naics_codes`, which is the code the source itself published. Null when the model could not pick one with confidence.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"inferred_psc_codes":{"description":"The single PSC/FSC (Product and Service Code) the AI judged to best classify the work. Compare with the top-level `explicit_psc_codes`, which the source published. Null when the model could not pick one with confidence.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"rfp_set_asides":{"description":"Business set-aside designations the AI found stated in the solicitation. Empty when the solicitation states none or the language was too unclear to classify — an empty array is not a guarantee the opportunity is unrestricted.","type":"array","items":{"type":"object","properties":{"type":{"description":"The set-aside normalized to one of Bidscope's canonical categories: \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Native-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\", or \"Other\" when none of the above fit. Example: \"Service-Disabled Veteran-Owned Business\".","type":"string"},"raw":{"description":"The set-aside's name as written in the solicitation (lightly formatting-corrected), preserved because each buyer uses its own program names and acronyms. Use this to look the program up on the buyer's own site. Example: \"SDVOSB Set-Aside\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","raw"],"additionalProperties":false}},"rfp_smart_codes":{"description":"Exactly three AI-generated capability tags summarizing what the opportunity actually asks for, used by Bidscope to score fit against a vendor's own smart codes. Empty only when the inference predates smart-code generation or generation failed.","type":"array","items":{"type":"object","properties":{"content":{"description":"The smart code phrase: at most four human-readable words, lowercased, more specific than an industry (\"construction\") but less specific than a SKU (\"8ft red ladder\"), and free of set-aside or quality language. Example: \"sidewalk construction\".","type":"string"}},"required":["content"],"additionalProperties":false}},"rfp_required_bonds":{"description":"Surety bonds the solicitation requires bidders to post (common on construction work). Empty when the solicitation mentions no bonds; bonds stated with a zero amount are dropped.","type":"array","items":{"type":"object","properties":{"type":{"description":"The kind of surety bond required. One of \"bid\", \"payment\", \"performance\", or \"other\". Example: \"performance\".","type":"string"},"other_type":{"description":"The bond's name when `type` is \"other\"; null for the three named types. Example: \"Maintenance Bond\".","anyOf":[{"type":"string"},{"type":"null"}]},"amount_percentage":{"description":"The bond amount expressed as a FRACTION of the contract or bid value, not a percent number — a solicitation demanding 10% is stored as 0.1. Null when the bond is stated as a flat amount (then `amount_fixed_usd_cents` is set) or no amount was given. Example: 0.1.","anyOf":[{"type":"number"},{"type":"null"}]},"amount_fixed_usd_cents":{"description":"The bond amount as a flat sum in integer USD cents. Null when the bond is stated as a percentage or no amount was given; the two amount fields are never both set. Example: 1000000 (i.e. $10,000.00).","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","other_type","amount_percentage","amount_fixed_usd_cents"],"additionalProperties":false}},"inferred_rfp_contacts":{"description":"Buyer-side points of contact the AI extracted from the solicitation and its documents, deduplicated into Bidscope's `people` table. Empty when the solicitation published no contact details. These are procurement contacts for the opportunity, not vendor contacts.","type":"array","items":{"type":"object","properties":{"people":{"description":"The person record this contact points at. Null when the linked person row has been removed or suppressed.","anyOf":[{"type":"object","properties":{"id":{"description":"The contact's Bidscope person id (`people.id`), stable across solicitations once the person is consolidated. Absent on older cached inferences. Example: \"5d2e9a71-3c48-4f60-b1a9-8e7f2c0d4a63\".","anyOf":[{"type":"string"},{"type":"null"}]},"full_name":{"description":"The contact's name as published by the buyer. Null when the solicitation gave only an email or phone. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"The contact's email address, null when none was published. Example: \"dana.whitfield@example-agency.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"description":"The contact's phone number, in whatever format the buyer published. Null when none was published. Example: \"+1 202-555-0143\".","anyOf":[{"type":"string"},{"type":"null"}]},"places":{"description":"The contact's location, geocoded from any address published alongside them. Null when no address was published or geocoding failed.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"Display name of the contact's geocoded location. Example: \"Arlington, Virginia, USA\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["pretty_name"],"additionalProperties":false},{"type":"null"}]}},"required":["full_name","email_address","phone_number","places"],"additionalProperties":false},{"type":"null"}]}},"required":["people"],"additionalProperties":false}},"inferred_rfp_raw_buyers":{"description":"The buying organization(s) behind the opportunity. Usually one entry. Empty when no buyer could be extracted from the source.","type":"array","items":{"type":"object","properties":{"raw_buyers":{"description":"The per-solicitation raw buyer record the AI extracted, and its link into the consolidated buyer hierarchy. Null when the raw buyer row has been removed.","anyOf":[{"type":"object","properties":{"buyer_tiers":{"description":"The consolidated buyer tier this raw buyer resolved to. Null while consolidation is still pending — raw buyers are recorded per solicitation and matched to the canonical hierarchy asynchronously, so a freshly crawled opportunity can have a raw buyer with no tier yet.","anyOf":[{"type":"object","properties":{"id":{"description":"The consolidated buyer tier's id (`buyer_tiers.id`), usable with the `buyers` endpoints. Example: \"7a1c4e08-62b9-4d37-8f50-2b6e9c3a1d54\".","type":"string"},"name_pretty":{"description":"Display name of this tier alone, without its ancestors. Example: \"Defense Logistics Agency\".","anyOf":[{"type":"string"},{"type":"null"}]},"name_pretty_hierarchy":{"description":"The tier's full path from the root organization down to itself, useful as a one-line buyer label. Absent on older cached inferences. Example: \"United States of America > Department of Defense > Defense Logistics Agency\".","anyOf":[{"type":"string"},{"type":"null"}]},"parent_buyer_tier_id":{"description":"The id of this tier's parent in the buyer hierarchy; null when this tier is itself the root organization. Example: \"c93f5b27-8a10-4e6d-b4f2-1d80a7c56e39\".","anyOf":[{"type":"string"},{"type":"null"}]},"buyer_roots":{"description":"Attributes of the root organization this tier descends from. Null when the tier has not been attached to a root yet.","anyOf":[{"type":"object","properties":{"root_type":{"description":"What kind of organization sits at the root of this buyer's hierarchy. One of \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", or \"private\". Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_coop":{"description":"True when the root is a purchasing group or cooperative rather than a single entity — a cooperative of California school districts would be `root_type: \"k12\"` with `is_coop: true`. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["root_type","is_coop"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name_pretty","parent_buyer_tier_id","buyer_roots"],"additionalProperties":false},{"type":"null"}]}},"required":["buyer_tiers"],"additionalProperties":false},{"type":"null"}]}},"required":["raw_buyers"],"additionalProperties":false}},"rfp_recompete_estimates":{"description":"Projected recompete dates, derived arithmetically from `contract_period_months` plus a contract start anchor — not read from the solicitation. Empty when the contract period is unknown or implausible. These are estimates for pipeline planning, not announced dates.","type":"array","items":{"type":"object","properties":{"estimated_recompeted_at":{"description":"Estimated date this contract period ends and the work could come up for bid again, as an ISO 8601 timestamp. Computed as the contract start anchor plus the cumulative length of every period up to and including `period_index`. Null when no anchor date could be established. Example: \"2029-09-30T00:00:00.000Z\".","anyOf":[{"type":"string"},{"type":"null"}]},"period_index":{"description":"Zero-based index into `contract_period_months` identifying which period this estimate is the end of: 0 is the end of the base period, 1 the end of the first option period, and so on. Example: 0.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["estimated_recompeted_at","period_index"],"additionalProperties":false}},"title":{"description":"An AI-cleaned, human-readable title describing what is being requested. Often clearer than the source's own `rfp.title`, which is preserved verbatim at the top level. Example: \"Commercial HVAC Preventive Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"blurb":{"description":"A one-sentence at-a-glance summary of what is requested and by whom, suitable for a list row. Example: \"The Defense Logistics Agency seeks a contractor to provide scheduled preventive maintenance for commercial HVAC systems across three depots.\"","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"One to three AI-written paragraphs summarizing the opportunity in enough detail for a vendor to judge fit. Deliberately excludes contact details and location (those have their own fields) and never names the source portal. Synthesized from the solicitation and its attached documents. Example: \"The agency requires quarterly preventive maintenance on approximately 120 rooftop units...\"","anyOf":[{"type":"string"},{"type":"null"}]},"milestones":{"description":"A JSON array of key dates extracted from the solicitation. Each item is `{ label, date, meeting }`: `label` is free text naming the milestone (there is no fixed enum — e.g. \"Pre-Bid Meeting\", \"Questions Due Date\", \"Close Date\"), `date` is the milestone date, and `meeting` is null unless the milestone is attendable, in which case it is `{ is_required, physical_location_address, physical_location_details, virtual_meeting_url, virtual_meeting_joining_information }`. Empty array when the solicitation states no dated events. Example: [{ \"label\": \"Pre-Bid Site Visit\", \"date\": \"2026-08-04\", \"meeting\": { \"is_required\": true, \"physical_location_address\": \"1200 Depot Road, Richmond, VA 23297\", \"physical_location_details\": \"Building 4, visitor gate\", \"virtual_meeting_url\": null, \"virtual_meeting_joining_information\": null } }]."},"type":{"description":"The kind of solicitation, normalized to one of \"Request for Proposal (RFP)\", \"Request for Quote/Qualifications (RFQ)\", \"Request for Information (RFI)\", \"Invitation for/to Bid (IFB/ITB)\", \"Sources Sought\", \"Sole Source\", \"Sale\" (the agency is selling goods or assets), \"Award Notice\", \"Event\", \"Grant\", or \"Other\". Example: \"Invitation for/to Bid (IFB/ITB)\".","anyOf":[{"type":"string"},{"type":"null"}]},"other_type":{"description":"A free-text solicitation type used when `type` is \"Other\"; null otherwise. Example: \"Prequalification Application\".","anyOf":[{"type":"string"},{"type":"null"}]},"level":{"description":"The level of government issuing the opportunity: \"Federal\", \"State\", \"Local\", or \"Private\". Example: \"Federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"in_person":{"description":"True when the solicitation explicitly states the work must be performed on site, false when it explicitly allows remote performance. Null when the solicitation is silent, or for goods-only purchases — it is never guessed from the industry or location. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"top_clearance":{"description":"The highest security clearance the solicitation explicitly requires (federal work only). One of \"Confidential\", \"Secret\", \"Top Secret\", \"TS/SCI\", \"TS/SAP\", \"Public Trust\", \"DOE Q\", \"DOE L\", or \"NATO Secret / TS\". Null when no clearance is required or none is stated — there is no explicit \"None\" value. Example: \"Secret\".","anyOf":[{"type":"string"},{"type":"null"}]},"max_education_required":{"description":"The highest education level explicitly required across all staffed positions (a role mix of two bachelor's and one PhD yields the doctorate value). One of \"Primary/elementary school\", \"Some high school (no diploma)\", \"High school diploma or equivalent (e.g., GED)\", \"Some college (no degree)\", \"Trade/vocational/technical training\", \"Associate degree\", \"Bachelor's degree\", \"Master's degree\", \"Professional degree (e.g., MD, JD)\", or \"Doctorate (PhD, EdD, etc.)\". Null when no education requirement is stated. Example: \"Bachelor's degree\".","anyOf":[{"type":"string"},{"type":"null"}]},"insurance_required":{"description":"True when the solicitation mandates any insurance coverage, false when it explicitly says none is required, null when insurance is never mentioned. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfp_insurance_coverages":{"description":"The specific insurance coverages the solicitation requires. Empty when `insurance_required` is false or insurance is never mentioned.","type":"array","items":{"type":"object","properties":{"type":{"description":"The coverage name as stated. Free text, not an enum — common values are \"General Liability\", \"Workers Compensation\", \"Auto Liability\", \"Professional Liability\", and \"Cyber Liability\". Example: \"General Liability\".","type":"string"},"minimum_limit_usd_cents":{"description":"The minimum per-occurrence (or equivalent) limit in integer USD cents. Null when the solicitation gives no figure or says only \"statutory\". Example: 100000000 (i.e. $1,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","minimum_limit_usd_cents"],"additionalProperties":false}},"past_performance_strictness":{"description":"How past-performance references are used in the award decision: \"required\" (a hard responsibility gate — too little qualifying past performance makes a bid non-responsive), \"scored\" (contributes points to the evaluation), or \"informational\" (collected but not formally rated). Null when past performance is not mentioned. Example: \"scored\".","anyOf":[{"type":"string"},{"type":"null"}]},"past_performance_minimum_count":{"description":"How many prior projects or references the bidder must supply. Null when past performance is not mentioned or no count is given. Example: 3.","anyOf":[{"type":"number"},{"type":"null"}]},"past_performance_recency_years":{"description":"How recently a prior project must have been performed to count, in years. Null when no recency window is stated. Example: 5.","anyOf":[{"type":"number"},{"type":"null"}]},"past_performance_minimum_project_value_usd_cents":{"description":"The minimum size a prior project must have been to count as relevant past performance, in integer USD cents. When the solicitation states several tiers, the largest is used. Null when no dollar threshold is stated. Example: 50000000 (i.e. $500,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"past_performance_contact_required":{"description":"True when each reference must include a reachable client point of contact (a name plus a phone number or email). Null when past performance is not mentioned. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"local_preference_level":{"description":"How strongly the buyer favors local vendors, taken from the most stringent statement in the solicitation: \"required\" (local vendors are mandated), \"preferred\" (local vendors get a scoring or evaluation advantage), or \"encouraged-to-apply\" (softer explicit encouragement). Null unless explicit local-vendor language appears — it is never inferred from the buyer's own location. Example: \"preferred\".","anyOf":[{"type":"string"},{"type":"null"}]},"local_preference_raw":{"description":"The passage from the solicitation that establishes the local preference, quoted verbatim, so a bidder can verify the classification. Null when `local_preference_level` is null. Example: \"Bidders whose principal place of business lies within Mecklenburg County shall receive a five percent evaluation preference.\"","anyOf":[{"type":"string"},{"type":"null"}]},"local_preference_radius_mi":{"description":"The radius in miles when the preference is expressed as a distance (\"within 150 miles of Charlotte\"). Null when the preference names a jurisdiction rather than a distance, or when there is no preference. Example: 150.","anyOf":[{"type":"number"},{"type":"null"}]},"local_preference_place":{"description":"The geographic area the local preference applies to, geocoded from the place named in the solicitation. Null when there is no local preference or the named place could not be geocoded.","anyOf":[{"type":"object","properties":{"bbox":{"description":"The place's GeoJSON bounding box as [minLng, minLat, maxLng, maxLat], usable to test whether a vendor's address falls inside the preference area. Null when the geocoded place carries no bounding box. Example: [-81.06, 35.0, -80.55, 35.4].","anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]}},"required":["bbox"],"additionalProperties":false},{"type":"null"}]},"contract_period_months":{"description":"The contract's periods, in months, first entry being the base period and the rest option periods in order. \"Three-year base with two one-year options\" becomes [36, 12, 12]; \"base year plus four option years\" becomes [12, 12, 12, 12, 12]. Null when the solicitation does not state a contract length — it is never guessed. Example: [12, 12, 12, 12, 12].","anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]},"contract_period_raw_text":{"description":"The phrase from the solicitation that `contract_period_months` was derived from, quoted verbatim so the parse can be checked. Null when no contract length is stated. Example: \"one (1) base year with four (4) one-year renewal options\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_supply":{"description":"True when goods, products, or software must be supplied on award. Null when the solicitation is ambiguous about it. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"is_service":{"description":"True when a service must be rendered — professional services, staffing, or installation. Delivery or shipping alone does not count as a service, but installation does, so a supply-and-install contract is both `is_supply` and `is_service`. Null when ambiguous. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"national_stock_numbers":{"description":"National Stock Numbers explicitly cited in the solicitation, normalized to bare 13-digit strings (the conventional NSN display form is XXXX-XX-XXX-XXXX). Never inferred. Null when none are cited. Example: [\"5340015551234\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"cage_codes":{"description":"CAGE (Commercial and Government Entity) codes written out in the solicitation, uppercased — five alphanumeric characters beginning and ending with a digit. Never inferred from a company name. Null when none appear. Example: [\"1A2B3\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"is_off_the_shelf":{"description":"When a product is being supplied, true if it is a commercially available off-the-shelf item (including a configured instance of one) and false if it must be custom built. Null when no product is involved or there is not enough information. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"explicit_budget_or_award_amount_min_usd_cents":{"description":"The low end of the total budget or award amount the solicitation states, in integer USD cents. Equals the max when a single figure is given. Only ever a total contract or budget value — never a unit price or hourly rate. Null when no total is stated. Example: 250000000 (i.e. $2,500,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"explicit_budget_or_award_amount_max_usd_cents":{"description":"The high end of the stated total budget or award amount, in integer USD cents. Null when no total is stated; the min and max are always both set or both null. Example: 400000000 (i.e. $4,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"submission_information_type":{"description":"How bids are submitted: \"email\", \"mail\", \"online\", or \"other\". When the solicitation allows several methods this is the preferred (or easiest) one. Federal solicitations default to \"online\" via SAM.gov. Null when the solicitation does not say. Example: \"online\".","anyOf":[{"type":"string"},{"type":"null"}]},"submission_information_other_type":{"description":"A free-text description of the submission method when `submission_information_type` is \"other\"; null otherwise. Example: \"Hand delivery to the Purchasing counter\".","anyOf":[{"type":"string"},{"type":"null"}]},"submission_information_email_address":{"description":"The address bids are emailed to. Normally populated when the type is \"email\"; null otherwise. Example: \"bids@example-agency.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"submission_information_mail_address":{"description":"The postal address bids are mailed to. Normally populated when the type is \"mail\"; null otherwise. Example: \"Purchasing Division, 500 Main Street, Room 210, Springfield, IL 62701\".","anyOf":[{"type":"string"},{"type":"null"}]},"submission_information_online_portal_url":{"description":"The portal URL bids are submitted through, only when the solicitation states it explicitly — it is never guessed, so this can be null even when the type is \"online\". Example: \"https://sam.gov/opp/example/view\".","anyOf":[{"type":"string"},{"type":"null"}]},"submission_information_extra_instructions":{"description":"One or two sentences of concrete submission mechanics that the other submission fields do not cover — copy counts, required file formats, envelope or subject-line labeling, a specific deadline time. Deliberately excludes evaluation criteria, award process, and reservation-of-rights language. Null when there is nothing to add. Example: \"Submit one original and three bound copies in a sealed envelope marked with the solicitation number; late bids are not accepted after 2:00 PM local time.\"","anyOf":[{"type":"string"},{"type":"null"}]},"document_download_instructions":{"description":"How a vendor obtains the solicitation package (scope of work, addenda, bid sheets) when Bidscope could not host the files itself — extracted only from explicit text, with every sub-field independently nullable. Null when the solicitation says nothing about it. Most useful when `documents` is empty and `has_external_documents` is true.","anyOf":[{"type":"object","properties":{"url":{"description":"The web address where the solicitation documents can be obtained. Example: \"https://example-agency.gov/purchasing/bids\".","anyOf":[{"type":"string"},{"type":"null"}]},"site_name":{"description":"The name of the site or portal hosting the documents. Example: \"City of Springfield Vendor Portal\".","anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"description":"A phone number to call to request the documents. Example: \"+1 217-555-0198\".","anyOf":[{"type":"string"},{"type":"null"}]},"person_name":{"description":"The person to contact for the documents. Example: \"Marcus Ellery\".","anyOf":[{"type":"string"},{"type":"null"}]},"person_title":{"description":"That person's job title. Example: \"Senior Procurement Officer\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"An email address to write to for the documents. Example: \"purchasing@example-city.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"address":{"description":"A physical address where documents may be picked up. Example: \"500 Main Street, Room 210, Springfield, IL 62701\".","anyOf":[{"type":"string"},{"type":"null"}]},"location_name":{"description":"The name of that pickup location. Example: \"City Hall Purchasing Counter\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","site_name","phone_number","person_name","person_title","email_address","address","location_name"],"additionalProperties":false},{"type":"null"}]},"places":{"description":"Where the work will be performed, geocoded from the location the AI extracted from the solicitation. Null when no place of performance could be determined.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"Display name of the place of performance. Example: \"Richmond, Virginia, USA\".","anyOf":[{"type":"string"},{"type":"null"}]},"region":{"description":"The first-level administrative region — a state for US places. Example: \"Virginia\".","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"The country name. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"data":{"description":"The raw geocoder payload for the place. Chiefly useful for `geometry.coordinates` ([longitude, latitude]) and `bbox` ([minLng, minLat, maxLng, maxLat]). Example: { \"geometry\": { \"coordinates\": [-77.436, 37.541] }, \"bbox\": [-77.6, 37.4, -77.3, 37.65] }."}},"required":["pretty_name","region","country","data"],"additionalProperties":false},{"type":"null"}]},"place_seo_lists":{"description":"The nearest place-based Bidscope listing page to the place of performance, matched within 100 miles (160,934 metres) of the list's own point. Null when no list falls within that radius or the place of performance is unknown.","anyOf":[{"type":"object","properties":{"slug":{"description":"The list's URL slug, forming the path `/list/<slug>` on bidscope.ai. Example: \"virginia\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slug"],"additionalProperties":false},{"type":"null"}]}},"required":["is_latest","inferred_naics_codes","inferred_psc_codes","rfp_set_asides","rfp_smart_codes","rfp_required_bonds","inferred_rfp_contacts","inferred_rfp_raw_buyers","rfp_recompete_estimates","title","blurb","description","milestones","type","other_type","level","in_person","top_clearance","max_education_required","insurance_required","rfp_insurance_coverages","past_performance_strictness","past_performance_minimum_count","past_performance_recency_years","past_performance_minimum_project_value_usd_cents","past_performance_contact_required","local_preference_level","local_preference_raw","local_preference_radius_mi","local_preference_place","contract_period_months","contract_period_raw_text","is_supply","is_service","national_stock_numbers","cage_codes","is_off_the_shelf","explicit_budget_or_award_amount_min_usd_cents","explicit_budget_or_award_amount_max_usd_cents","submission_information_type","submission_information_other_type","submission_information_email_address","submission_information_mail_address","submission_information_online_portal_url","submission_information_extra_instructions","document_download_instructions","places","place_seo_lists"],"additionalProperties":false}},"documents":{"description":"Public, still-current solicitation attachments. Withdrawn and restricted documents are filtered out entirely. Empty when the buyer published none, when they sit behind a login wall (see `has_external_documents`), or when Bidscope has not yet fetched them.","type":"array","items":{"type":"object","properties":{"removed_at":{"type":["string","null"],"format":"date-time","description":"When the document was withdrawn. The query excludes withdrawn documents, so this is always null in this response; it is retained for schema compatibility."},"title":{"description":"The document's display title. Example: \"Attachment A - Statement of Work.pdf\". Null when the source gave none.","anyOf":[{"type":"string"},{"type":"null"}]},"date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer posted this document, which for addenda is later than the solicitation's own `date_posted`. Null when unknown. Example: \"2026-07-16T00:00:00.000Z\"."},"is_private":{"description":"Whether the document is restricted. The query excludes restricted documents, so this is always false in this response; it is retained for schema compatibility.","anyOf":[{"type":"boolean"},{"type":"null"}]},"filename":{"description":"The original filename, useful as the `download` parameter when building a storage URL. Example: \"attachment-a-sow.pdf\".","anyOf":[{"type":"string"},{"type":"null"}]},"stored_documents":{"description":"The stored, content-addressed copy of the file. Because blobs are deduplicated by content hash, one stored document can back the same attachment across several opportunities. Null when no copy was stored, in which case only the legacy `key` or the source's own link is available.","anyOf":[{"type":"object","properties":{"key":{"description":"The authoritative object-storage key for the stored copy; prefer this over the sibling `key` when present. Example: \"rfps/3f8a1c42/attachment-a-sow.pdf\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_in_supabase":{"description":"False when the binary has been archived out of the storage bucket and can no longer be downloaded — the metadata and extracted text survive, but the file does not. Check this before building a download URL. True (or null, on older rows) when the file is still retrievable. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["key","is_in_supabase"],"additionalProperties":false},{"type":"null"}]},"key":{"description":"A legacy storage key kept on the document row itself; use it only when `stored_documents.key` is absent. Together they form the download path `<supabase-url>/storage/v1/object/public/documents/<key>`. Example: \"rfps/3f8a1c42/attachment-a-sow.pdf\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["removed_at","title","date_posted","is_private","filename","stored_documents","key"],"additionalProperties":false}},"crawled_rfps":{"description":"One record per source Bidscope found this opportunity on. Multiple entries mean the same solicitation was published in several places and merged into one Bidscope record — useful for auditing where the merged fields came from. Rarely empty.","type":"array","items":{"type":"object","properties":{"source":{"description":"The portal or collector this record came from, as a Bidscope source slug. Examples: \"sam-dot-gov\", \"planet-bids\", \"bonfire\", \"bidnet-direct\", \"grants-dot-gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"source_url":{"description":"The link to the opportunity on that particular source. Example: \"https://www.planetbids.com/portal/12345/bo/bo-detail/98765\".","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"description":"The title as that source published it, which can differ from the top-level `title` when several sources are merged. Example: \"HVAC Preventive Maintenance - Depot Operations\".","anyOf":[{"type":"string"},{"type":"null"}]},"solicitation_identifier":{"description":"The reference number as that source published it. Example: \"SPE8EH-26-R-0142\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","source_url","title","solicitation_identifier"],"additionalProperties":false}},"public_notices":{"description":"Legal advertisements for this solicitation published in newspapers of record, gathered across every source record and flattened into one list. Empty for the many opportunities that were never advertised in print, and for all federal portal opportunities.","type":"array","items":{"type":"object","properties":{"content":{"description":"The notice text as printed. Example: \"NOTICE TO BIDDERS: Sealed bids for HVAC preventive maintenance will be received until 2:00 PM on August 21, 2026...\"","anyOf":[{"type":"string"},{"type":"null"}]},"published_at":{"type":["string","null"],"format":"date-time","description":"When the notice ran. Null when the publication date is unknown. Example: \"2026-07-15T00:00:00.000Z\"."},"publication_name":{"description":"The newspaper or journal that carried the notice. Example: \"Richmond Times-Dispatch\".","anyOf":[{"type":"string"},{"type":"null"}]},"publication_city":{"description":"The publication's city. Example: \"Richmond\". Null when unknown.","anyOf":[{"type":"string"},{"type":"null"}]},"publication_state":{"description":"The publication's state or region. Example: \"VA\". Null when unknown.","anyOf":[{"type":"string"},{"type":"null"}]},"publication_url":{"description":"A link to the notice online, when the publication offers one. Example: \"https://legals.example-times.com/notice/2026/0715/44821\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["content","published_at","publication_name","publication_city","publication_state","publication_url"],"additionalProperties":false}},"awards":{"description":"The first page of contract awards linked to this opportunity — at most 5, ordered by when Bidscope linked the award, newest link first (which is not necessarily `date_awarded` order). Empty for opportunities that have not been awarded, which is normal for open solicitations. For the full list call `opportunities.get-awards`.","type":"array","items":{"type":"object","properties":{"id":{"description":"The award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract's title as reported by the awarding source, null when the source published none. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The awarding agency's contract identifier (the federal Procurement Instrument Identifier for FPDS/SAM awards), null for sources that publish none. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_name":{"description":"Display name of the vendor that won the contract, null when the award has no linked vendor (or the linked one is suppressed). Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded. Example: \"2026-03-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the contract's period of performance. Example: \"2026-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the contract's period of performance — in the past for expired contracts. Example: \"2029-03-31T00:00:00.000Z\"."}},"required":["id","title","piid","vendor_name","award_value_cents","date_awarded","date_started","date_ended"],"additionalProperties":false}},"award_count":{"description":"The true total number of awards linked to this opportunity, not the length of `awards` — use it to decide whether fetching the rest is worthwhile. Example: 7.","type":"number"},"awards_next_cursor":{"description":"A pagination cursor — the link timestamp of the 5th embedded award — set only when `award_count` exceeds the 5 embedded here, and null otherwise. Treat it primarily as a \"there are more awards\" marker: `opportunities.get-awards` takes no cursor and simply returns the first 10 linked awards, so it already supersedes this embed. The field mirrors `solicitations_next_cursor` on `awards.get`, which does feed the `cursor` parameter of `awards.get-solicitations` in the opposite direction. Example: \"2026-03-11T14:22:07.481Z\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","status_reason","source_url","date_due","date_posted","title","solicitation_identifier","private_metadata","customers","explicit_naics_codes","explicit_psc_codes","has_external_documents","rfp_inferences","documents","crawled_rfps","public_notices","awards","award_count","awards_next_cursor"],"additionalProperties":false}},"required":["rfp"],"additionalProperties":false},"examples":[{"title":"A richly populated federal solicitation","description":"A federal IFB with a full inference: set-asides, bonds, insurance, past-performance and contract-period rules, a resolved buyer hierarchy, public attachments, and two linked awards. Note that `rfp_required_bonds[].amount_percentage` is a fraction — 0.1 means 10%.","request":{"id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30"},"response":{"rfp":{"status":"open","status_reason":null,"source_url":"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view","date_due":"2026-08-21T21:00:00.000Z","date_posted":"2026-07-14T00:00:00.000Z","title":"HVAC PREVENTIVE MAINT SVCS - DEPOT OPS","solicitation_identifier":"SPE8EH-26-R-0142","private_metadata":null,"customers":null,"explicit_naics_codes":{"code":"238220","label":"Plumbing, Heating, and Air-Conditioning Contractors"},"explicit_psc_codes":{"code":"J041","label":"Maintenance, Repair, and Rebuilding of Equipment: Refrigeration, Air Conditioning, and Air Circulating Equipment"},"has_external_documents":false,"rfp_inferences":[{"is_latest":true,"inferred_naics_codes":{"code":"238220","label":"Plumbing, Heating, and Air-Conditioning Contractors"},"inferred_psc_codes":{"code":"J041","label":"Maintenance, Repair, and Rebuilding of Equipment: Refrigeration, Air Conditioning, and Air Circulating Equipment"},"rfp_set_asides":[{"type":"Service-Disabled Veteran-Owned Business","raw":"SDVOSB Set-Aside"}],"rfp_smart_codes":[{"content":"commercial hvac maintenance"},{"content":"rooftop unit servicing"},{"content":"industrial chiller repair"}],"rfp_required_bonds":[{"type":"bid","other_type":null,"amount_percentage":null,"amount_fixed_usd_cents":1000000},{"type":"performance","other_type":null,"amount_percentage":0.1,"amount_fixed_usd_cents":null}],"inferred_rfp_contacts":[{"people":{"id":"5d2e9a71-3c48-4f60-b1a9-8e7f2c0d4a63","full_name":"Dana Whitfield","email_address":"dana.whitfield@example-agency.gov","phone_number":"+1 202-555-0143","places":{"pretty_name":"Richmond, Virginia, USA"}}}],"inferred_rfp_raw_buyers":[{"raw_buyers":{"buyer_tiers":{"id":"7a1c4e08-62b9-4d37-8f50-2b6e9c3a1d54","name_pretty":"Defense Logistics Agency","name_pretty_hierarchy":"United States of America > Department of Defense > Defense Logistics Agency","parent_buyer_tier_id":"c93f5b27-8a10-4e6d-b4f2-1d80a7c56e39","buyer_roots":{"root_type":"federal","is_coop":false}}}}],"rfp_recompete_estimates":[{"estimated_recompeted_at":"2027-09-30T00:00:00.000Z","period_index":0},{"estimated_recompeted_at":"2028-09-30T00:00:00.000Z","period_index":1}],"title":"Commercial HVAC Preventive Maintenance Services","blurb":"The Defense Logistics Agency seeks a contractor to provide scheduled preventive maintenance for commercial HVAC systems across three depots.","description":"The agency requires quarterly preventive maintenance on approximately 120 rooftop units, six centrifugal chillers, and associated air-handling equipment at three depot locations. The contractor supplies all labor, tools, filters, belts, and refrigerant, and must respond to emergency service calls within four hours. Work is performed on government premises during normal duty hours, with occasional weekend outages coordinated in advance.","milestones":[{"label":"Pre-Bid Site Visit","date":"2026-08-04","meeting":{"is_required":true,"physical_location_address":"1200 Depot Road, Richmond, VA 23297","physical_location_details":"Building 4, visitor gate","virtual_meeting_url":null,"virtual_meeting_joining_information":null}},{"label":"Questions Due Date","date":"2026-08-08","meeting":null},{"label":"Close Date","date":"2026-08-21","meeting":null}],"type":"Invitation for/to Bid (IFB/ITB)","other_type":null,"level":"Federal","in_person":true,"top_clearance":"Secret","max_education_required":"High school diploma or equivalent (e.g., GED)","insurance_required":true,"rfp_insurance_coverages":[{"type":"General Liability","minimum_limit_usd_cents":100000000},{"type":"Workers Compensation","minimum_limit_usd_cents":null}],"past_performance_strictness":"scored","past_performance_minimum_count":3,"past_performance_recency_years":5,"past_performance_minimum_project_value_usd_cents":50000000,"past_performance_contact_required":true,"local_preference_level":null,"local_preference_raw":null,"local_preference_radius_mi":null,"local_preference_place":null,"contract_period_months":[12,12,12,12,12],"contract_period_raw_text":"one (1) base year with four (4) one-year renewal options","is_supply":false,"is_service":true,"national_stock_numbers":null,"cage_codes":null,"is_off_the_shelf":null,"explicit_budget_or_award_amount_min_usd_cents":250000000,"explicit_budget_or_award_amount_max_usd_cents":400000000,"submission_information_type":"online","submission_information_other_type":null,"submission_information_email_address":null,"submission_information_mail_address":null,"submission_information_online_portal_url":"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view","submission_information_extra_instructions":"Upload the pricing worksheet as a separate unlocked spreadsheet; offers are due by 5:00 PM Eastern.","document_download_instructions":null,"places":{"pretty_name":"Richmond, Virginia, USA","region":"Virginia","country":"United States","data":{"geometry":{"coordinates":[-77.436,37.541]},"bbox":[-77.6,37.4,-77.3,37.65]}},"place_seo_lists":{"slug":"virginia"}}],"documents":[{"removed_at":null,"title":"Attachment A - Statement of Work.pdf","date_posted":"2026-07-14T00:00:00.000Z","is_private":false,"filename":"attachment-a-sow.pdf","stored_documents":{"key":"rfps/3f8a1c42/attachment-a-sow.pdf","is_in_supabase":true},"key":"rfps/3f8a1c42/attachment-a-sow.pdf"},{"removed_at":null,"title":"Amendment 0001 - Revised Equipment Schedule.pdf","date_posted":"2026-07-16T00:00:00.000Z","is_private":false,"filename":"amendment-0001.pdf","stored_documents":{"key":"rfps/3f8a1c42/amendment-0001.pdf","is_in_supabase":true},"key":"rfps/3f8a1c42/amendment-0001.pdf"}],"crawled_rfps":[{"source":"sam-dot-gov","source_url":"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view","title":"HVAC PREVENTIVE MAINT SVCS - DEPOT OPS","solicitation_identifier":"SPE8EH-26-R-0142"}],"public_notices":[],"awards":[{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Facility HVAC Maintenance Services","piid":"47QRAA24D008K","vendor_name":"Northwind Facility Services LLC","award_value_cents":128450000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2026-04-01T00:00:00.000Z","date_ended":"2029-03-31T00:00:00.000Z"},{"id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","title":"Facility HVAC Maintenance Services - Option Year One","piid":"47QRAA24D008K-0001","vendor_name":"Northwind Facility Services LLC","award_value_cents":41200000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2029-04-01T00:00:00.000Z","date_ended":"2030-03-31T00:00:00.000Z"}],"award_count":2,"awards_next_cursor":null}}},{"title":"A sparse local solicitation","description":"A small city bid carried only in a newspaper legal notice. The inference exists but most of its fields are null, because the AI records a value only on explicit evidence rather than guessing. There are no stored attachments (`has_external_documents` is true and `document_download_instructions` explains where to get them) and no awards yet.","request":{"id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68"},"response":{"rfp":{"status":"open","status_reason":null,"source_url":"https://www.planetbids.com/portal/12345/bo/bo-detail/98765","date_due":"2026-09-02T19:00:00.000Z","date_posted":null,"title":"Annual Sidewalk Repair Program","solicitation_identifier":"IFB 2026-014","private_metadata":null,"customers":null,"explicit_naics_codes":null,"explicit_psc_codes":null,"has_external_documents":true,"rfp_inferences":[{"is_latest":true,"inferred_naics_codes":{"code":"238990","label":"All Other Specialty Trade Contractors"},"inferred_psc_codes":null,"rfp_set_asides":[],"rfp_smart_codes":[{"content":"concrete sidewalk repair"},{"content":"curb and gutter replacement"},{"content":"ada ramp installation"}],"rfp_required_bonds":[],"inferred_rfp_contacts":[],"inferred_rfp_raw_buyers":[{"raw_buyers":{"buyer_tiers":{"id":"e40a8c62-1f95-4b73-a2d6-5c8e0b4f7139","name_pretty":"City of Fairhaven","name_pretty_hierarchy":"City of Fairhaven","parent_buyer_tier_id":null,"buyer_roots":{"root_type":"city","is_coop":false}}}}],"rfp_recompete_estimates":[],"title":"Annual Sidewalk Repair Program","blurb":"The City of Fairhaven is soliciting bids for its annual program of concrete sidewalk, curb, and ADA ramp repairs.","description":"The city seeks a licensed contractor to remove and replace deteriorated sidewalk panels, curbs, and gutters at locations identified by the Public Works Department, and to bring pedestrian ramps into compliance with current accessibility standards. Quantities are approximate and work is ordered by task.","milestones":[],"type":"Invitation for/to Bid (IFB/ITB)","other_type":null,"level":"Local","in_person":null,"top_clearance":null,"max_education_required":null,"insurance_required":null,"rfp_insurance_coverages":[],"past_performance_strictness":null,"past_performance_minimum_count":null,"past_performance_recency_years":null,"past_performance_minimum_project_value_usd_cents":null,"past_performance_contact_required":null,"local_preference_level":null,"local_preference_raw":null,"local_preference_radius_mi":null,"local_preference_place":null,"contract_period_months":null,"contract_period_raw_text":null,"is_supply":null,"is_service":true,"national_stock_numbers":null,"cage_codes":null,"is_off_the_shelf":null,"explicit_budget_or_award_amount_min_usd_cents":null,"explicit_budget_or_award_amount_max_usd_cents":null,"submission_information_type":null,"submission_information_other_type":null,"submission_information_email_address":null,"submission_information_mail_address":null,"submission_information_online_portal_url":null,"submission_information_extra_instructions":null,"document_download_instructions":{"url":"https://example-city.gov/purchasing/bids","site_name":"City of Fairhaven Vendor Portal","phone_number":"+1 217-555-0198","person_name":"Marcus Ellery","person_title":"Senior Procurement Officer","email_address":"purchasing@example-city.gov","address":"500 Main Street, Room 210, Fairhaven, IL 62701","location_name":"City Hall Purchasing Counter"},"places":null,"place_seo_lists":null}],"documents":[],"crawled_rfps":[{"source":"planet-bids","source_url":"https://www.planetbids.com/portal/12345/bo/bo-detail/98765","title":"Annual Sidewalk Repair Program","solicitation_identifier":"IFB 2026-014"}],"public_notices":[{"content":"NOTICE TO BIDDERS: Sealed bids for the Annual Sidewalk Repair Program, IFB 2026-014, will be received by the City of Fairhaven until 2:00 PM local time on September 2, 2026, at which time they will be publicly opened and read aloud.","published_at":"2026-08-05T00:00:00.000Z","publication_name":"Fairhaven Daily Register","publication_city":"Fairhaven","publication_state":"IL","publication_url":"https://legals.example-register.com/notice/2026/0805/44821"}],"awards":[],"award_count":0,"awards_next_cursor":null}}}]},{"version":"2026-08-20","description":"The complete details record for one opportunity. Everything outside `rfp.rfp_inferences` is sourced verbatim from the buyer or portal — status, dates, titles, identifiers, published classification codes, attachments, per-source records, and legal notices. Everything inside `rfp.rfp_inferences` is AI-extracted from the solicitation text and its documents: the cleaned title and description, set-asides, smart codes, bonds and insurance, past-performance and local-preference rules, contract periods, submission mechanics, place of performance, buyer hierarchy, and contacts. Only the latest inference is returned, so `rfp_inferences` holds exactly one element once the opportunity has been processed and is empty before that. Up to 5 linked contract awards are embedded in `rfp.awards`, newest link first, with `rfp.award_count` giving the true total; `rfp.awards_next_cursor` is set when more than 5 exist, but `opportunities.get-awards` takes no cursor and returns the first 10 linked awards directly, so treat the cursor as a \"there are more\" marker (its mirror image, `awards.get`'s `solicitations_next_cursor`, does feed `awards.get-solicitations`). Opportunities private to an organization are visible only to that organization's tokens. Returns 404 when the opportunity does not exist or is private to another organization.","plans":["free","starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The opportunity's Bidscope id (`rfps.id`, as returned by `opportunities.search` as `\"rfps.id\"`). Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rfp":{"type":"object","properties":{"status":{"description":"Whether the opportunity is still accepting bids: \"open\" or \"closed\". Example: \"open\".","anyOf":[{"type":"string"},{"type":"null"}]},"status_reason":{"description":"A one-to-three-word explanation of why the opportunity is closed — the source's own wording, or one Bidscope assigns: \"past due\" (the deadline passed), \"expired\" (no deadline, but too old), or \"pruned\" (retired by an administrator). Always null while the opportunity is open. Example: \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"source_url":{"description":"The canonical link to the opportunity on the buyer's or portal's own site. When several sources describe the same opportunity, this is the winning one; per-source links are in `crawled_rfps`. Example: \"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view\".","anyOf":[{"type":"string"},{"type":"null"}]},"date_due":{"type":["string","null"],"format":"date-time","description":"The bid submission deadline. Null when the source published no deadline (common on Sources Sought and Award Notices). Example: \"2026-08-21T21:00:00.000Z\"."},"date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer published the solicitation — not when Bidscope first saw it. Null when the source published no date. Example: \"2026-07-14T00:00:00.000Z\"."},"title":{"description":"The opportunity's title exactly as the source published it, unedited. For a cleaned-up version see `rfp_inferences[0].title`. Example: \"HVAC PREVENTIVE MAINT SVCS - DEPOT OPS\". Null when the source published no title.","anyOf":[{"type":"string"},{"type":"null"}]},"solicitation_identifier":{"description":"The buyer's own reference number for the solicitation, as published. Null when the source publishes none. Example: \"SPE8EH-26-R-0142\".","anyOf":[{"type":"string"},{"type":"null"}]},"private_metadata":{"description":"Extra metadata carried on opportunities that are private to a single organization. In practice the only key is `type`, marking the private channel the opportunity arrived through. Null for ordinary public opportunities, which is the overwhelming majority. Example: { \"type\": \"ebuy\" }.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"explicit_naics_codes":{"description":"The NAICS code the source itself published for this opportunity, verbatim rather than inferred. Null when the source published none — which is normal outside federal portals. For Bidscope's own classification see `rfp_inferences[].inferred_naics_codes`.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"explicit_psc_codes":{"description":"The PSC/FSC code the source itself published, verbatim rather than inferred. Null when the source published none. For Bidscope's own classification see `rfp_inferences[].inferred_psc_codes`.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"has_external_documents":{"description":"True when the source links to solicitation attachments that Bidscope could not download itself — typically because they sit behind a registration or login wall, or are not fetchable files. Set by the collector, not by the AI, and sticky across merges: once any source reports external documents it stays true. When this is true, follow `source_url` or `rfp_inferences[].document_download_instructions` to obtain the rest of the package. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfp_inferences":{"description":"The AI-extracted view of the opportunity. Filtered to the latest inference only, so this array holds exactly one element for any opportunity that has been processed, and is empty for one that has not been (or whose inference was superseded and not yet replaced). Everything in here is model output derived from the solicitation text and its documents; everything outside it is sourced verbatim.","type":"array","items":{"type":"object","properties":{"is_latest":{"description":"Whether this is the current inference for the opportunity. The query filters on `is_latest = true`, so in this response it is always true — superseded inferences are never returned. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"inferred_naics_codes":{"description":"The single NAICS code the AI judged to best classify the work, chosen even when the buyer published none. Compare with the top-level `explicit_naics_codes`, which is the code the source itself published. Null when the model could not pick one with confidence.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"inferred_psc_codes":{"description":"The single PSC/FSC (Product and Service Code) the AI judged to best classify the work. Compare with the top-level `explicit_psc_codes`, which the source published. Null when the model could not pick one with confidence.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself. NAICS codes are 6 digits; PSC/FSC codes are 4 characters (a letter-prefixed service code or a numeric product code). Example: \"541519\".","type":"string"},"label":{"description":"The official title of the code, from Bidscope's `naics_codes` / `psc_codes` reference tables. Null only when the reference row has no label. Example: \"Other Computer Related Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"rfp_set_asides":{"description":"Business set-aside designations the AI found stated in the solicitation. Empty when the solicitation states none or the language was too unclear to classify — an empty array is not a guarantee the opportunity is unrestricted.","type":"array","items":{"type":"object","properties":{"type":{"description":"The set-aside normalized to one of Bidscope's canonical categories: \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Native-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\", or \"Other\" when none of the above fit. Example: \"Service-Disabled Veteran-Owned Business\".","type":"string"},"raw":{"description":"The set-aside's name as written in the solicitation (lightly formatting-corrected), preserved because each buyer uses its own program names and acronyms. Use this to look the program up on the buyer's own site. Example: \"SDVOSB Set-Aside\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","raw"],"additionalProperties":false}},"rfp_smart_codes":{"description":"Exactly three AI-generated capability tags summarizing what the opportunity actually asks for, used by Bidscope to score fit against a vendor's own smart codes. Empty only when the inference predates smart-code generation or generation failed.","type":"array","items":{"type":"object","properties":{"content":{"description":"The smart code phrase: at most four human-readable words, lowercased, more specific than an industry (\"construction\") but less specific than a SKU (\"8ft red ladder\"), and free of set-aside or quality language. Example: \"sidewalk construction\".","type":"string"}},"required":["content"],"additionalProperties":false}},"rfp_required_bonds":{"description":"Surety bonds the solicitation requires bidders to post (common on construction work). Empty when the solicitation mentions no bonds; bonds stated with a zero amount are dropped.","type":"array","items":{"type":"object","properties":{"type":{"description":"The kind of surety bond required. One of \"bid\", \"payment\", \"performance\", or \"other\". Example: \"performance\".","type":"string"},"other_type":{"description":"The bond's name when `type` is \"other\"; null for the three named types. Example: \"Maintenance Bond\".","anyOf":[{"type":"string"},{"type":"null"}]},"amount_percentage":{"description":"The bond amount expressed as a FRACTION of the contract or bid value, not a percent number — a solicitation demanding 10% is stored as 0.1. Null when the bond is stated as a flat amount (then `amount_fixed_usd_cents` is set) or no amount was given. Example: 0.1.","anyOf":[{"type":"number"},{"type":"null"}]},"amount_fixed_usd_cents":{"description":"The bond amount as a flat sum in integer USD cents. Null when the bond is stated as a percentage or no amount was given; the two amount fields are never both set. Example: 1000000 (i.e. $10,000.00).","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","other_type","amount_percentage","amount_fixed_usd_cents"],"additionalProperties":false}},"inferred_rfp_contacts":{"description":"Buyer-side points of contact the AI extracted from the solicitation and its documents, deduplicated into Bidscope's `people` table. Empty when the solicitation published no contact details. These are procurement contacts for the opportunity, not vendor contacts.","type":"array","items":{"type":"object","properties":{"people":{"description":"The person record this contact points at. Null when the linked person row has been removed or suppressed.","anyOf":[{"type":"object","properties":{"id":{"description":"The contact's Bidscope person id (`people.id`), stable across solicitations once the person is consolidated. Absent on older cached inferences. Example: \"5d2e9a71-3c48-4f60-b1a9-8e7f2c0d4a63\".","anyOf":[{"type":"string"},{"type":"null"}]},"full_name":{"description":"The contact's name as published by the buyer. Null when the solicitation gave only an email or phone. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"The contact's email address, null when none was published. Example: \"dana.whitfield@example-agency.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"description":"The contact's phone number, in whatever format the buyer published. Null when none was published. Example: \"+1 202-555-0143\".","anyOf":[{"type":"string"},{"type":"null"}]},"places":{"description":"The contact's location, geocoded from any address published alongside them. Null when no address was published or geocoding failed.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"Display name of the contact's geocoded location. Example: \"Arlington, Virginia, USA\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["pretty_name"],"additionalProperties":false},{"type":"null"}]}},"required":["full_name","email_address","phone_number","places"],"additionalProperties":false},{"type":"null"}]}},"required":["people"],"additionalProperties":false}},"inferred_rfp_raw_buyers":{"description":"The buying organization(s) behind the opportunity. Usually one entry. Empty when no buyer could be extracted from the source.","type":"array","items":{"type":"object","properties":{"raw_buyers":{"description":"The per-solicitation raw buyer record the AI extracted, and its link into the consolidated buyer hierarchy. Null when the raw buyer row has been removed.","anyOf":[{"type":"object","properties":{"buyer_tiers":{"description":"The consolidated buyer tier this raw buyer resolved to. Null while consolidation is still pending — raw buyers are recorded per solicitation and matched to the canonical hierarchy asynchronously, so a freshly crawled opportunity can have a raw buyer with no tier yet.","anyOf":[{"type":"object","properties":{"id":{"description":"The consolidated buyer tier's id (`buyer_tiers.id`), usable with the `buyers` endpoints. Example: \"7a1c4e08-62b9-4d37-8f50-2b6e9c3a1d54\".","type":"string"},"name_pretty":{"description":"Display name of this tier alone, without its ancestors. Example: \"Defense Logistics Agency\".","anyOf":[{"type":"string"},{"type":"null"}]},"name_pretty_hierarchy":{"description":"The tier's full path from the root organization down to itself, useful as a one-line buyer label. Absent on older cached inferences. Example: \"United States of America > Department of Defense > Defense Logistics Agency\".","anyOf":[{"type":"string"},{"type":"null"}]},"parent_buyer_tier_id":{"description":"The id of this tier's parent in the buyer hierarchy; null when this tier is itself the root organization. Example: \"c93f5b27-8a10-4e6d-b4f2-1d80a7c56e39\".","anyOf":[{"type":"string"},{"type":"null"}]},"buyer_roots":{"description":"Attributes of the root organization this tier descends from. Null when the tier has not been attached to a root yet.","anyOf":[{"type":"object","properties":{"root_type":{"description":"What kind of organization sits at the root of this buyer's hierarchy. One of \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", or \"private\". Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_coop":{"description":"True when the root is a purchasing group or cooperative rather than a single entity — a cooperative of California school districts would be `root_type: \"k12\"` with `is_coop: true`. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["root_type","is_coop"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name_pretty","parent_buyer_tier_id","buyer_roots"],"additionalProperties":false},{"type":"null"}]}},"required":["buyer_tiers"],"additionalProperties":false},{"type":"null"}]}},"required":["raw_buyers"],"additionalProperties":false}},"rfp_recompete_estimates":{"description":"Projected recompete dates, derived arithmetically from `contract_period_months` plus a contract start anchor — not read from the solicitation. Empty when the contract period is unknown or implausible. These are estimates for pipeline planning, not announced dates.","type":"array","items":{"type":"object","properties":{"estimated_recompeted_at":{"description":"Estimated date this contract period ends and the work could come up for bid again, as an ISO 8601 timestamp. Computed as the contract start anchor plus the cumulative length of every period up to and including `period_index`. Null when no anchor date could be established. Example: \"2029-09-30T00:00:00.000Z\".","anyOf":[{"type":"string"},{"type":"null"}]},"period_index":{"description":"Zero-based index into `contract_period_months` identifying which period this estimate is the end of: 0 is the end of the base period, 1 the end of the first option period, and so on. Example: 0.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["estimated_recompeted_at","period_index"],"additionalProperties":false}},"title":{"description":"An AI-cleaned, human-readable title describing what is being requested. Often clearer than the source's own `rfp.title`, which is preserved verbatim at the top level. Example: \"Commercial HVAC Preventive Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"blurb":{"description":"A one-sentence at-a-glance summary of what is requested and by whom, suitable for a list row. Example: \"The Defense Logistics Agency seeks a contractor to provide scheduled preventive maintenance for commercial HVAC systems across three depots.\"","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"One to three AI-written paragraphs summarizing the opportunity in enough detail for a vendor to judge fit. Deliberately excludes contact details and location (those have their own fields) and never names the source portal. Synthesized from the solicitation and its attached documents. Example: \"The agency requires quarterly preventive maintenance on approximately 120 rooftop units...\"","anyOf":[{"type":"string"},{"type":"null"}]},"milestones":{"description":"A JSON array of key dates extracted from the solicitation. Each item is `{ label, date, meeting }`: `label` is free text naming the milestone (there is no fixed enum — e.g. \"Pre-Bid Meeting\", \"Questions Due Date\", \"Close Date\"), `date` is the milestone date, and `meeting` is null unless the milestone is attendable, in which case it is `{ is_required, physical_location_address, physical_location_details, virtual_meeting_url, virtual_meeting_joining_information }`. Empty array when the solicitation states no dated events. Example: [{ \"label\": \"Pre-Bid Site Visit\", \"date\": \"2026-08-04\", \"meeting\": { \"is_required\": true, \"physical_location_address\": \"1200 Depot Road, Richmond, VA 23297\", \"physical_location_details\": \"Building 4, visitor gate\", \"virtual_meeting_url\": null, \"virtual_meeting_joining_information\": null } }]."},"type":{"description":"The kind of solicitation, normalized to one of \"Request for Proposal (RFP)\", \"Request for Quote/Qualifications (RFQ)\", \"Request for Information (RFI)\", \"Invitation for/to Bid (IFB/ITB)\", \"Sources Sought\", \"Sole Source\", \"Sale\" (the agency is selling goods or assets), \"Award Notice\", \"Event\", \"Grant\", or \"Other\". Example: \"Invitation for/to Bid (IFB/ITB)\".","anyOf":[{"type":"string"},{"type":"null"}]},"other_type":{"description":"A free-text solicitation type used when `type` is \"Other\"; null otherwise. Example: \"Prequalification Application\".","anyOf":[{"type":"string"},{"type":"null"}]},"level":{"description":"The level of government issuing the opportunity: \"Federal\", \"State\", \"Local\", or \"Private\". Example: \"Federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"in_person":{"description":"True when the solicitation explicitly states the work must be performed on site, false when it explicitly allows remote performance. Null when the solicitation is silent, or for goods-only purchases — it is never guessed from the industry or location. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"top_clearance":{"description":"The highest security clearance the solicitation explicitly requires (federal work only). One of \"Confidential\", \"Secret\", \"Top Secret\", \"TS/SCI\", \"TS/SAP\", \"Public Trust\", \"DOE Q\", \"DOE L\", or \"NATO Secret / TS\". Null when no clearance is required or none is stated — there is no explicit \"None\" value. Example: \"Secret\".","anyOf":[{"type":"string"},{"type":"null"}]},"max_education_required":{"description":"The highest education level explicitly required across all staffed positions (a role mix of two bachelor's and one PhD yields the doctorate value). One of \"Primary/elementary school\", \"Some high school (no diploma)\", \"High school diploma or equivalent (e.g., GED)\", \"Some college (no degree)\", \"Trade/vocational/technical training\", \"Associate degree\", \"Bachelor's degree\", \"Master's degree\", \"Professional degree (e.g., MD, JD)\", or \"Doctorate (PhD, EdD, etc.)\". Null when no education requirement is stated. Example: \"Bachelor's degree\".","anyOf":[{"type":"string"},{"type":"null"}]},"insurance_required":{"description":"True when the solicitation mandates any insurance coverage, false when it explicitly says none is required, null when insurance is never mentioned. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"rfp_insurance_coverages":{"description":"The specific insurance coverages the solicitation requires. Empty when `insurance_required` is false or insurance is never mentioned.","type":"array","items":{"type":"object","properties":{"type":{"description":"The coverage name as stated. Free text, not an enum — common values are \"General Liability\", \"Workers Compensation\", \"Auto Liability\", \"Professional Liability\", and \"Cyber Liability\". Example: \"General Liability\".","type":"string"},"minimum_limit_usd_cents":{"description":"The minimum per-occurrence (or equivalent) limit in integer USD cents. Null when the solicitation gives no figure or says only \"statutory\". Example: 100000000 (i.e. $1,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","minimum_limit_usd_cents"],"additionalProperties":false}},"past_performance_strictness":{"description":"How past-performance references are used in the award decision: \"required\" (a hard responsibility gate — too little qualifying past performance makes a bid non-responsive), \"scored\" (contributes points to the evaluation), or \"informational\" (collected but not formally rated). Null when past performance is not mentioned. Example: \"scored\".","anyOf":[{"type":"string"},{"type":"null"}]},"past_performance_minimum_count":{"description":"How many prior projects or references the bidder must supply. Null when past performance is not mentioned or no count is given. Example: 3.","anyOf":[{"type":"number"},{"type":"null"}]},"past_performance_recency_years":{"description":"How recently a prior project must have been performed to count, in years. Null when no recency window is stated. Example: 5.","anyOf":[{"type":"number"},{"type":"null"}]},"past_performance_minimum_project_value_usd_cents":{"description":"The minimum size a prior project must have been to count as relevant past performance, in integer USD cents. When the solicitation states several tiers, the largest is used. Null when no dollar threshold is stated. Example: 50000000 (i.e. $500,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"past_performance_contact_required":{"description":"True when each reference must include a reachable client point of contact (a name plus a phone number or email). Null when past performance is not mentioned. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"local_preference_level":{"description":"How strongly the buyer favors local vendors, taken from the most stringent statement in the solicitation: \"required\" (local vendors are mandated), \"preferred\" (local vendors get a scoring or evaluation advantage), or \"encouraged-to-apply\" (softer explicit encouragement). Null unless explicit local-vendor language appears — it is never inferred from the buyer's own location. Example: \"preferred\".","anyOf":[{"type":"string"},{"type":"null"}]},"local_preference_raw":{"description":"The passage from the solicitation that establishes the local preference, quoted verbatim, so a bidder can verify the classification. Null when `local_preference_level` is null. Example: \"Bidders whose principal place of business lies within Mecklenburg County shall receive a five percent evaluation preference.\"","anyOf":[{"type":"string"},{"type":"null"}]},"local_preference_radius_mi":{"description":"The radius in miles when the preference is expressed as a distance (\"within 150 miles of Charlotte\"). Null when the preference names a jurisdiction rather than a distance, or when there is no preference. Example: 150.","anyOf":[{"type":"number"},{"type":"null"}]},"local_preference_place":{"description":"The geographic area the local preference applies to, geocoded from the place named in the solicitation. Null when there is no local preference or the named place could not be geocoded.","anyOf":[{"type":"object","properties":{"bbox":{"description":"The place's GeoJSON bounding box as [minLng, minLat, maxLng, maxLat], usable to test whether a vendor's address falls inside the preference area. Null when the geocoded place carries no bounding box. Example: [-81.06, 35.0, -80.55, 35.4].","anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]}},"required":["bbox"],"additionalProperties":false},{"type":"null"}]},"contract_period_months":{"description":"The contract's periods, in months, first entry being the base period and the rest option periods in order. \"Three-year base with two one-year options\" becomes [36, 12, 12]; \"base year plus four option years\" becomes [12, 12, 12, 12, 12]. Null when the solicitation does not state a contract length — it is never guessed. Example: [12, 12, 12, 12, 12].","anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]},"contract_period_raw_text":{"description":"The phrase from the solicitation that `contract_period_months` was derived from, quoted verbatim so the parse can be checked. Null when no contract length is stated. Example: \"one (1) base year with four (4) one-year renewal options\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_supply":{"description":"True when goods, products, or software must be supplied on award. Null when the solicitation is ambiguous about it. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"is_service":{"description":"True when a service must be rendered — professional services, staffing, or installation. Delivery or shipping alone does not count as a service, but installation does, so a supply-and-install contract is both `is_supply` and `is_service`. Null when ambiguous. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"can_middleman":{"description":"True when the work could be fulfilled by a reseller or broker sourcing it from someone else, rather than requiring the bidder to perform or manufacture it directly. Null when there is not enough information. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"national_stock_numbers":{"description":"National Stock Numbers explicitly cited in the solicitation, normalized to bare 13-digit strings (the conventional NSN display form is XXXX-XX-XXX-XXXX). Never inferred. Null when none are cited. Example: [\"5340015551234\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"cage_codes":{"description":"CAGE (Commercial and Government Entity) codes written out in the solicitation, uppercased — five alphanumeric characters beginning and ending with a digit. Never inferred from a company name. Null when none appear. Example: [\"1A2B3\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"is_off_the_shelf":{"description":"When a product is being supplied, true if it is a commercially available off-the-shelf item (including a configured instance of one) and false if it must be custom built. Null when no product is involved or there is not enough information. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"explicit_budget_or_award_amount_min_usd_cents":{"description":"The low end of the total budget or award amount the solicitation states, in integer USD cents. Equals the max when a single figure is given. Only ever a total contract or budget value — never a unit price or hourly rate. Null when no total is stated. Example: 250000000 (i.e. $2,500,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"explicit_budget_or_award_amount_max_usd_cents":{"description":"The high end of the stated total budget or award amount, in integer USD cents. Null when no total is stated; the min and max are always both set or both null. Example: 400000000 (i.e. $4,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"submission_methods":{"description":"Every way this solicitation accepts a bid, in the order the model judged most to least preferred — so the first entry is the one to use when only one method is wanted. Null when the solicitation states no submission method, and also null for solicitations last inferred before Bidscope extracted methods as a list (their single-method data was not carried forward).","anyOf":[{"type":"array","items":{"type":"object","properties":{"type":{"description":"How bids are submitted by this method: \"email\", \"mail\", \"online\", or \"other\". Example: \"online\".","type":"string"},"other_type":{"description":"A free-text description of the method when `type` is \"other\"; null otherwise. Example: \"Hand delivery to the Purchasing counter\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"The address bids are emailed to. Normally populated when the type is \"email\"; null otherwise. Example: \"bids@example-agency.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"mail_address":{"description":"The postal address bids are mailed to. Normally populated when the type is \"mail\"; null otherwise. Example: \"Purchasing Division, 500 Main Street, Room 210, Springfield, IL 62701\".","anyOf":[{"type":"string"},{"type":"null"}]},"online_portal_url":{"description":"The portal URL bids are submitted through, only when the solicitation states it explicitly — it is never guessed, so this can be null even when the type is \"online\". Example: \"https://sam.gov/opp/example/view\".","anyOf":[{"type":"string"},{"type":"null"}]},"extra_instructions":{"description":"One or two sentences of concrete submission mechanics for this method that the other fields do not cover — copy counts, required file formats, envelope or subject-line labeling, a specific deadline time. Deliberately excludes evaluation criteria, award process, and reservation-of-rights language. Null when there is nothing to add. Example: \"Submit one original and three bound copies in a sealed envelope marked with the solicitation number; late bids are not accepted after 2:00 PM local time.\"","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","other_type","email_address","mail_address","online_portal_url","extra_instructions"],"additionalProperties":false}},{"type":"null"}]},"document_download_instructions":{"description":"How a vendor obtains the solicitation package (scope of work, addenda, bid sheets) when Bidscope could not host the files itself — extracted only from explicit text, with every sub-field independently nullable. Null when the solicitation says nothing about it. Most useful when `documents` is empty and `has_external_documents` is true.","anyOf":[{"type":"object","properties":{"url":{"description":"The web address where the solicitation documents can be obtained. Example: \"https://example-agency.gov/purchasing/bids\".","anyOf":[{"type":"string"},{"type":"null"}]},"site_name":{"description":"The name of the site or portal hosting the documents. Example: \"City of Springfield Vendor Portal\".","anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"description":"A phone number to call to request the documents. Example: \"+1 217-555-0198\".","anyOf":[{"type":"string"},{"type":"null"}]},"person_name":{"description":"The person to contact for the documents. Example: \"Marcus Ellery\".","anyOf":[{"type":"string"},{"type":"null"}]},"person_title":{"description":"That person's job title. Example: \"Senior Procurement Officer\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"An email address to write to for the documents. Example: \"purchasing@example-city.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"address":{"description":"A physical address where documents may be picked up. Example: \"500 Main Street, Room 210, Springfield, IL 62701\".","anyOf":[{"type":"string"},{"type":"null"}]},"location_name":{"description":"The name of that pickup location. Example: \"City Hall Purchasing Counter\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["url","site_name","phone_number","person_name","person_title","email_address","address","location_name"],"additionalProperties":false},{"type":"null"}]},"places":{"description":"Where the work will be performed, geocoded from the location the AI extracted from the solicitation. Null when no place of performance could be determined.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"Display name of the place of performance. Example: \"Richmond, Virginia, USA\".","anyOf":[{"type":"string"},{"type":"null"}]},"region":{"description":"The first-level administrative region — a state for US places. Example: \"Virginia\".","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"The country name. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"data":{"description":"The raw geocoder payload for the place. Chiefly useful for `geometry.coordinates` ([longitude, latitude]) and `bbox` ([minLng, minLat, maxLng, maxLat]). Example: { \"geometry\": { \"coordinates\": [-77.436, 37.541] }, \"bbox\": [-77.6, 37.4, -77.3, 37.65] }."}},"required":["pretty_name","region","country","data"],"additionalProperties":false},{"type":"null"}]},"place_seo_lists":{"description":"The nearest place-based Bidscope listing page to the place of performance, matched within 100 miles (160,934 metres) of the list's own point. Null when no list falls within that radius or the place of performance is unknown.","anyOf":[{"type":"object","properties":{"slug":{"description":"The list's URL slug, forming the path `/list/<slug>` on bidscope.ai. Example: \"virginia\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["slug"],"additionalProperties":false},{"type":"null"}]}},"required":["is_latest","inferred_naics_codes","inferred_psc_codes","rfp_set_asides","rfp_smart_codes","rfp_required_bonds","inferred_rfp_contacts","inferred_rfp_raw_buyers","rfp_recompete_estimates","title","blurb","description","milestones","type","other_type","level","in_person","top_clearance","max_education_required","insurance_required","rfp_insurance_coverages","past_performance_strictness","past_performance_minimum_count","past_performance_recency_years","past_performance_minimum_project_value_usd_cents","past_performance_contact_required","local_preference_level","local_preference_raw","local_preference_radius_mi","local_preference_place","contract_period_months","contract_period_raw_text","is_supply","is_service","can_middleman","national_stock_numbers","cage_codes","is_off_the_shelf","explicit_budget_or_award_amount_min_usd_cents","explicit_budget_or_award_amount_max_usd_cents","submission_methods","document_download_instructions","places","place_seo_lists"],"additionalProperties":false}},"documents":{"description":"Public, still-current solicitation attachments. Withdrawn and restricted documents are filtered out entirely. Empty when the buyer published none, when they sit behind a login wall (see `has_external_documents`), or when Bidscope has not yet fetched them.","type":"array","items":{"type":"object","properties":{"removed_at":{"type":["string","null"],"format":"date-time","description":"When the document was withdrawn. The query excludes withdrawn documents, so this is always null in this response; it is retained for schema compatibility."},"title":{"description":"The document's display title. Example: \"Attachment A - Statement of Work.pdf\". Null when the source gave none.","anyOf":[{"type":"string"},{"type":"null"}]},"date_posted":{"type":["string","null"],"format":"date-time","description":"When the buyer posted this document, which for addenda is later than the solicitation's own `date_posted`. Null when unknown. Example: \"2026-07-16T00:00:00.000Z\"."},"is_private":{"description":"Whether the document is restricted. The query excludes restricted documents, so this is always false in this response; it is retained for schema compatibility.","anyOf":[{"type":"boolean"},{"type":"null"}]},"filename":{"description":"The original filename, useful as the `download` parameter when building a storage URL. Example: \"attachment-a-sow.pdf\".","anyOf":[{"type":"string"},{"type":"null"}]},"stored_documents":{"description":"The stored, content-addressed copy of the file. Because blobs are deduplicated by content hash, one stored document can back the same attachment across several opportunities. Null when no copy was stored, in which case only the legacy `key` or the source's own link is available.","anyOf":[{"type":"object","properties":{"key":{"description":"The authoritative object-storage key for the stored copy; prefer this over the sibling `key` when present. Example: \"rfps/3f8a1c42/attachment-a-sow.pdf\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_in_supabase":{"description":"False when the binary has been archived out of the storage bucket and can no longer be downloaded — the metadata and extracted text survive, but the file does not. Check this before building a download URL. True (or null, on older rows) when the file is still retrievable. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["key","is_in_supabase"],"additionalProperties":false},{"type":"null"}]},"key":{"description":"A legacy storage key kept on the document row itself; use it only when `stored_documents.key` is absent. Together they form the download path `<supabase-url>/storage/v1/object/public/documents/<key>`. Example: \"rfps/3f8a1c42/attachment-a-sow.pdf\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["removed_at","title","date_posted","is_private","filename","stored_documents","key"],"additionalProperties":false}},"crawled_rfps":{"description":"One record per source Bidscope found this opportunity on. Multiple entries mean the same solicitation was published in several places and merged into one Bidscope record — useful for auditing where the merged fields came from. Rarely empty.","type":"array","items":{"type":"object","properties":{"source":{"description":"The portal or collector this record came from, as a Bidscope source slug. Examples: \"sam-dot-gov\", \"planet-bids\", \"bonfire\", \"bidnet-direct\", \"grants-dot-gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"source_url":{"description":"The link to the opportunity on that particular source. Example: \"https://www.planetbids.com/portal/12345/bo/bo-detail/98765\".","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"description":"The title as that source published it, which can differ from the top-level `title` when several sources are merged. Example: \"HVAC Preventive Maintenance - Depot Operations\".","anyOf":[{"type":"string"},{"type":"null"}]},"solicitation_identifier":{"description":"The reference number as that source published it. Example: \"SPE8EH-26-R-0142\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","source_url","title","solicitation_identifier"],"additionalProperties":false}},"public_notices":{"description":"Legal advertisements for this solicitation published in newspapers of record, gathered across every source record and flattened into one list. Empty for the many opportunities that were never advertised in print, and for all federal portal opportunities.","type":"array","items":{"type":"object","properties":{"content":{"description":"The notice text as printed. Example: \"NOTICE TO BIDDERS: Sealed bids for HVAC preventive maintenance will be received until 2:00 PM on August 21, 2026...\"","anyOf":[{"type":"string"},{"type":"null"}]},"published_at":{"type":["string","null"],"format":"date-time","description":"When the notice ran. Null when the publication date is unknown. Example: \"2026-07-15T00:00:00.000Z\"."},"publication_name":{"description":"The newspaper or journal that carried the notice. Example: \"Richmond Times-Dispatch\".","anyOf":[{"type":"string"},{"type":"null"}]},"publication_city":{"description":"The publication's city. Example: \"Richmond\". Null when unknown.","anyOf":[{"type":"string"},{"type":"null"}]},"publication_state":{"description":"The publication's state or region. Example: \"VA\". Null when unknown.","anyOf":[{"type":"string"},{"type":"null"}]},"publication_url":{"description":"A link to the notice online, when the publication offers one. Example: \"https://legals.example-times.com/notice/2026/0715/44821\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["content","published_at","publication_name","publication_city","publication_state","publication_url"],"additionalProperties":false}},"awards":{"description":"The first page of contract awards linked to this opportunity — at most 5, ordered by when Bidscope linked the award, newest link first (which is not necessarily `date_awarded` order). Empty for opportunities that have not been awarded, which is normal for open solicitations. For the full list call `opportunities.get-awards`.","type":"array","items":{"type":"object","properties":{"id":{"description":"The award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract's title as reported by the awarding source, null when the source published none. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_identifier":{"description":"The awarding agency's contract identifier (the federal Procurement Instrument Identifier for FPDS/SAM awards), null for sources that publish none. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_name":{"description":"Display name of the vendor that won the contract, null when the award has no linked vendor (or the linked one is suppressed). Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded. Example: \"2026-03-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the contract's period of performance. Example: \"2026-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the contract's period of performance — in the past for expired contracts. Example: \"2029-03-31T00:00:00.000Z\"."}},"required":["id","title","award_identifier","vendor_name","award_value_cents","date_awarded","date_started","date_ended"],"additionalProperties":false}},"award_count":{"description":"The true total number of awards linked to this opportunity, not the length of `awards` — use it to decide whether fetching the rest is worthwhile. Example: 7.","type":"number"},"awards_next_cursor":{"description":"A pagination cursor — the link timestamp of the 5th embedded award — set only when `award_count` exceeds the 5 embedded here, and null otherwise. Treat it primarily as a \"there are more awards\" marker: `opportunities.get-awards` takes no cursor and simply returns the first 10 linked awards, so it already supersedes this embed. The field mirrors `solicitations_next_cursor` on `awards.get`, which does feed the `cursor` parameter of `awards.get-solicitations` in the opposite direction. Example: \"2026-03-11T14:22:07.481Z\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","status_reason","source_url","date_due","date_posted","title","solicitation_identifier","private_metadata","explicit_naics_codes","explicit_psc_codes","has_external_documents","rfp_inferences","documents","crawled_rfps","public_notices","awards","award_count","awards_next_cursor"],"additionalProperties":false}},"required":["rfp"],"additionalProperties":false},"examples":[{"title":"A richly populated federal solicitation","description":"A federal IFB with a full inference: set-asides, bonds, insurance, past-performance and contract-period rules, a resolved buyer hierarchy, public attachments, and two linked awards. Note that `rfp_required_bonds[].amount_percentage` is a fraction — 0.1 means 10%.","request":{"id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30"},"response":{"rfp":{"status":"open","status_reason":null,"source_url":"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view","date_due":"2026-08-21T21:00:00.000Z","date_posted":"2026-07-14T00:00:00.000Z","title":"HVAC PREVENTIVE MAINT SVCS - DEPOT OPS","solicitation_identifier":"SPE8EH-26-R-0142","private_metadata":null,"explicit_naics_codes":{"code":"238220","label":"Plumbing, Heating, and Air-Conditioning Contractors"},"explicit_psc_codes":{"code":"J041","label":"Maintenance, Repair, and Rebuilding of Equipment: Refrigeration, Air Conditioning, and Air Circulating Equipment"},"has_external_documents":false,"rfp_inferences":[{"is_latest":true,"inferred_naics_codes":{"code":"238220","label":"Plumbing, Heating, and Air-Conditioning Contractors"},"inferred_psc_codes":{"code":"J041","label":"Maintenance, Repair, and Rebuilding of Equipment: Refrigeration, Air Conditioning, and Air Circulating Equipment"},"rfp_set_asides":[{"type":"Service-Disabled Veteran-Owned Business","raw":"SDVOSB Set-Aside"}],"rfp_smart_codes":[{"content":"commercial hvac maintenance"},{"content":"rooftop unit servicing"},{"content":"industrial chiller repair"}],"rfp_required_bonds":[{"type":"bid","other_type":null,"amount_percentage":null,"amount_fixed_usd_cents":1000000},{"type":"performance","other_type":null,"amount_percentage":0.1,"amount_fixed_usd_cents":null}],"inferred_rfp_contacts":[{"people":{"id":"5d2e9a71-3c48-4f60-b1a9-8e7f2c0d4a63","full_name":"Dana Whitfield","email_address":"dana.whitfield@example-agency.gov","phone_number":"+1 202-555-0143","places":{"pretty_name":"Richmond, Virginia, USA"}}}],"inferred_rfp_raw_buyers":[{"raw_buyers":{"buyer_tiers":{"id":"7a1c4e08-62b9-4d37-8f50-2b6e9c3a1d54","name_pretty":"Defense Logistics Agency","name_pretty_hierarchy":"United States of America > Department of Defense > Defense Logistics Agency","parent_buyer_tier_id":"c93f5b27-8a10-4e6d-b4f2-1d80a7c56e39","buyer_roots":{"root_type":"federal","is_coop":false}}}}],"rfp_recompete_estimates":[{"estimated_recompeted_at":"2027-09-30T00:00:00.000Z","period_index":0},{"estimated_recompeted_at":"2028-09-30T00:00:00.000Z","period_index":1}],"title":"Commercial HVAC Preventive Maintenance Services","blurb":"The Defense Logistics Agency seeks a contractor to provide scheduled preventive maintenance for commercial HVAC systems across three depots.","description":"The agency requires quarterly preventive maintenance on approximately 120 rooftop units, six centrifugal chillers, and associated air-handling equipment at three depot locations. The contractor supplies all labor, tools, filters, belts, and refrigerant, and must respond to emergency service calls within four hours. Work is performed on government premises during normal duty hours, with occasional weekend outages coordinated in advance.","milestones":[{"label":"Pre-Bid Site Visit","date":"2026-08-04","meeting":{"is_required":true,"physical_location_address":"1200 Depot Road, Richmond, VA 23297","physical_location_details":"Building 4, visitor gate","virtual_meeting_url":null,"virtual_meeting_joining_information":null}},{"label":"Questions Due Date","date":"2026-08-08","meeting":null},{"label":"Close Date","date":"2026-08-21","meeting":null}],"type":"Invitation for/to Bid (IFB/ITB)","other_type":null,"level":"Federal","in_person":true,"top_clearance":"Secret","max_education_required":"High school diploma or equivalent (e.g., GED)","insurance_required":true,"rfp_insurance_coverages":[{"type":"General Liability","minimum_limit_usd_cents":100000000},{"type":"Workers Compensation","minimum_limit_usd_cents":null}],"past_performance_strictness":"scored","past_performance_minimum_count":3,"past_performance_recency_years":5,"past_performance_minimum_project_value_usd_cents":50000000,"past_performance_contact_required":true,"local_preference_level":null,"local_preference_raw":null,"local_preference_radius_mi":null,"local_preference_place":null,"contract_period_months":[12,12,12,12,12],"contract_period_raw_text":"one (1) base year with four (4) one-year renewal options","is_supply":false,"is_service":true,"can_middleman":false,"national_stock_numbers":null,"cage_codes":null,"is_off_the_shelf":null,"explicit_budget_or_award_amount_min_usd_cents":250000000,"explicit_budget_or_award_amount_max_usd_cents":400000000,"submission_methods":[{"type":"online","other_type":null,"email_address":null,"mail_address":null,"online_portal_url":"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view","extra_instructions":"Upload the pricing worksheet as a separate unlocked spreadsheet; offers are due by 5:00 PM Eastern."},{"type":"email","other_type":null,"email_address":"contracting@example-agency.gov","mail_address":null,"online_portal_url":null,"extra_instructions":"Emailed offers must carry the solicitation number in the subject line."}],"document_download_instructions":null,"places":{"pretty_name":"Richmond, Virginia, USA","region":"Virginia","country":"United States","data":{"geometry":{"coordinates":[-77.436,37.541]},"bbox":[-77.6,37.4,-77.3,37.65]}},"place_seo_lists":{"slug":"virginia"}}],"documents":[{"removed_at":null,"title":"Attachment A - Statement of Work.pdf","date_posted":"2026-07-14T00:00:00.000Z","is_private":false,"filename":"attachment-a-sow.pdf","stored_documents":{"key":"rfps/3f8a1c42/attachment-a-sow.pdf","is_in_supabase":true},"key":"rfps/3f8a1c42/attachment-a-sow.pdf"},{"removed_at":null,"title":"Amendment 0001 - Revised Equipment Schedule.pdf","date_posted":"2026-07-16T00:00:00.000Z","is_private":false,"filename":"amendment-0001.pdf","stored_documents":{"key":"rfps/3f8a1c42/amendment-0001.pdf","is_in_supabase":true},"key":"rfps/3f8a1c42/amendment-0001.pdf"}],"crawled_rfps":[{"source":"sam-dot-gov","source_url":"https://sam.gov/opp/1a2b3c4d5e6f7890abcdef1234567890/view","title":"HVAC PREVENTIVE MAINT SVCS - DEPOT OPS","solicitation_identifier":"SPE8EH-26-R-0142"}],"public_notices":[],"awards":[{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Facility HVAC Maintenance Services","award_identifier":"47QRAA24D008K","vendor_name":"Northwind Facility Services LLC","award_value_cents":128450000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2026-04-01T00:00:00.000Z","date_ended":"2029-03-31T00:00:00.000Z"},{"id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","title":"Facility HVAC Maintenance Services - Option Year One","award_identifier":"47QRAA24D008K-0001","vendor_name":"Northwind Facility Services LLC","award_value_cents":41200000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2029-04-01T00:00:00.000Z","date_ended":"2030-03-31T00:00:00.000Z"}],"award_count":2,"awards_next_cursor":null}}},{"title":"A sparse local solicitation","description":"A small city bid carried only in a newspaper legal notice. The inference exists but most of its fields are null, because the AI records a value only on explicit evidence rather than guessing. There are no stored attachments (`has_external_documents` is true and `document_download_instructions` explains where to get them) and no awards yet.","request":{"id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68"},"response":{"rfp":{"status":"open","status_reason":null,"source_url":"https://www.planetbids.com/portal/12345/bo/bo-detail/98765","date_due":"2026-09-02T19:00:00.000Z","date_posted":null,"title":"Annual Sidewalk Repair Program","solicitation_identifier":"IFB 2026-014","private_metadata":null,"explicit_naics_codes":null,"explicit_psc_codes":null,"has_external_documents":true,"rfp_inferences":[{"is_latest":true,"inferred_naics_codes":{"code":"238990","label":"All Other Specialty Trade Contractors"},"inferred_psc_codes":null,"rfp_set_asides":[],"rfp_smart_codes":[{"content":"concrete sidewalk repair"},{"content":"curb and gutter replacement"},{"content":"ada ramp installation"}],"rfp_required_bonds":[],"inferred_rfp_contacts":[],"inferred_rfp_raw_buyers":[{"raw_buyers":{"buyer_tiers":{"id":"e40a8c62-1f95-4b73-a2d6-5c8e0b4f7139","name_pretty":"City of Fairhaven","name_pretty_hierarchy":"City of Fairhaven","parent_buyer_tier_id":null,"buyer_roots":{"root_type":"city","is_coop":false}}}}],"rfp_recompete_estimates":[],"title":"Annual Sidewalk Repair Program","blurb":"The City of Fairhaven is soliciting bids for its annual program of concrete sidewalk, curb, and ADA ramp repairs.","description":"The city seeks a licensed contractor to remove and replace deteriorated sidewalk panels, curbs, and gutters at locations identified by the Public Works Department, and to bring pedestrian ramps into compliance with current accessibility standards. Quantities are approximate and work is ordered by task.","milestones":[],"type":"Invitation for/to Bid (IFB/ITB)","other_type":null,"level":"Local","in_person":null,"top_clearance":null,"max_education_required":null,"insurance_required":null,"rfp_insurance_coverages":[],"past_performance_strictness":null,"past_performance_minimum_count":null,"past_performance_recency_years":null,"past_performance_minimum_project_value_usd_cents":null,"past_performance_contact_required":null,"local_preference_level":null,"local_preference_raw":null,"local_preference_radius_mi":null,"local_preference_place":null,"contract_period_months":null,"contract_period_raw_text":null,"is_supply":null,"is_service":true,"can_middleman":false,"national_stock_numbers":null,"cage_codes":null,"is_off_the_shelf":null,"explicit_budget_or_award_amount_min_usd_cents":null,"explicit_budget_or_award_amount_max_usd_cents":null,"submission_methods":null,"document_download_instructions":{"url":"https://example-city.gov/purchasing/bids","site_name":"City of Fairhaven Vendor Portal","phone_number":"+1 217-555-0198","person_name":"Marcus Ellery","person_title":"Senior Procurement Officer","email_address":"purchasing@example-city.gov","address":"500 Main Street, Room 210, Fairhaven, IL 62701","location_name":"City Hall Purchasing Counter"},"places":null,"place_seo_lists":null}],"documents":[],"crawled_rfps":[{"source":"planet-bids","source_url":"https://www.planetbids.com/portal/12345/bo/bo-detail/98765","title":"Annual Sidewalk Repair Program","solicitation_identifier":"IFB 2026-014"}],"public_notices":[{"content":"NOTICE TO BIDDERS: Sealed bids for the Annual Sidewalk Repair Program, IFB 2026-014, will be received by the City of Fairhaven until 2:00 PM local time on September 2, 2026, at which time they will be publicly opened and read aloud.","published_at":"2026-08-05T00:00:00.000Z","publication_name":"Fairhaven Daily Register","publication_city":"Fairhaven","publication_state":"IL","publication_url":"https://legals.example-register.com/notice/2026/0805/44821"}],"awards":[],"award_count":0,"awards_next_cursor":null}}}]}]},{"procedure":"opportunities.get-awards","versions":[{"version":"2026-07-05","description":"Contract awards linked to an opportunity — the contracts that resulted from (or were otherwise matched to) the solicitation. Returns the 10 most recently linked awards, newest link first; `hasMore` is true when further awards exist. Returns 404 when the opportunity does not exist or is a private opportunity belonging to another organization.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rfpId":{"description":"The opportunity's Bidscope id (`rfps.id`, as returned by `opportunities.search` as `\"rfps.id\"`). Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["rfpId"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"awards":{"description":"The 10 most recently linked awards, newest link first. Ordered by when Bidscope linked the award to the opportunity, which is not necessarily `date_awarded` order.","type":"array","items":{"type":"object","properties":{"id":{"description":"The award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract's title as reported by the awarding source, null when the source published none. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The awarding agency's contract identifier (the federal Procurement Instrument Identifier for FPDS/SAM awards), null for sources that publish none. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_name":{"description":"Display name of the vendor that won the contract, null when the award has no linked vendor (or the linked one is suppressed). Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded. Example: \"2026-03-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the contract's period of performance. Example: \"2026-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the contract's period of performance — in the past for expired contracts. Example: \"2029-03-31T00:00:00.000Z\"."}},"required":["id","title","piid","vendor_name","award_value_cents","date_awarded","date_started","date_ended"],"additionalProperties":false}},"hasMore":{"description":"True when more than 10 awards are linked to the opportunity. This endpoint has no paging — use `awards.search`, or the opportunity's `awards_next_cursor` flow, to go deeper. Example: false.","type":"boolean"}},"required":["awards","hasMore"],"additionalProperties":false},"examples":[{"title":"Awards resulting from a solicitation","description":"A solicitation that produced two contracts. `piid` and `award_value_cents` come from the awarding source, so either can be null on non-federal awards.","request":{"rfpId":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30"},"response":{"awards":[{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Facility HVAC Maintenance Services","piid":"47QRAA24D008K","vendor_name":"Northwind Facility Services LLC","award_value_cents":128450000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2026-04-01T00:00:00.000Z","date_ended":"2029-03-31T00:00:00.000Z"},{"id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","title":"Facility HVAC Maintenance Services — Base Year Option","piid":"47QRAA24D008K-0001","vendor_name":"Northwind Facility Services LLC","award_value_cents":41200000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2029-04-01T00:00:00.000Z","date_ended":"2030-03-31T00:00:00.000Z"}],"hasMore":false}},{"title":"An opportunity with no linked awards","description":"Open solicitations normally have no awards yet — an empty list, not a 404.","request":{"rfpId":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68"},"response":{"awards":[],"hasMore":false}}]}]},{"procedure":"opportunities.get-followers","versions":[{"version":"2026-07-05","description":"The vendors following an opportunity — those that downloaded its documents, placed a bid, or were listed by the source as prospective bidders. One record is one follow link between a vendor and this opportunity, carrying the vendor (`lead`) with its contact roster (`people`, each with any email-deliverability checks) and its capability smart codes.\n\nUse it to see who your competition is on a solicitation, and who at those firms to reach.\n\nReturns at most the 10 most recently recorded follower links, newest first; `hasMore` is true when an 11th exists. There is no paging — 10 is the ceiling. Follow links that have been removed, and vendors flagged to be ignored, are excluded. Each vendor's `people` list is capped at 11 contacts, and contacts with no name, email, and phone whatsoever are dropped rather than returned as empty rows.\n\nReturns 404 when the opportunity does not exist or is a private opportunity belonging to another organization. An opportunity nobody follows returns an empty list, not a 404.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rfpId":{"description":"The opportunity's Bidscope id (`rfps.id`, as returned by `opportunities.search` as `\"rfps.id\"`). Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["rfpId"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"followers":{"description":"The 10 most recent follower links, newest first (by when Bidscope recorded the follow). Removed links and vendors flagged as ignored are excluded. Empty when nobody is recorded as following the opportunity — which is normal, since only some sources publish plan-holder or document-download lists at all.","type":"array","items":{"type":"object","properties":{"id":{"description":"Bidscope id of the FOLLOW LINK between this vendor and this opportunity — not the vendor's id (that is `lead.id`). Example: \"e51d7a09-3b64-4c28-9a17-0f6b2d8c4e13\".","type":"string"},"createdAt":{"type":"string","format":"date-time","description":"When Bidscope first recorded this vendor as following the opportunity. This is the ordering key for the list (newest first), and it reflects when Bidscope observed the follow, which can be later than when the vendor actually acted. Example: \"2026-07-14T09:22:31.118Z\"."},"type":{"description":"How the vendor is following the opportunity, normalized at crawl time. \"download-documents\" means it pulled the solicitation documents, \"placed-bid\" that it submitted a bid, \"prospective-bidder\" that the source listed it as an interested party, and \"follow\" that it explicitly subscribed. Writers that do not supply a type fall back to \"prospective-bidder\". Examples: \"download-documents\", \"placed-bid\", \"prospective-bidder\", \"follow\".","anyOf":[{"type":"string"},{"type":"null"}]},"lead":{"description":"The vendor doing the following. This is the same vendor record `vendors.get` returns, trimmed to the fields useful for sizing up the competition on an opportunity.","type":"object","properties":{"id":{"description":"The vendor's Bidscope id; pass it to `vendors.get`, `vendors.get-awards`, or `vendors.get-contacts`. Example: \"7f2c9a51-4d80-4e63-b1c7-9a3e5d0b8f46\".","type":"string"},"name":{"description":"The vendor's name exactly as the source published it, null when the source published none. Example: \"NORTHWIND FACILITY SERVICES, LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"prettyName":{"description":"A cleaned-up, display-ready version of the vendor name (casing and legal-suffix normalization). Null until normalization has run for this vendor — fall back to `name`. Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"address":{"description":"The vendor's address as a single line, as published by the source. Null when the source published none. Example: \"1420 Industrial Pkwy, Suite 12, Columbus, OH 43229\".","anyOf":[{"type":"string"},{"type":"null"}]},"certifications":{"description":"Raw certification / socio-economic program labels as published by the source, unmapped and un-deduplicated across sources — the same program can appear under different wordings. Null when the source published none. Example: [\"Women Owned Small Business\", \"HUBZone\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"websiteUrl":{"description":"The vendor's website, null when none is known. Example: \"https://www.northwind-facility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"contactName":{"description":"Legacy single contact name recorded directly on the vendor record (typically whoever the source listed against the registration). Distinct from the `people` list, which is the structured contact roster. Null when none is known. Example: \"Marcus Ellery\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailAddress":{"description":"Legacy single contact email recorded directly on the vendor record, null when none is known. Example: \"bids@northwind-facility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"description":"Legacy single contact phone recorded directly on the vendor record, formatted as published. Null when none is known. Example: \"(555) 010-4471\".","anyOf":[{"type":"string"},{"type":"null"}]},"placePrettyName":{"description":"Display name of the vendor's resolved location, null when its address has not been geocoded. Example: \"Columbus, Ohio, United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"people":{"description":"The vendor's known contacts. Capped at 11 per vendor (the 10 shown in the app plus one extra so a client can tell there are more) and ordered oldest-recorded first, though the order is not guaranteed. Contacts with no name, email, and phone at all are omitted. Empty when Bidscope knows no contacts for the vendor.","type":"array","items":{"type":"object","properties":{"id":{"description":"The contact person's Bidscope id. Example: \"a4c81f27-6b93-4d05-8e2a-3c7f1b9d6054\".","type":"string"},"fullName":{"description":"The contact's full name, null when only an email or phone is known for them. Example: \"Marcus Ellery\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailAddress":{"description":"The contact's email address, null when unknown. Example: \"marcus.ellery@northwind-facility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"description":"The contact's phone number as recorded, null when unknown. Example: \"(555) 010-4472\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailValidations":{"description":"Email-deliverability checks recorded for this contact's address. Empty when the address has never been validated, or when the contact has no email at all. Usually zero or one entry; more than one means the address was re-checked over time.","type":"array","items":{"type":"object","properties":{"id":{"description":"Bidscope id of the deliverability check. Example: \"d83b0e15-72a4-4c19-9f36-5b0a8e2d7c41\".","type":"string"},"emailAddress":{"description":"The address that was checked — always the contact's own `emailAddress`, since validations are matched to the contact on it. Example: \"marcus.ellery@northwind-facility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"isDeliverable":{"description":"True when the mail provider accepted the address, false when it rejected it. Null when the check was inconclusive (e.g. a catch-all domain). Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the deliverability check ran. Older results are not re-verified, so treat a distant date as a stale signal. Example: \"2026-05-02T18:41:07.902Z\"."}},"required":["id","emailAddress","isDeliverable","createdAt"],"additionalProperties":false}}},"required":["id","fullName","emailAddress","phoneNumber","emailValidations"],"additionalProperties":false}},"smartCodes":{"description":"The vendor's capability smart codes, drawn from its inference records with removed codes excluded. Empty when the vendor has not been inferred yet. The internal embedding vector for each code is deliberately not exposed.","type":"array","items":{"type":"object","properties":{"id":{"description":"Bidscope id of the smart code. Example: \"2b6f4c08-1a95-4e72-b0d3-8c5e7a1f9236\".","type":"string"},"content":{"description":"The capability statement itself — one short natural-language claim about what the vendor does, generated from the vendor's profile and award history. Example: \"Provides scheduled and emergency HVAC maintenance for government facilities.\".","type":"string"}},"required":["id","content"],"additionalProperties":false}}},"required":["id","name","prettyName","address","certifications","websiteUrl","contactName","emailAddress","phoneNumber","placePrettyName","people","smartCodes"],"additionalProperties":false}},"required":["id","createdAt","type","lead"],"additionalProperties":false}},"hasMore":{"description":"True when more than 10 vendors follow the opportunity. This endpoint has no paging — 10 is the most it will ever return. Example: false.","type":"boolean"}},"required":["followers","hasMore"],"additionalProperties":false},"examples":[{"title":"Vendors that pulled the documents","description":"A solicitation on a source that publishes its document-download list. `hasMore` is true, so at least one more follower exists beyond these 10 — there is no way to fetch it from this endpoint.","request":{"rfpId":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30"},"response":{"followers":[{"id":"e51d7a09-3b64-4c28-9a17-0f6b2d8c4e13","createdAt":"2026-07-14T09:22:31.118Z","type":"download-documents","lead":{"id":"7f2c9a51-4d80-4e63-b1c7-9a3e5d0b8f46","name":"NORTHWIND FACILITY SERVICES, LLC","prettyName":"Northwind Facility Services LLC","address":"1420 Industrial Pkwy, Suite 12, Columbus, OH 43229","certifications":["Women Owned Small Business","HUBZone"],"websiteUrl":"https://www.northwind-facility.example.com","contactName":"Marcus Ellery","emailAddress":"bids@northwind-facility.example.com","phoneNumber":"(555) 010-4471","placePrettyName":"Columbus, Ohio, United States","people":[{"id":"a4c81f27-6b93-4d05-8e2a-3c7f1b9d6054","fullName":"Marcus Ellery","emailAddress":"marcus.ellery@northwind-facility.example.com","phoneNumber":"(555) 010-4472","emailValidations":[{"id":"d83b0e15-72a4-4c19-9f36-5b0a8e2d7c41","emailAddress":"marcus.ellery@northwind-facility.example.com","isDeliverable":true,"createdAt":"2026-05-02T18:41:07.902Z"}]},{"id":"b90e3d62-5f17-4a88-8c04-6d1b7e9a2f35","fullName":"Tessa Nakamura","emailAddress":null,"phoneNumber":"(555) 010-4473","emailValidations":[]}],"smartCodes":[{"id":"2b6f4c08-1a95-4e72-b0d3-8c5e7a1f9236","content":"Provides scheduled and emergency HVAC maintenance for government facilities."},{"id":"5c1a8e34-7d20-4b96-a8f5-0e2c6b9d4713","content":"Holds journeyman-level refrigeration technicians certified for federal depot work."}]}},{"id":"f6247b83-0c51-4d39-8b7e-2a9f4c1e6d08","createdAt":"2026-07-12T15:07:44.006Z","type":"prospective-bidder","lead":{"id":"3d5b7f10-8a24-4c67-9e1b-4f0c2a8d6759","name":"Cedarline Mechanical Contractors Inc","prettyName":null,"address":null,"certifications":null,"websiteUrl":null,"contactName":null,"emailAddress":null,"phoneNumber":null,"placePrettyName":null,"people":[],"smartCodes":[]}}],"hasMore":true}},{"title":"An opportunity nobody is recorded as following","description":"Most sources publish no plan-holder or download list at all, so an empty result says nothing about how contested the opportunity is. It is an empty list, not a 404.","request":{"rfpId":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68"},"response":{"followers":[],"hasMore":false}}]}]},{"procedure":"awards.search","versions":[{"version":"2026-07-05","description":"Searches contract awards, ranked against one of your organization's matching profiles. One item is one award — an ordinary contract, a contract vehicle, or a task order placed against a vehicle. `score` is the profile-to-contract similarity normalised to [0, 1]; `complementary_score` is the equivalent for subcontracting fit.\n\nOrdering. Sorting by `score` or `complementary_score` orders the full result set exactly. Any other sort orders the full result set too, as long as the query does not also filter on `score` / `complementary_score`.\n\nCombining a minimum-match filter with a non-score sort is exact as well for nearly every realistic shape, via three cooperating strategies. Dense matches: the query walks contracts in the requested sort order and scores them as it goes. Sparse matches: the query instead enumerates every contract above the threshold directly and sorts those — fast at any page depth, and EXACT, because that enumeration is a range test evaluated against each distinct similarity vector rather than an approximate nearest-neighbour lookup. Nothing qualifying is missed, so these answers can also report a real `total`. Selective filters (a quick-search keyword, or NAICS/PSC/vendor/buyer/region equality): the query enumerates that filter's matching contracts first and scores them in your sort order — which also broadens exactness to sorts like `awards.title`. When none of the three applies (a match threshold below ~15%, where nearly the whole corpus qualifies and enumerating it is not worthwhile), the search returns either the correct next rows in order (a short page with nothing wrong or skipped before it) or falls back to sorting your best-matching 2,000 contracts — a fixed pool, so paging through it is stable, but a contract ranking below those 2,000 is not returned.\n\nPaging. `page` + `search.pageSize`, capped at 1,000 results overall — past the cap the response is `{ total: 0, items: [] }`, and the page straddling it is truncated. `total` is -1 unless you request a count via `skipCountTotal` and the query shape can afford one (see both fields).\n\nIf the matching profile has no embedding centroid yet, a query that reads the score (ranked sort or score filter) returns an empty page; any other query is answered normally with `score` and `complementary_score` null on every row.\n\nErrors: 404 when `matchingProfileId` matches no profile, 403 when the profile belongs to another organization, 500 on an unexpected failure.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile to rank against. Results are ordered by the cosine similarity of each contract's AI embedding to this profile's centroid, so the profile — not the query text — is what makes a result \"relevant\". Must belong to your organization (403 otherwise). Example: \"d5c8f0a3-2e61-4b79-9c04-8a7f3b1d6e52\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The search state: `{ orderBy, sort, pageSize, filters, quickSearch?, filterMeta? }`. `orderBy` is one of \"awards.date_started\", \"awards.date_ended\", \"awards.date_awarded\", \"awards.date_originated\", \"score\", \"complementary_score\" — only sorts with an index-backed query path are accepted; every other column remains filterable and displayable, just not orderable. `sort` is \"asc\" or \"desc\"; `pageSize` must be one of 1, 10, 25, 50, 100. `filters` is a filter tree (`{ type: \"group\", isAnd, filters: [...] }` nesting `{ type: \"filter\", column, filter: { operator, value } }` leaves) or null for no filtering — see the Filters section of this reference for the operators, and the per-column descriptions in the response for what each column holds. One column carries an extra rule: `awards.is_active` accepts only `enum.eq \"true\"` (or the equivalent null-inclusive `enum.neq \"false\"`) — an expired-contracts-only filter is rejected as invalid. `quickSearch` is an optional free-text term matched case-insensitively against the contract title, contract number, buyer hierarchy name and vendor name. `filterMeta` is an opaque bag the Bidscope UI uses to remember display labels; it does not affect results. Example: { \"orderBy\": \"score\", \"sort\": \"desc\", \"pageSize\": 25, \"filters\": null }.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["awards.date_started","awards.date_ended","awards.date_awarded","awards.date_originated","score","complementary_score"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Ranked search has no cursor: each page re-runs the ranking and slices out rows `pageSize * (page - 1)` through `pageSize * page`. Paging past 1,000 total results returns an empty page. Example: 1.","type":"number","minimum":1},"skipCountTotal":{"description":"Same contract as `opportunities.search`: pass true to skip counting (`total` comes back -1 — the right choice when paging a UI), omit or pass false to request a real `total` where one can be computed exactly. Counting happens only on provably-exact query paths: no-score queries (one full pass over the filtered set), score-thresholded searches that walked their sort order or candidate set to the end, and threshold enumerations (exact by construction). Answers served by the approximate nearest-neighbour index — score-ordered pools — return -1 even when a count is requested, and no slow compensating query is run. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"-1 unless a count was requested (`skipCountTotal` false/omitted) AND the answer came from a provably-exact query path: queries that read no match score report the exact count of matching rows, and a score-thresholded search that walked its sort order (or its filter's candidate set) to the end reports the exact count it proved. Answers served from the similarity index — score sorts, above-threshold enumerations, the bounded match pool — always report -1, even when a count was requested: the similarity index is approximate, so no trustworthy count can be derived from it and none is attempted. 0 on an empty page from an exact path (including once you have paged past the 1,000-result ceiling). With `skipCountTotal: true`, always -1 on non-empty pages — page until `items` comes back empty rather than dividing this by `pageSize`. Example: -1.","type":"number"},"items":{"description":"One page of matching contract awards, one object per award, ordered by the requested `search.orderBy` / `search.sort`. Each key is a search column name, matching the filter/sort column vocabulary. Empty when the page is past the end of the ranked pool, past the 1,000-result ceiling, or when the matching profile has no embedding centroid yet (a brand-new profile that has not been processed).","type":"array","items":{"type":"object","properties":{"awards.id":{"description":"The contract award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"awards.is_active":{"description":"Tri-state contract status: true = Active, false = Expired, null = Unknown (no dates to decide from). As a filter only two leaves are accepted: `enum.eq \"true\"` (the Bidscope UI's \"Only Show Active Contracts\" switch) and the equivalent null-inclusive `enum.neq \"false\"`; filtering TO expired contracts (`eq \"false\"` / `neq \"true\"`) is rejected as invalid. Unknown is ~0.002% of contracts, so the two accepted forms are near-identical. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"awards.title":{"description":"The contract title as published by the awarding source (FPDS text arrives upper-cased). Null when the source published none. This is the only free-text column awards can be keyword-filtered on — the UI's \"must include\" / \"must not include\" keywords become `string.contains` / `string.ncontains` filters here. Example: \"FACILITY HVAC MAINTENANCE SERVICES\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.award_identifier":{"description":"The user-facing contract number, source-agnostic (federal PIID, CanadaBuys contract number, ...). Null when the source published none. Filterable but not sortable. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.date_started":{"type":["string","null"],"format":"date-time","description":"Start of the period of performance, null when the source published no date. Example: \"2026-04-01T00:00:00.000Z\"."},"awards.date_ended":{"type":["string","null"],"format":"date-time","description":"End of the period of performance, null when the source published no date. Example: \"2029-03-31T00:00:00.000Z\"."},"awards.date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded, null when the source published no date. Example: \"2026-03-11T00:00:00.000Z\"."},"awards.date_originated":{"type":["string","null"],"format":"date-time","description":"Derived \"earliest known\" date: the minimum of `awards.date_awarded`, `awards.date_started` and the record's creation time, so it is never null. This is the Bidscope UI's default sort column, because it gives a usable chronology even for records missing contract dates. Example: \"2026-03-11T00:00:00.000Z\"."},"awards.recent_action_date":{"type":["string","null"],"format":"date-time","description":"Derived \"most recent activity\" date: the maximum of the award's creation/awarded/start dates and its transaction ledger's signed/start/creation dates, ignoring future dates. Use it to find contracts that were recently modified rather than recently awarded. Null only when every candidate date is in the future. Example: \"2027-03-28T00:00:00.000Z\"."},"awards.buyer.id":{"description":"Consolidated buyer tier id for the awarding buyer; pass it to `buyers.get`. Null when the award's raw buyer has not been consolidated yet. Filtering on this column matches the whole subtree — the selected tier and every descendant — so filtering on a parent agency also returns its sub-agencies' contracts. Example: \"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.buyer.name_pretty":{"description":"The buyer's full hierarchy display name from its consolidated tier, falling back to the raw buyer's root name when unconsolidated. Null when the award names no buyer. Awards can name several raw buyers; this is the first one recorded. Example: \"General Services Administration > Public Buildings Service > Region 8\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.buyer.root_type":{"description":"Level of government the buyer sits at, from its consolidated root. One of: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", \"private\". Null when the buyer is unconsolidated or absent. Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.vendor.id":{"description":"Bidscope id of the vendor that won the contract; pass it to `vendors.get`. Null when the award has no linked vendor. Unlike the buyer filter this matches exactly — there is no vendor hierarchy to expand. Example: \"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.vendor.name_pretty":{"description":"Display name of the winning vendor. Null when the award has no linked vendor. Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.naics_codes.code":{"description":"The 6-digit NAICS industry code from the award's latest AI inference (not the code the source published — `awards.get` returns both as `inferred_naics_code` and `explicit_naics_code`). Null when the inference assigned none. Example: \"561210\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.psc_codes.code":{"description":"The 4-character Product/Service Code from the award's latest AI inference. Null when the inference assigned none. Example: \"J041\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.places.country":{"description":"Country of the contract's place of performance. Null when the source published no location or it could not be geocoded. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.places.region":{"description":"State / province of the contract's place of performance. Null when unresolved or the place resolved only to a country. Example: \"Colorado\".","anyOf":[{"type":"string"},{"type":"null"}]},"distance":{"description":"Straight-line distance in METRES from your organization's saved location to the contract's place of performance. Null when your organization has no saved coordinates, or the award's place has no geometry — in which case a distance filter matches nothing. Example: 42350.7 (about 26 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"score":{"description":"Match score in [0, 1] against the requested matching profile — the calibrated normalisation `min(1.30 * e^(-2.05 * d), 1)` of the cosine distance `d` between the contract's embedding and the profile's centroid. Higher is a better match. Filter it with `number.gt` / `number.lt` on the same [0, 1] scale (the Bidscope UI's minimum-match slider is `number.gt`). Null on every row when the matching profile has no embedding centroid yet (still processing) AND the query does not read the score — such a query is answered unranked rather than returning nothing; treat null as \"unknown\", not zero. Example: 0.78.","anyOf":[{"type":"number"},{"type":"null"}]},"complementary_score":{"description":"The same [0, 1] normalisation applied to the contract's \"complementary target\" embedding — how well the contract suits you as a SUBCONTRACTING or teaming opportunity rather than as prime work (the Bidscope UI calls it \"Sub Match\"). Null when the contract has no complementary target, which is not the same as a zero score and must not be rendered as 0%. Example: 0.41.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["awards.id","awards.is_active","awards.title","awards.award_identifier","awards.date_started","awards.date_ended","awards.date_awarded","awards.date_originated","awards.recent_action_date","awards.buyer.id","awards.buyer.name_pretty","awards.buyer.root_type","awards.vendor.id","awards.vendor.name_pretty","awards.naics_codes.code","awards.psc_codes.code","awards.places.country","awards.places.region","distance","score","complementary_score"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best-matching contracts for a profile","description":"A plain ranked query: no filters, sorted by match score descending, which is the one ordering that streams straight off the similarity index. Note `total` is -1 — page until `items` is empty. `complementary_score` is null on the second row, meaning that contract has no subcontracting target, not that it scored zero.","request":{"matchingProfileId":"d5c8f0a3-2e61-4b79-9c04-8a7f3b1d6e52","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1},"response":{"total":-1,"items":[{"awards.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","awards.is_active":true,"awards.title":"FACILITY HVAC MAINTENANCE SERVICES","awards.award_identifier":"47QRAA24D008K","awards.date_started":"2026-04-01T00:00:00.000Z","awards.date_ended":"2029-03-31T00:00:00.000Z","awards.date_awarded":"2026-03-11T00:00:00.000Z","awards.date_originated":"2026-03-11T00:00:00.000Z","awards.recent_action_date":"2026-03-11T00:00:00.000Z","awards.buyer.id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","awards.buyer.name_pretty":"General Services Administration > Public Buildings Service > Region 8","awards.buyer.root_type":"federal","awards.vendor.id":"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63","awards.vendor.name_pretty":"Northwind Facility Services LLC","awards.naics_codes.code":"561210","awards.psc_codes.code":"J041","awards.places.country":"United States","awards.places.region":"Colorado","distance":42350.7,"score":0.78,"complementary_score":0.41},{"awards.id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","awards.is_active":false,"awards.title":"BOILER PLANT OPERATION AND MAINTENANCE","awards.award_identifier":"36C24919D0043","awards.date_started":"2023-01-01T00:00:00.000Z","awards.date_ended":"2025-12-31T00:00:00.000Z","awards.date_awarded":"2022-11-18T00:00:00.000Z","awards.date_originated":"2022-11-18T00:00:00.000Z","awards.recent_action_date":"2025-08-04T00:00:00.000Z","awards.buyer.id":"3e7b1a90-4c25-4d68-8f31-9a0c6e2d5b74","awards.buyer.name_pretty":"Department of Veterans Affairs > Veterans Health Administration","awards.buyer.root_type":"federal","awards.vendor.id":null,"awards.vendor.name_pretty":null,"awards.naics_codes.code":"561210","awards.psc_codes.code":"J045","awards.places.country":"United States","awards.places.region":"Wyoming","distance":168920.4,"score":0.66,"complementary_score":null}]}},{"title":"Filtered like the Bidscope simple search","description":"The filter tree the app builds from its simple-search panel: an AND group holding the default active-contracts scope (`enum.eq \"true\"` — the \"Only Show Active Contracts\" switch), a minimum match threshold, an OR group of buyer tier ids (each expands to that agency and all of its sub-agencies), an OR group of NAICS codes, and a date lower bound. Sorted by `awards.date_originated`, so despite the minimum-match filter these are genuinely the newest contracts above the threshold, not a re-sorted sample of the best-matching ones.","request":{"matchingProfileId":"d5c8f0a3-2e61-4b79-9c04-8a7f3b1d6e52","search":{"orderBy":"awards.date_originated","sort":"desc","pageSize":25,"quickSearch":"","filters":{"type":"group","isAnd":true,"filters":[{"type":"filter","column":"awards.is_active","filter":{"operator":"enum.eq","value":"true"}},{"type":"filter","column":"score","filter":{"operator":"number.gt","value":0.6}},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"awards.buyer.id","filter":{"operator":"string.eq","value":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14"}}]},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"awards.naics_codes.code","filter":{"operator":"string.eq","value":"561210"}},{"type":"filter","column":"awards.naics_codes.code","filter":{"operator":"string.eq","value":"238220"}}]},{"type":"filter","column":"awards.date_awarded","filter":{"operator":"date.after","value":"2026-01-01T00:00:00.000Z"}}]},"filterMeta":{"simpleData":{"quickFilter":"ai","buyerLabels":{"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14":"General Services Administration > Public Buildings Service > Region 8"}}}},"page":1},"response":{"total":-1,"items":[{"awards.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","awards.is_active":true,"awards.title":"FACILITY HVAC MAINTENANCE SERVICES","awards.award_identifier":"47QRAA24D008K","awards.date_started":"2026-04-01T00:00:00.000Z","awards.date_ended":"2029-03-31T00:00:00.000Z","awards.date_awarded":"2026-03-11T00:00:00.000Z","awards.date_originated":"2026-03-11T00:00:00.000Z","awards.recent_action_date":"2026-03-11T00:00:00.000Z","awards.buyer.id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","awards.buyer.name_pretty":"General Services Administration > Public Buildings Service > Region 8","awards.buyer.root_type":"federal","awards.vendor.id":"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63","awards.vendor.name_pretty":"Northwind Facility Services LLC","awards.naics_codes.code":"561210","awards.psc_codes.code":"J041","awards.places.country":"United States","awards.places.region":"Colorado","distance":42350.7,"score":0.78,"complementary_score":0.41},{"awards.id":"f5091a7c-3b46-4e28-8d90-6c2b7f4a1e53","awards.is_active":null,"awards.title":"AIR HANDLER REPLACEMENT — DENVER FEDERAL CENTER","awards.award_identifier":"47PM0126C0007","awards.date_started":null,"awards.date_ended":null,"awards.date_awarded":"2026-02-04T00:00:00.000Z","awards.date_originated":"2026-02-04T00:00:00.000Z","awards.recent_action_date":"2026-02-04T00:00:00.000Z","awards.buyer.id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","awards.buyer.name_pretty":"General Services Administration > Public Buildings Service > Region 8","awards.buyer.root_type":"federal","awards.vendor.id":"e83b0d47-51c9-4f26-9a70-4d2f8c6b1e35","awards.vendor.name_pretty":"Alpenglow Mechanical Contractors LLC","awards.naics_codes.code":"238220","awards.psc_codes.code":"J041","awards.places.country":"United States","awards.places.region":"Colorado","distance":39118.2,"score":0.71,"complementary_score":0.52}]}}]},{"version":"2026-08-19","description":"Searches contract awards, ranked against one of your organization's matching profiles. One item is one award — an ordinary contract, a contract vehicle, or a task order placed against a vehicle. `score` is the profile-to-contract similarity normalised to [0, 1]; `complementary_score` is the equivalent for subcontracting fit.\n\nOrdering. Sorting by `score` or `complementary_score` orders the full result set exactly. Any other sort orders the full result set too, as long as the query does not also filter on `score` / `complementary_score`.\n\nCombining a minimum-match filter with a non-score sort is exact as well for nearly every realistic shape, via three cooperating strategies. Dense matches: the query walks contracts in the requested sort order and scores them as it goes. Sparse matches: the query instead enumerates every contract above the threshold directly and sorts those — fast at any page depth, and EXACT, because that enumeration is a range test evaluated against each distinct similarity vector rather than an approximate nearest-neighbour lookup. Nothing qualifying is missed, so these answers can also report a real `total`. Selective filters (a quick-search keyword, or NAICS/PSC/vendor/buyer/region equality): the query enumerates that filter's matching contracts first and scores them in your sort order — which also broadens exactness to sorts like `awards.title`. When none of the three applies (a match threshold below ~15%, where nearly the whole corpus qualifies and enumerating it is not worthwhile), the search returns either the correct next rows in order (a short page with nothing wrong or skipped before it) or falls back to sorting your best-matching 2,000 contracts — a fixed pool, so paging through it is stable, but a contract ranking below those 2,000 is not returned.\n\nPaging. `page` + `search.pageSize`, capped at 1,000 results overall — past the cap the response is `{ total: 0, items: [] }`, and the page straddling it is truncated. `total` is -1 unless you request a count via `skipCountTotal` and the query shape can afford one (see both fields).\n\nIf the matching profile has no embedding centroid yet, a query that reads the score (ranked sort or score filter) returns an empty page; any other query is answered normally with `score` and `complementary_score` null on every row.\n\nErrors: 404 when `matchingProfileId` matches no profile, 403 when the profile belongs to another organization, 500 on an unexpected failure.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile to rank against. Results are ordered by the cosine similarity of each contract's AI embedding to this profile's centroid, so the profile — not the query text — is what makes a result \"relevant\". Must belong to your organization (403 otherwise). Example: \"d5c8f0a3-2e61-4b79-9c04-8a7f3b1d6e52\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The search state: `{ orderBy, sort, pageSize, filters, quickSearch?, filterMeta? }`. `orderBy` is one of \"awards.date_started\", \"awards.date_ended\", \"awards.date_awarded\", \"awards.date_originated\", \"score\", \"complementary_score\" — only sorts with an index-backed query path are accepted; every other column remains filterable and displayable, just not orderable. `sort` is \"asc\" or \"desc\"; `pageSize` must be one of 1, 10, 25, 50, 100. `filters` is a filter tree (`{ type: \"group\", isAnd, filters: [...] }` nesting `{ type: \"filter\", column, filter: { operator, value } }` leaves) or null for no filtering — see the Filters section of this reference for the operators, and the per-column descriptions in the response for what each column holds. One column carries an extra rule: `awards.is_active` accepts only `enum.eq \"true\"` (or the equivalent null-inclusive `enum.neq \"false\"`) — an expired-contracts-only filter is rejected as invalid. `quickSearch` is an optional free-text term matched case-insensitively against the contract title, contract number, buyer hierarchy name and vendor name. `filterMeta` is an opaque bag the Bidscope UI uses to remember display labels; it does not affect results. Example: { \"orderBy\": \"score\", \"sort\": \"desc\", \"pageSize\": 25, \"filters\": null }.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["awards.date_started","awards.date_ended","awards.date_awarded","awards.date_originated","score","complementary_score"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Ranked search has no cursor: each page re-runs the ranking and slices out rows `pageSize * (page - 1)` through `pageSize * page`. Paging past 1,000 total results returns an empty page. Example: 1.","type":"number","minimum":1},"location":{"description":"Optional point to measure distances from. When supplied it replaces your organization's saved location as the center for the distance column(s) and any distance filter, for this request only. Omit it (or pass null) to use the organization's saved location, which is the previous behaviour. Example: { \"latitude\": 30.267153, \"longitude\": -97.743057 }.","anyOf":[{"type":"object","properties":{"latitude":{"description":"Latitude in decimal degrees. Example: 30.267153.","type":"number","minimum":-90,"maximum":90},"longitude":{"description":"Longitude in decimal degrees. Example: -97.743057.","type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}]},"skipCountTotal":{"description":"Same contract as `opportunities.search`: pass true to skip counting (`total` comes back -1 — the right choice when paging a UI), omit or pass false to request a real `total` where one can be computed exactly. Counting happens only on provably-exact query paths: no-score queries (one full pass over the filtered set), score-thresholded searches that walked their sort order or candidate set to the end, and threshold enumerations (exact by construction). Answers served by the approximate nearest-neighbour index — score-ordered pools — return -1 even when a count is requested, and no slow compensating query is run. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"-1 unless a count was requested (`skipCountTotal` false/omitted) AND the answer came from a provably-exact query path: queries that read no match score report the exact count of matching rows, and a score-thresholded search that walked its sort order (or its filter's candidate set) to the end reports the exact count it proved. Answers served from the similarity index — score sorts, above-threshold enumerations, the bounded match pool — always report -1, even when a count was requested: the similarity index is approximate, so no trustworthy count can be derived from it and none is attempted. 0 on an empty page from an exact path (including once you have paged past the 1,000-result ceiling). With `skipCountTotal: true`, always -1 on non-empty pages — page until `items` comes back empty rather than dividing this by `pageSize`. Example: -1.","type":"number"},"items":{"description":"One page of matching contract awards, one object per award, ordered by the requested `search.orderBy` / `search.sort`. Each key is a search column name, matching the filter/sort column vocabulary. Empty when the page is past the end of the ranked pool, past the 1,000-result ceiling, or when the matching profile has no embedding centroid yet (a brand-new profile that has not been processed).","type":"array","items":{"type":"object","properties":{"awards.id":{"description":"The contract award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"awards.is_active":{"description":"Tri-state contract status: true = Active, false = Expired, null = Unknown (no dates to decide from). As a filter only two leaves are accepted: `enum.eq \"true\"` (the Bidscope UI's \"Only Show Active Contracts\" switch) and the equivalent null-inclusive `enum.neq \"false\"`; filtering TO expired contracts (`eq \"false\"` / `neq \"true\"`) is rejected as invalid. Unknown is ~0.002% of contracts, so the two accepted forms are near-identical. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"awards.title":{"description":"The contract title as published by the awarding source (FPDS text arrives upper-cased). Null when the source published none. This is the only free-text column awards can be keyword-filtered on — the UI's \"must include\" / \"must not include\" keywords become `string.contains` / `string.ncontains` filters here. Example: \"FACILITY HVAC MAINTENANCE SERVICES\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.award_identifier":{"description":"The user-facing contract number, source-agnostic (federal PIID, CanadaBuys contract number, ...). Null when the source published none. Filterable but not sortable. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.date_started":{"type":["string","null"],"format":"date-time","description":"Start of the period of performance, null when the source published no date. Example: \"2026-04-01T00:00:00.000Z\"."},"awards.date_ended":{"type":["string","null"],"format":"date-time","description":"End of the period of performance, null when the source published no date. Example: \"2029-03-31T00:00:00.000Z\"."},"awards.date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded, null when the source published no date. Example: \"2026-03-11T00:00:00.000Z\"."},"awards.date_originated":{"type":["string","null"],"format":"date-time","description":"Derived \"earliest known\" date: the minimum of `awards.date_awarded`, `awards.date_started` and the record's creation time, so it is never null. This is the Bidscope UI's default sort column, because it gives a usable chronology even for records missing contract dates. Example: \"2026-03-11T00:00:00.000Z\"."},"awards.recent_action_date":{"type":["string","null"],"format":"date-time","description":"Derived \"most recent activity\" date: the maximum of the award's creation/awarded/start dates and its transaction ledger's signed/start/creation dates, ignoring future dates. Use it to find contracts that were recently modified rather than recently awarded. Null only when every candidate date is in the future. Example: \"2027-03-28T00:00:00.000Z\"."},"awards.buyer.id":{"description":"Consolidated buyer tier id for the awarding buyer; pass it to `buyers.get`. Null when the award's raw buyer has not been consolidated yet. Filtering on this column matches the whole subtree — the selected tier and every descendant — so filtering on a parent agency also returns its sub-agencies' contracts. Example: \"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.buyer.name_pretty":{"description":"The buyer's full hierarchy display name from its consolidated tier, falling back to the raw buyer's root name when unconsolidated. Null when the award names no buyer. Awards can name several raw buyers; this is the first one recorded. Example: \"General Services Administration > Public Buildings Service > Region 8\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.buyer.root_type":{"description":"Level of government the buyer sits at, from its consolidated root. One of: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", \"private\". Null when the buyer is unconsolidated or absent. Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.vendor.id":{"description":"Bidscope id of the vendor that won the contract; pass it to `vendors.get`. Null when the award has no linked vendor. Unlike the buyer filter this matches exactly — there is no vendor hierarchy to expand. Example: \"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.vendor.name_pretty":{"description":"Display name of the winning vendor. Null when the award has no linked vendor. Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.naics_codes.code":{"description":"The 6-digit NAICS industry code from the award's latest AI inference (not the code the source published — `awards.get` returns both as `inferred_naics_code` and `explicit_naics_code`). Null when the inference assigned none. Example: \"561210\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.psc_codes.code":{"description":"The 4-character Product/Service Code from the award's latest AI inference. Null when the inference assigned none. Example: \"J041\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.places.country":{"description":"Country of the contract's place of performance. Null when the source published no location or it could not be geocoded. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"awards.places.region":{"description":"State / province of the contract's place of performance. Null when unresolved or the place resolved only to a country. Example: \"Colorado\".","anyOf":[{"type":"string"},{"type":"null"}]},"distance":{"description":"Straight-line distance in METRES to the contract's place of performance, measured from the request's `location` when supplied and otherwise from your organization's saved location. Null when your organization has no saved coordinates, or the award's place has no geometry — in which case a distance filter matches nothing. Example: 42350.7 (about 26 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"score":{"description":"Match score in [0, 1] against the requested matching profile — the calibrated normalisation `min(1.30 * e^(-2.05 * d), 1)` of the cosine distance `d` between the contract's embedding and the profile's centroid. Higher is a better match. Filter it with `number.gt` / `number.lt` on the same [0, 1] scale (the Bidscope UI's minimum-match slider is `number.gt`). Null on every row when the matching profile has no embedding centroid yet (still processing) AND the query does not read the score — such a query is answered unranked rather than returning nothing; treat null as \"unknown\", not zero. Example: 0.78.","anyOf":[{"type":"number"},{"type":"null"}]},"complementary_score":{"description":"The same [0, 1] normalisation applied to the contract's \"complementary target\" embedding — how well the contract suits you as a SUBCONTRACTING or teaming opportunity rather than as prime work (the Bidscope UI calls it \"Sub Match\"). Null when the contract has no complementary target, which is not the same as a zero score and must not be rendered as 0%. Example: 0.41.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["awards.id","awards.is_active","awards.title","awards.award_identifier","awards.date_started","awards.date_ended","awards.date_awarded","awards.date_originated","awards.recent_action_date","awards.buyer.id","awards.buyer.name_pretty","awards.buyer.root_type","awards.vendor.id","awards.vendor.name_pretty","awards.naics_codes.code","awards.psc_codes.code","awards.places.country","awards.places.region","distance","score","complementary_score"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best-matching contracts for a profile","description":"A plain ranked query: no filters, sorted by match score descending, which is the one ordering that streams straight off the similarity index. Note `total` is -1 — page until `items` is empty. `complementary_score` is null on the second row, meaning that contract has no subcontracting target, not that it scored zero.","request":{"matchingProfileId":"d5c8f0a3-2e61-4b79-9c04-8a7f3b1d6e52","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1},"response":{"total":-1,"items":[{"awards.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","awards.is_active":true,"awards.title":"FACILITY HVAC MAINTENANCE SERVICES","awards.award_identifier":"47QRAA24D008K","awards.date_started":"2026-04-01T00:00:00.000Z","awards.date_ended":"2029-03-31T00:00:00.000Z","awards.date_awarded":"2026-03-11T00:00:00.000Z","awards.date_originated":"2026-03-11T00:00:00.000Z","awards.recent_action_date":"2026-03-11T00:00:00.000Z","awards.buyer.id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","awards.buyer.name_pretty":"General Services Administration > Public Buildings Service > Region 8","awards.buyer.root_type":"federal","awards.vendor.id":"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63","awards.vendor.name_pretty":"Northwind Facility Services LLC","awards.naics_codes.code":"561210","awards.psc_codes.code":"J041","awards.places.country":"United States","awards.places.region":"Colorado","distance":42350.7,"score":0.78,"complementary_score":0.41},{"awards.id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","awards.is_active":false,"awards.title":"BOILER PLANT OPERATION AND MAINTENANCE","awards.award_identifier":"36C24919D0043","awards.date_started":"2023-01-01T00:00:00.000Z","awards.date_ended":"2025-12-31T00:00:00.000Z","awards.date_awarded":"2022-11-18T00:00:00.000Z","awards.date_originated":"2022-11-18T00:00:00.000Z","awards.recent_action_date":"2025-08-04T00:00:00.000Z","awards.buyer.id":"3e7b1a90-4c25-4d68-8f31-9a0c6e2d5b74","awards.buyer.name_pretty":"Department of Veterans Affairs > Veterans Health Administration","awards.buyer.root_type":"federal","awards.vendor.id":null,"awards.vendor.name_pretty":null,"awards.naics_codes.code":"561210","awards.psc_codes.code":"J045","awards.places.country":"United States","awards.places.region":"Wyoming","distance":168920.4,"score":0.66,"complementary_score":null}]}},{"title":"Filtered like the Bidscope simple search","description":"The filter tree the app builds from its simple-search panel: an AND group holding the default active-contracts scope (`enum.eq \"true\"` — the \"Only Show Active Contracts\" switch), a minimum match threshold, an OR group of buyer tier ids (each expands to that agency and all of its sub-agencies), an OR group of NAICS codes, and a date lower bound. Sorted by `awards.date_originated`, so despite the minimum-match filter these are genuinely the newest contracts above the threshold, not a re-sorted sample of the best-matching ones.","request":{"matchingProfileId":"d5c8f0a3-2e61-4b79-9c04-8a7f3b1d6e52","search":{"orderBy":"awards.date_originated","sort":"desc","pageSize":25,"quickSearch":"","filters":{"type":"group","isAnd":true,"filters":[{"type":"filter","column":"awards.is_active","filter":{"operator":"enum.eq","value":"true"}},{"type":"filter","column":"score","filter":{"operator":"number.gt","value":0.6}},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"awards.buyer.id","filter":{"operator":"string.eq","value":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14"}}]},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"awards.naics_codes.code","filter":{"operator":"string.eq","value":"561210"}},{"type":"filter","column":"awards.naics_codes.code","filter":{"operator":"string.eq","value":"238220"}}]},{"type":"filter","column":"awards.date_awarded","filter":{"operator":"date.after","value":"2026-01-01T00:00:00.000Z"}}]},"filterMeta":{"simpleData":{"quickFilter":"ai","buyerLabels":{"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14":"General Services Administration > Public Buildings Service > Region 8"}}}},"page":1},"response":{"total":-1,"items":[{"awards.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","awards.is_active":true,"awards.title":"FACILITY HVAC MAINTENANCE SERVICES","awards.award_identifier":"47QRAA24D008K","awards.date_started":"2026-04-01T00:00:00.000Z","awards.date_ended":"2029-03-31T00:00:00.000Z","awards.date_awarded":"2026-03-11T00:00:00.000Z","awards.date_originated":"2026-03-11T00:00:00.000Z","awards.recent_action_date":"2026-03-11T00:00:00.000Z","awards.buyer.id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","awards.buyer.name_pretty":"General Services Administration > Public Buildings Service > Region 8","awards.buyer.root_type":"federal","awards.vendor.id":"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63","awards.vendor.name_pretty":"Northwind Facility Services LLC","awards.naics_codes.code":"561210","awards.psc_codes.code":"J041","awards.places.country":"United States","awards.places.region":"Colorado","distance":42350.7,"score":0.78,"complementary_score":0.41},{"awards.id":"f5091a7c-3b46-4e28-8d90-6c2b7f4a1e53","awards.is_active":null,"awards.title":"AIR HANDLER REPLACEMENT — DENVER FEDERAL CENTER","awards.award_identifier":"47PM0126C0007","awards.date_started":null,"awards.date_ended":null,"awards.date_awarded":"2026-02-04T00:00:00.000Z","awards.date_originated":"2026-02-04T00:00:00.000Z","awards.recent_action_date":"2026-02-04T00:00:00.000Z","awards.buyer.id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","awards.buyer.name_pretty":"General Services Administration > Public Buildings Service > Region 8","awards.buyer.root_type":"federal","awards.vendor.id":"e83b0d47-51c9-4f26-9a70-4d2f8c6b1e35","awards.vendor.name_pretty":"Alpenglow Mechanical Contractors LLC","awards.naics_codes.code":"238220","awards.psc_codes.code":"J041","awards.places.country":"United States","awards.places.region":"Colorado","distance":39118.2,"score":0.71,"complementary_score":0.52}]}}]}]},{"procedure":"awards.get","versions":[{"version":"2026-07-05","description":"The full details payload for a single contract award: contract scalars and dates, the awardee vendor (with up to 5 contacts and the true `contact_count`), the awarding buyer, place of performance, NAICS/PSC codes both explicit (published by the source) and inferred (assigned by Bidscope's AI), Bidscope's recompete inference, the first 5 linked solicitations plus `solicitations_next_cursor` for the rest, the parent vehicle when this award is a task order, the 50 largest task orders placed against it when it is a vehicle, and the complete transaction ledger in `phases`. Every embedded list is capped except `phases`; each cap is paired with a count field carrying the true total (`solicitation_count`, `task_order_count`, `vendor.contact_count`). Returns 404 when no award has that id, and 500 on an unexpected failure. Award data is public — unlike opportunities, there is no per-organization visibility filter here.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The award's Bidscope id (`awards.id`, as returned by `awards.search` as `\"awards.id\"` and by `opportunities.get-awards` as `id`). Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"award":{"description":"The full details payload for one contract award.","type":"object","properties":{"id":{"description":"The award's Bidscope id — the same value passed as `id`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract title / description of requirement as published by the awarding source. FPDS text arrives upper-cased, so federal titles usually are. Null when the source published none. Example: \"FACILITY HVAC MAINTENANCE SERVICES\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The federal Procurement Instrument Identifier for FPDS/SAM awards. Null for awards from sources that publish no PIID. Prefer `award_identifier`, which carries the same number for federal awards and a source-appropriate contract number elsewhere. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_identifier":{"description":"The user-facing contract number, source-agnostic (federal PIID, CanadaBuys contract number, ...). This is the number the Bidscope UI shows, falling back to `piid`. Null when the source published no contract number. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_active":{"description":"Tri-state contract status: true = active, false = expired, null = unknown (the source gave no dates to decide from). Rendered as the Active/Expired/Unknown badge. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"is_sole_source":{"description":"True when the contract was awarded without competition (sole source / non-competed). Null when the source published no competition information. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"is_vehicle":{"description":"True when this award is a contract vehicle (an indefinite-delivery vehicle such as a GSA schedule or IDIQ) that task orders are placed against, rather than a single ordinary contract. Task orders placed against it appear in `task_orders`. Null when unknown. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"response_count":{"description":"Number of offers the buyer received for this requirement (FPDS 'number of offers received'). Null when the source published none. Example: 4.","anyOf":[{"type":"number"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"min_amount_usd_cents":{"description":"Guaranteed floor of the contract's value range, in integer USD cents — typically the minimum order on an indefinite-delivery vehicle. Null when the source published no floor. Example: 250000 (i.e. $2,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"max_amount_usd_cents":{"description":"Ceiling of the contract's value range, in integer USD cents — the vehicle's not-to-exceed. Null when the source published no ceiling. When it equals `min_amount_usd_cents` the value is exact, not a range. Example: 5000000000 (i.e. $50,000,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded (signed). Null when the source published no date. Example: \"2026-03-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the period of performance. Null when the source published no date. Example: \"2026-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the period of performance, including exercised options — in the past for expired contracts. Null when the source published no date. Example: \"2029-03-31T00:00:00.000Z\"."},"vendor":{"description":"The vendor that won the contract. Null when the award has no linked vendor, and also when the linked vendor record is suppressed (ignored) in Bidscope.","anyOf":[{"type":"object","properties":{"id":{"description":"The awardee vendor's Bidscope id; pass it to `vendors.get`. Example: \"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63\".","type":"string"},"name":{"description":"The vendor's legal name, as registered. Null when only a display name is known. Example: \"NORTHWIND FACILITY SERVICES LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"pretty_name":{"description":"The vendor's cleaned-up display name — what the UI shows, preferring this over `name`. Null when Bidscope has not normalised one. Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"website_url":{"description":"The vendor's website, when Bidscope has found one. Null otherwise. Example: \"https://northwindfacility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"certifications":{"description":"Raw socio-economic certification / set-aside strings exactly as published by the vendor's registrations, un-normalised and possibly containing near-duplicates. Null when Bidscope has collected none. Example: [\"Woman Owned Small Business\", \"HUBZone\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"address":{"description":"The vendor's street address as published. Null when unknown. Example: \"1200 Wynkoop St Suite 400, Denver, CO 80202\".","anyOf":[{"type":"string"},{"type":"null"}]},"place_pretty_name":{"description":"Display name of the vendor's resolved location, from Bidscope's geocoded place record. Null when the address could not be resolved. Example: \"Denver, CO, USA\".","anyOf":[{"type":"string"},{"type":"null"}]},"contact_name":{"description":"The single primary contact name stored on the vendor record itself (distinct from the `people` list). Null when none. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"The vendor record's primary email address. Null when none. Example: \"contracts@northwindfacility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"description":"The vendor record's primary phone number, formatted as published. Null when none. Example: \"+1 303-555-0147\".","anyOf":[{"type":"string"},{"type":"null"}]},"people":{"description":"Up to 5 contacts at the awardee vendor, contacts with an email address first, then by name. `contact_count` carries the true total — large vendors can have hundreds, so use `vendors.get-contacts` to page through them all. Empty when Bidscope knows no contacts.","type":"array","items":{"type":"object","properties":{"id":{"description":"The contact's Bidscope person id. Example: \"f2a70c84-5d19-4e63-b0a7-8c1e5f2d9a30\".","type":"string"},"full_name":{"description":"The contact's name. Null when only an email or phone number is known. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_address":{"description":"The contact's email address. Null when unknown. Example: \"d.whitfield@northwindfacility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"description":"The contact's phone number. Null when unknown. Example: \"+1 303-555-0182\".","anyOf":[{"type":"string"},{"type":"null"}]},"email_validations":{"description":"Email-deliverability checks Bidscope has run for this contact, most useful as a freshness signal. Empty when the contact has no email address or has never been checked.","type":"array","items":{"type":"object","properties":{"id":{"description":"The validation record's id. Example: \"1b6d2f39-08c4-4a51-9e77-3d5b0a8c6f21\".","type":"string"},"email_address":{"description":"The address that was checked — matches the contact's `email_address`. Example: \"d.whitfield@northwindfacility.example.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"is_deliverable":{"description":"Result of the deliverability check: true = the address accepted mail, false = it did not. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"created_at":{"type":["string","null"],"format":"date-time","description":"When the check ran — deliverability decays, so treat old checks with suspicion. Example: \"2026-02-27T14:05:11.842Z\"."}},"required":["id","email_address","is_deliverable","created_at"],"additionalProperties":false}}},"required":["id","full_name","email_address","phone_number","email_validations"],"additionalProperties":false}},"contact_count":{"description":"Total number of contacts Bidscope knows for this vendor, before the 5-row cap on `people`. 0 when none are known. Example: 37.","type":"number"}},"required":["id","name","pretty_name","website_url","certifications","address","place_pretty_name","contact_name","email_address","phone_number","people","contact_count"],"additionalProperties":false},{"type":"null"}]},"buyer":{"description":"The awarding buyer — the first buyer recorded against the award, resolved to its consolidated tier. Null when the award has no buyer record at all. Awards can name several raw buyers; only this primary one is returned here.","anyOf":[{"type":"object","properties":{"id":{"description":"The consolidated buyer tier id; pass it to `buyers.get`. Null when the award's raw buyer has not been consolidated into the buyer hierarchy yet — in that case `name` is still populated from the raw record. Example: \"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14\".","anyOf":[{"type":"string"},{"type":"null"}]},"name":{"description":"The buyer's full hierarchy display name from the consolidated tier, falling back to the raw buyer's root name when unconsolidated. Example: \"General Services Administration > Public Buildings Service > Region 8\".","anyOf":[{"type":"string"},{"type":"null"}]},"root_type":{"description":"Level of government the buyer sits at, from its consolidated root. One of: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\", \"private\". Null when the buyer is unconsolidated. Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","root_type"],"additionalProperties":false},{"type":"null"}]},"place":{"description":"Place of performance for the contract. Null when the source published no location or it could not be geocoded.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"Display name of the place of performance, from Bidscope's geocoded place record. Example: \"Denver, CO, USA\".","anyOf":[{"type":"string"},{"type":"null"}]},"region":{"description":"State / province / first-level subdivision of the place of performance. Null when the place resolved only to a country. Example: \"Colorado\".","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"Country of the place of performance. Null when unresolved. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"data":{"description":"The raw geocoder payload for the place, used by the UI to draw a map. Shaped `{ geometry?: { coordinates?: [longitude, latitude] }, bbox?: number[] }` — note the GeoJSON longitude-first ordering. Null when the place was stored without geometry. Example: { \"geometry\": { \"coordinates\": [-104.9903, 39.7392] }, \"bbox\": [-105.1099, 39.6143, -104.6002, 39.9142] }."}},"required":["pretty_name","region","country","data"],"additionalProperties":false},{"type":"null"}]},"explicit_naics_code":{"description":"The NAICS industry code the awarding source attached to the contract record itself (FPDS publishes one). Null for sources that publish no NAICS — fall back to `inferred_naics_code`. Example: { \"code\": \"561210\", \"label\": \"Facilities Support Services\" }.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself — a 6-digit NAICS industry code, or a 4-character Product/Service Code (PSC). Example: \"561210\" (NAICS) or \"J041\" (PSC).","type":"string"},"label":{"description":"The official title of the code, from Bidscope's NAICS/PSC reference tables. An empty string when the code exists but carries no stored title. Example: \"Facilities Support Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"inferred_naics_code":{"description":"The NAICS code Bidscope's AI pipeline assigned from the contract text, on the award's latest inference. Only shown to users as \"inferred with AI\" when there is no explicit code. Null when the award has no inference yet, or the inference found no code. Example: { \"code\": \"561210\", \"label\": \"Facilities Support Services\" }.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself — a 6-digit NAICS industry code, or a 4-character Product/Service Code (PSC). Example: \"561210\" (NAICS) or \"J041\" (PSC).","type":"string"},"label":{"description":"The official title of the code, from Bidscope's NAICS/PSC reference tables. An empty string when the code exists but carries no stored title. Example: \"Facilities Support Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"explicit_psc_code":{"description":"The Product/Service Code the awarding source attached to the contract record itself. Null for sources that publish no PSC — fall back to `inferred_psc_code`. Example: { \"code\": \"J041\", \"label\": \"Maintenance, Repair and Rebuilding of Equipment: Refrigeration, Air Conditioning and Air Circulating Equipment\" }.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself — a 6-digit NAICS industry code, or a 4-character Product/Service Code (PSC). Example: \"561210\" (NAICS) or \"J041\" (PSC).","type":"string"},"label":{"description":"The official title of the code, from Bidscope's NAICS/PSC reference tables. An empty string when the code exists but carries no stored title. Example: \"Facilities Support Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"inferred_psc_code":{"description":"The PSC Bidscope's AI pipeline assigned from the contract text, on the award's latest inference. Null when the award has no inference yet, or the inference found no code. Example: { \"code\": \"J041\", \"label\": \"Maintenance, Repair and Rebuilding of Equipment: Refrigeration, Air Conditioning and Air Circulating Equipment\" }.","anyOf":[{"type":"object","properties":{"code":{"description":"The classification code itself — a 6-digit NAICS industry code, or a 4-character Product/Service Code (PSC). Example: \"561210\" (NAICS) or \"J041\" (PSC).","type":"string"},"label":{"description":"The official title of the code, from Bidscope's NAICS/PSC reference tables. An empty string when the code exists but carries no stored title. Example: \"Facilities Support Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"contract_period_months":{"description":"The contract's structure in months as read off the contract text by the AI pipeline: the first entry is the base period and each remaining entry is an option period. Null when the award has no inference or the structure could not be determined. Example: [12, 12, 12, 12] (a one-year base plus three one-year options).","anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]},"is_enduring_requirement":{"description":"AI judgement of whether the underlying need is ongoing and likely to be recompeted when this contract ends, rather than one-off. Null when the award has no inference. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"recompete_rationale":{"description":"The AI pipeline's prose reasoning behind `is_enduring_requirement` and the recompete timing estimate. Null when the award has no inference. Example: \"Recurring preventive maintenance across a fixed building portfolio; the agency has recompeted this scope every five years since 2011.\"","anyOf":[{"type":"string"},{"type":"null"}]},"solicitations":{"description":"The first page of up to 5 public opportunities linked to this award, newest link first (ordered by when Bidscope linked them, not by `date_posted`). Private opportunities belonging to an organization are never included. Empty when no opportunity has been linked — common for awards ingested from FPDS with no matching solicitation on record.","type":"array","items":{"type":"object","properties":{"rfp_id":{"description":"The linked opportunity's Bidscope id (`rfps.id`); pass it to `opportunities.get`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"title":{"description":"The opportunity's title — the latest AI inference's title, falling back to the raw title scraped from the source. Null only when neither exists. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"blurb":{"description":"A one-paragraph AI-written summary of the solicitation, from the latest inference. Null when the opportunity has not been through inference yet. Example: \"Recurring preventive maintenance and emergency repair of HVAC systems across twelve federal buildings in the Denver metro area.\"","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"Lifecycle state of the opportunity: \"open\" (still accepting responses) or \"closed\". Null for records whose source never published a state. Example: \"closed\".","anyOf":[{"type":"string"},{"type":"null"}]},"status_reason":{"description":"Why the opportunity reached its current `status`, when Bidscope recorded one — e.g. \"awarded\", \"cancelled\", \"pruned\". Null for most open opportunities. Example: \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"date_posted":{"type":["string","null"],"format":"date-time","description":"When the solicitation was published by the buyer, null when the source published no date. Example: \"2025-11-14T00:00:00.000Z\"."},"date_due":{"type":["string","null"],"format":"date-time","description":"The response deadline. Null when the source published none (or the solicitation has no deadline). Example: \"2025-12-19T21:00:00.000Z\"."},"solicitation_identifier":{"description":"The buyer's own solicitation number, as published. Null for sources that publish none. Example: \"47PM0125Q0031\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["rfp_id","title","blurb","status","status_reason","date_posted","date_due","solicitation_identifier"],"additionalProperties":false}},"solicitation_count":{"description":"Total number of linked public opportunities, before the 5-row cap on `solicitations`. 0 when none. Example: 12.","type":"number"},"solicitations_next_cursor":{"description":"Paging cursor for the rest of the linked opportunities — pass it as `cursor` to `awards.get-solicitations`. Null when `solicitation_count` is 5 or fewer, i.e. `solicitations` is already complete. Example: \"2026-05-02T18:41:07.212Z\".","anyOf":[{"type":"string"},{"type":"null"}]},"parent":{"description":"The contract vehicle this award was placed against, when this award is a task order. Null for standalone contracts and for vehicles themselves.","anyOf":[{"type":"object","properties":{"id":{"description":"The parent vehicle's Bidscope award id; pass it back to `awards.get`. Example: \"4a9c2e70-8b31-4f56-9d02-7e6b1a4c8f39\".","type":"string"},"title":{"description":"The parent vehicle's title, null when its source published none. Example: \"MULTIPLE AWARD SCHEDULE — FACILITIES\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The parent vehicle's contract identifier, null when its source published none. Example: \"47QSMD30R0001\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","piid"],"additionalProperties":false},{"type":"null"}]},"task_orders":{"description":"Task orders placed against this award when it acts as a contract vehicle — the 50 largest by awarded value (ties broken by most recent award date). `task_order_count` carries the true total, which can run into the tens of thousands for a government-wide schedule. Empty for ordinary standalone contracts and for task orders themselves.","type":"array","items":{"type":"object","properties":{"id":{"description":"The task order's Bidscope award id; pass it back to `awards.get`. Example: \"0e5b8c21-9d47-4a03-b6f8-1c2d7e9a4b50\".","type":"string"},"piid":{"description":"The task order's contract identifier, null when its source published none. Example: \"47PM0125F0042\".","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"description":"The task order's title, null when its source published none. Example: \"REGION 8 HVAC PREVENTIVE MAINTENANCE — FY26\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"The task order's awarded value in integer USD cents, null when its source published no value. Example: 41200000 (i.e. $412,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the task order was awarded, null when its source published no date. Example: \"2026-04-02T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the task order's period of performance, null when its source published no date. Example: \"2027-04-01T00:00:00.000Z\"."},"is_active":{"description":"Tri-state status of the task order: true = active, false = expired, null = unknown. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","piid","title","award_value_cents","date_awarded","date_ended","is_active"],"additionalProperties":false}},"task_order_count":{"description":"Total number of task orders placed against this award, before the 50-row cap on `task_orders`. 0 when it is not a vehicle. Example: 318.","type":"number"},"phases":{"description":"The contract's full transaction ledger — the base award plus every modification (option exercises, funding actions, de-obligations, administrative changes). Ordered newest signed first (`date_signed` descending, nulls last, then modification number descending), and NOT capped. Empty for awards from sources that publish no transaction history; federal FPDS awards always have at least the base transaction.","type":"array","items":{"type":"object","properties":{"usfed_mod_number":{"description":"The federal modification number for this transaction. An empty string or \"0\" identifies the base award itself; anything else is a modification. Example: \"P00003\".","anyOf":[{"type":"string"},{"type":"null"}]},"usfed_transaction_number":{"description":"The federal transaction number, which disambiguates multiple transactions sharing a modification number. Example: \"0\".","anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"description":"The source's reason-for-modification code/text. Null on the base award and where the source published none. Example: \"EXERCISE AN OPTION\".","anyOf":[{"type":"string"},{"type":"null"}]},"obligation_usd_cents":{"description":"Funds obligated (or de-obligated, hence possibly negative) by this transaction, in integer USD cents. Null when the source published no amount. Summing this column across `phases` gives total funds obligated to date, which differs from `award_value_cents` (the contract's awarded value). Example: 41200000 (i.e. $412,000.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_signed":{"type":["string","null"],"format":"date-time","description":"When this transaction was signed — the primary ordering key of the ledger. Null when the source published no date. Example: \"2027-03-28T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the period of performance as of this transaction. Null when the source published no date. Example: \"2027-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the period of performance as of this transaction — this is how an exercised option extends the contract. Null when the source published no date. Example: \"2028-03-31T00:00:00.000Z\"."},"description":{"description":"Free-text description of the transaction from the source; the UI joins it with `reason`. Null when the source published none. Example: \"EXERCISE OPTION YEAR 2\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["usfed_mod_number","usfed_transaction_number","reason","obligation_usd_cents","date_signed","date_started","date_ended","description"],"additionalProperties":false}}},"required":["id","title","piid","award_identifier","is_active","is_sole_source","is_vehicle","response_count","award_value_cents","min_amount_usd_cents","max_amount_usd_cents","date_awarded","date_started","date_ended","vendor","buyer","place","explicit_naics_code","inferred_naics_code","explicit_psc_code","inferred_psc_code","contract_period_months","is_enduring_requirement","recompete_rationale","solicitations","solicitation_count","solicitations_next_cursor","parent","task_orders","task_order_count","phases"],"additionalProperties":false}},"required":["award"],"additionalProperties":false},"examples":[{"title":"A contract vehicle with task orders","description":"`is_vehicle` is true and `task_orders` lists the largest of `task_order_count` children. `explicit_naics_code` is present (FPDS published it), so a consumer should prefer it over `inferred_naics_code`. `solicitation_count` exceeds the 5 embedded rows, so `solicitations_next_cursor` is set — feed it to `awards.get-solicitations`.","request":{"id":"4a9c2e70-8b31-4f56-9d02-7e6b1a4c8f39"},"response":{"award":{"id":"4a9c2e70-8b31-4f56-9d02-7e6b1a4c8f39","title":"MULTIPLE AWARD SCHEDULE — FACILITIES","piid":"47QSMD30R0001","award_identifier":"47QSMD30R0001","is_active":true,"is_sole_source":false,"is_vehicle":true,"response_count":11,"award_value_cents":null,"min_amount_usd_cents":250000,"max_amount_usd_cents":5000000000,"date_awarded":"2024-09-30T00:00:00.000Z","date_started":"2024-10-01T00:00:00.000Z","date_ended":"2029-09-30T00:00:00.000Z","vendor":{"id":"7c3e9a15-6b28-4d70-91af-2f5c8d0e4b63","name":"NORTHWIND FACILITY SERVICES LLC","pretty_name":"Northwind Facility Services LLC","website_url":"https://northwindfacility.example.com","certifications":["Woman Owned Small Business","HUBZone"],"address":"1200 Wynkoop St Suite 400, Denver, CO 80202","place_pretty_name":"Denver, CO, USA","contact_name":"Dana Whitfield","email_address":"contracts@northwindfacility.example.com","phone_number":"+1 303-555-0147","people":[{"id":"f2a70c84-5d19-4e63-b0a7-8c1e5f2d9a30","full_name":"Dana Whitfield","email_address":"d.whitfield@northwindfacility.example.com","phone_number":"+1 303-555-0182","email_validations":[{"id":"1b6d2f39-08c4-4a51-9e77-3d5b0a8c6f21","email_address":"d.whitfield@northwindfacility.example.com","is_deliverable":true,"created_at":"2026-02-27T14:05:11.842Z"}]},{"id":"9a4c1e56-2f80-4d37-b915-6e0d8b3a7c42","full_name":"Marcus Ohlsen","email_address":null,"phone_number":"+1 303-555-0190","email_validations":[]}],"contact_count":37},"buyer":{"id":"6d0f4c92-1a85-4b37-9e60-5c2a7d8f3b14","name":"General Services Administration > Federal Acquisition Service","root_type":"federal"},"place":{"pretty_name":"Denver, CO, USA","region":"Colorado","country":"United States","data":{"geometry":{"coordinates":[-104.9903,39.7392]},"bbox":[-105.1099,39.6143,-104.6002,39.9142]}},"explicit_naics_code":{"code":"561210","label":"Facilities Support Services"},"inferred_naics_code":{"code":"561210","label":"Facilities Support Services"},"explicit_psc_code":{"code":"J041","label":"Maintenance, Repair and Rebuilding of Equipment: Refrigeration, Air Conditioning and Air Circulating Equipment"},"inferred_psc_code":null,"contract_period_months":[12,12,12,12,12],"is_enduring_requirement":true,"recompete_rationale":"Recurring preventive maintenance across a fixed building portfolio; the agency has recompeted this scope every five years since 2011.","solicitations":[{"rfp_id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","title":"Facility HVAC Maintenance Services","blurb":"Recurring preventive maintenance and emergency repair of HVAC systems across twelve federal buildings in the Denver metro area.","status":"closed","status_reason":"awarded","date_posted":"2025-11-14T00:00:00.000Z","date_due":"2025-12-19T21:00:00.000Z","solicitation_identifier":"47PM0125Q0031"},{"rfp_id":"5b1d9e07-3c42-4a88-9f30-2e7c6d4b1a95","title":"Chiller Replacement — Building 4","blurb":null,"status":"closed","status_reason":"awarded","date_posted":"2025-09-02T00:00:00.000Z","date_due":"2025-10-07T20:00:00.000Z","solicitation_identifier":"47PM0125Q0018"}],"solicitation_count":12,"solicitations_next_cursor":"2026-05-02T18:41:07.212Z","parent":null,"task_orders":[{"id":"0e5b8c21-9d47-4a03-b6f8-1c2d7e9a4b50","piid":"47PM0125F0042","title":"REGION 8 HVAC PREVENTIVE MAINTENANCE — FY26","award_value_cents":41200000,"date_awarded":"2026-04-02T00:00:00.000Z","date_ended":"2027-04-01T00:00:00.000Z","is_active":true},{"id":"2c7f4b93-6a18-4e50-8d72-9b3e1c5a0d64","piid":"47PM0124F0117","title":"REGION 8 CHILLER OVERHAUL","award_value_cents":18750000,"date_awarded":"2025-02-19T00:00:00.000Z","date_ended":"2026-02-18T00:00:00.000Z","is_active":false}],"task_order_count":318,"phases":[{"usfed_mod_number":"P00003","usfed_transaction_number":"0","reason":"EXERCISE AN OPTION","obligation_usd_cents":41200000,"date_signed":"2027-03-28T00:00:00.000Z","date_started":"2027-04-01T00:00:00.000Z","date_ended":"2028-03-31T00:00:00.000Z","description":"EXERCISE OPTION YEAR 2"},{"usfed_mod_number":"0","usfed_transaction_number":"0","reason":null,"obligation_usd_cents":25000000,"date_signed":"2024-09-30T00:00:00.000Z","date_started":"2024-10-01T00:00:00.000Z","date_ended":"2025-09-30T00:00:00.000Z","description":null}]}}},{"title":"An ordinary standalone award","description":"Not a vehicle and not a task order: `is_vehicle` is false, `parent` is null and `task_orders` is empty. This source published no NAICS/PSC of its own, so only the inferred codes are populated — that is the case where the UI labels the codes 'inferred with AI'. With 1 linked solicitation, `solicitations_next_cursor` is null and no follow-up paging call is needed.","request":{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34"},"response":{"award":{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Citywide Traffic Signal Maintenance","piid":null,"award_identifier":"PW-2026-0114","is_active":true,"is_sole_source":false,"is_vehicle":false,"response_count":3,"award_value_cents":128450000,"min_amount_usd_cents":null,"max_amount_usd_cents":null,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2026-04-01T00:00:00.000Z","date_ended":"2029-03-31T00:00:00.000Z","vendor":{"id":"e83b0d47-51c9-4f26-9a70-4d2f8c6b1e35","name":"CASCADE SIGNAL SYSTEMS INC","pretty_name":"Cascade Signal Systems Inc","website_url":null,"certifications":null,"address":"88 SE Ankeny St, Portland, OR 97214","place_pretty_name":"Portland, OR, USA","contact_name":null,"email_address":"bids@cascadesignal.example.com","phone_number":"+1 503-555-0126","people":[],"contact_count":0},"buyer":{"id":"a1c6e284-0b73-4d95-8e12-7f4a3c5d9b60","name":"City of Portland > Bureau of Transportation","root_type":"city"},"place":{"pretty_name":"Portland, OR, USA","region":"Oregon","country":"United States","data":{"geometry":{"coordinates":[-122.6765,45.5231]}}},"explicit_naics_code":null,"inferred_naics_code":{"code":"237310","label":"Highway, Street, and Bridge Construction"},"explicit_psc_code":null,"inferred_psc_code":{"code":"J099","label":"Maintenance, Repair and Rebuilding of Equipment: Miscellaneous"},"contract_period_months":[12,12,12],"is_enduring_requirement":true,"recompete_rationale":"Signal maintenance is a continuous municipal obligation; the bureau has rebid this scope on a three-year cycle.","solicitations":[{"rfp_id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","title":"Citywide Traffic Signal Maintenance","blurb":"Three-year contract for preventive and corrective maintenance of approximately 1,100 signalized intersections.","status":"closed","status_reason":"awarded","date_posted":"2025-12-08T00:00:00.000Z","date_due":"2026-01-23T20:00:00.000Z","solicitation_identifier":"PBOT-2026-114"}],"solicitation_count":1,"solicitations_next_cursor":null,"parent":null,"task_orders":[],"task_order_count":0,"phases":[]}}}]}]},{"procedure":"awards.get-solicitations","versions":[{"version":"2026-07-05","description":"Pages through the opportunities (solicitations) linked to a contract award. One record is one linked opportunity. Pages are 5 rows, ordered by when Bidscope linked the opportunity to the award, newest first; only public opportunities are included. Omit `cursor` for the first page — that page is identical to the `award.solicitations` array `awards.get` embeds, so callers that already have the details payload should start from its `award.solicitations_next_cursor` instead. Keep passing the returned `nextCursor` until it comes back null, which marks the final page. An unknown or non-existent `awardId` returns an empty list with `nextCursor: null` rather than a 404; a malformed (non-uuid) `awardId` is rejected as a request validation error, and unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"awardId":{"description":"The award's Bidscope id (`awards.id`, as returned by `awards.search` as `\"awards.id\"`). Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"cursor":{"description":"Opaque paging cursor — pass the previous page's `nextCursor`, or `award.solicitations_next_cursor` from `awards.get`. Omit it to get the first page (the same 5 rows `awards.get` embeds). Its value is the ISO timestamp of the last returned link row, and rows strictly older than it are returned. Example: \"2026-05-02T18:41:07.212Z\".","type":"string"}},"required":["awardId"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"solicitations":{"description":"One page of up to 5 opportunities linked to the award, newest link first (ordered by when Bidscope linked the opportunity to the award, not by `date_posted`). Only public opportunities are returned — private opportunities belonging to an organization are never surfaced here. Empty when the award has no (further) linked opportunities, and also when `awardId` matches no award — this endpoint does not 404.","type":"array","items":{"type":"object","properties":{"rfp_id":{"description":"The linked opportunity's Bidscope id (`rfps.id`); pass it to `opportunities.get`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"title":{"description":"The opportunity's title — the latest AI inference's title, falling back to the raw title scraped from the source. Null only when neither exists. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"blurb":{"description":"A one-paragraph AI-written summary of the solicitation, from the latest inference. Null when the opportunity has not been through inference yet. Example: \"Recurring preventive maintenance and emergency repair of HVAC systems across twelve federal buildings in the Denver metro area.\"","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"Lifecycle state of the opportunity: \"open\" (still accepting responses) or \"closed\". Null for records whose source never published a state. Example: \"closed\".","anyOf":[{"type":"string"},{"type":"null"}]},"status_reason":{"description":"Why the opportunity reached its current `status`, when Bidscope recorded one — e.g. \"awarded\", \"cancelled\", \"pruned\". Null for most open opportunities. Example: \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"date_posted":{"type":["string","null"],"format":"date-time","description":"When the solicitation was published by the buyer, null when the source published no date. Example: \"2025-11-14T00:00:00.000Z\"."},"date_due":{"type":["string","null"],"format":"date-time","description":"The response deadline. Null when the source published none (or the solicitation has no deadline). Example: \"2025-12-19T21:00:00.000Z\"."},"solicitation_identifier":{"description":"The buyer's own solicitation number, as published. Null for sources that publish none. Example: \"47PM0125Q0031\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["rfp_id","title","blurb","status","status_reason","date_posted","date_due","solicitation_identifier"],"additionalProperties":false}},"nextCursor":{"description":"Pass back as `cursor` to fetch the next page. Null on the final page (fewer than 5 further rows exist). Example: \"2026-05-02T18:41:07.212Z\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["solicitations","nextCursor"],"additionalProperties":false},"examples":[{"title":"Second page of a heavily-linked vehicle's solicitations","description":"Called with the `solicitations_next_cursor` returned by `awards.get`. A full page of 5 comes back with a non-null `nextCursor`, meaning more remain.","request":{"awardId":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","cursor":"2026-05-02T18:41:07.212Z"},"response":{"solicitations":[{"rfp_id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","title":"Facility HVAC Maintenance Services","blurb":"Recurring preventive maintenance and emergency repair of HVAC systems across twelve federal buildings in the Denver metro area.","status":"closed","status_reason":"awarded","date_posted":"2025-11-14T00:00:00.000Z","date_due":"2025-12-19T21:00:00.000Z","solicitation_identifier":"47PM0125Q0031"},{"rfp_id":"5b1d9e07-3c42-4a88-9f30-2e7c6d4b1a95","title":"Chiller Replacement — Building 4","blurb":"Removal and replacement of two 400-ton centrifugal chillers, including controls integration and commissioning.","status":"closed","status_reason":"awarded","date_posted":"2025-09-02T00:00:00.000Z","date_due":"2025-10-07T20:00:00.000Z","solicitation_identifier":"47PM0125Q0018"},{"rfp_id":"8d2c4f16-9a05-4e73-b118-6f3a2d9c7e04","title":"Boiler Inspection and Preventive Maintenance","blurb":null,"status":"closed","status_reason":null,"date_posted":"2025-07-21T00:00:00.000Z","date_due":"2025-08-15T20:00:00.000Z","solicitation_identifier":"47PM0125Q0009"},{"rfp_id":"a4e8b301-72d6-4c19-8f52-0b9d3e6a1c78","title":"Emergency Generator Service — Region 8","blurb":"Quarterly load-bank testing and corrective maintenance for standby generators at eight Region 8 facilities.","status":"closed","status_reason":"awarded","date_posted":"2025-06-03T00:00:00.000Z","date_due":"2025-07-01T20:00:00.000Z","solicitation_identifier":"47PM0125Q0004"},{"rfp_id":"c9f1a527-4b60-4d38-9e21-7a5c8b2d0f43","title":"Building Automation System Upgrade","blurb":"Replacement of legacy pneumatic controls with a native BACnet building automation system.","status":"closed","status_reason":"cancelled","date_posted":"2025-04-18T00:00:00.000Z","date_due":null,"solicitation_identifier":"47PM0125Q0002"}],"nextCursor":"2025-04-19T09:12:33.480Z"}},{"title":"Final page","description":"The last two links come back and `nextCursor` is null — stop paging. `blurb` is null on opportunities that have not been through AI inference.","request":{"awardId":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","cursor":"2025-04-19T09:12:33.480Z"},"response":{"solicitations":[{"rfp_id":"d6b3c840-1f57-4e92-8a0c-3d5b7e1f9024","title":"Cooling Tower Water Treatment","blurb":null,"status":"closed","status_reason":"awarded","date_posted":"2025-02-10T00:00:00.000Z","date_due":"2025-03-11T21:00:00.000Z","solicitation_identifier":"47PM0124Q0117"},{"rfp_id":"e07a5219-8c34-4bd6-9f70-2a1e6c4d3b85","title":null,"blurb":null,"status":"closed","status_reason":null,"date_posted":"2025-01-22T00:00:00.000Z","date_due":null,"solicitation_identifier":"47PM0124Q0103"}],"nextCursor":null}}]}]},{"procedure":"buyers.search","versions":[{"version":"2026-07-05","description":"The scored buyer directory: buyer tiers ranked by how closely what they purchase matches one of your matching profiles. Each record is one tier in the consolidated buyer hierarchy — anything from a cabinet department to a single contracting office — and `\"buyerTiers.name_pretty\"` gives its full root-first hierarchy path rather than its bare name. There are two regimes. Ordering by \"score\" (with a profile that has a centroid) ranks buyers by semantic match and then tops up the page with unscored buyers, and `total` is -1 because the nearest-neighbour ranking cannot be counted. Ordering by any other column pages the full buyer universe with the score attached where one exists, and `total` is a real count unless `skipCountTotal` was set. `score` runs from just above 0 to 1 and is null — not 0 — for buyers with no nearby record, including every buyer when the profile has no centroid. Passing `search.filterMeta.naicsCodes` (up to 100 codes) restricts results to buyers with at least one record under those codes anywhere in their subtree, and sets `naics_exists` to true on every returned row; with no codes it is null on every row. Paging is capped at 1000 results in total, after which the response is `{ total: 0, items: [] }`. Returns 404 when the matching profile does not exist, 403 when it belongs to another organization, and 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile whose embedding centroid ranks the buyers. Must belong to your organization or the call is rejected with 403. A profile with no centroid yet is accepted, but then every row scores null and the results fall back to name ordering. Example: \"2b7f1e04-9c86-4d53-a0f7-6e3b8d5c1420\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query state. `orderBy` is one of \"score\", \"buyerTiers.name_pretty\" (the full hierarchy path), \"buyerTiers.buyer_roots.root_type\", \"buyerTiers.buyer_roots.is_coop\", or \"buyerTiers.id\"; `sort` is \"asc\" or \"desc\"; `pageSize` must be one of 1, 10, 25, 50, or 100; `filters` is a filter tree (or null) whose `column` values are those same names; `quickSearch` is an optional case-insensitive substring matched against the full hierarchy path; `filterMeta` is an open key/value record, and the key this endpoint reads is `naicsCodes` (an array of up to 100 NAICS code strings, max 10 chars each) which restricts results to buyers with at least one matching record in their subtree. Ordering by \"score\" with a profile that has a centroid selects the ranked regime (see the procedure description); anything else pages the full buyer universe. Example: { orderBy: \"score\", sort: \"desc\", pageSize: 10, filters: null }.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["buyerTiers.name_pretty","buyerTiers.buyer_roots.root_type","buyerTiers.buyer_roots.is_coop","score","buyerTiers.id"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"The 1-based page number. `page` * `search.pageSize` is capped at 1000 results overall: once the requested window starts beyond that cap the response is `{ total: 0, items: [] }`, and a page straddling it is truncated. Example: 1.","type":"number","minimum":1},"skipCountTotal":{"description":"Set true to skip the count that computes `total`, which is faster on broad queries; `total` then comes back as -1. Ignored under score ordering, where `total` is -1 regardless. Defaults to false. Example: false.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"The number of buyers matching the query across all pages, or -1 when that count is unavailable — which is the case both under score ordering (the nearest-neighbour ranking precludes a count) and whenever `skipCountTotal` was true. Under attribute ordering without `skipCountTotal` it is a real count. Also returned as 0 alongside an empty `items` when the requested page begins past the 1000-result cap. Example: -1.","type":"number"},"items":{"description":"One record per buyer tier — a node in the consolidated hierarchy, which may be a whole department or a single contracting office. At most `search.pageSize` records. Under score ordering the ranked buyers come first and any remaining room on the page is topped up with unscored buyers (`score` null) in name order; under attribute ordering the page is a plain slice of the full buyer universe. Empty past the end of the results or past the 1000-result cap.","type":"array","items":{"type":"object","properties":{"buyerTiers.id":{"description":"The buyer tier's Bidscope id — pass it to `buyers.get`, `buyers.get-children`, `buyers.get-rfps`, `buyers.get-awards`, or `buyers.get-contacts`. Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string"},"buyerTiers.name_pretty":{"description":"The buyer's FULL hierarchy path, root first, joined with \" > \" — despite the field name this is not the tier's bare name, so mid-tree tiers read unambiguously. (Use `buyers.get` if you need just this level's name.) It is what `quickSearch` and the `\"buyerTiers.name_pretty\"` filter match against. Null only when the tier has no stored path. Example: \"United States of America > VETERANS AFFAIRS, DEPARTMENT OF > Veterans Health Administration\".","anyOf":[{"type":"string"},{"type":"null"}]},"buyerTiers.buyer_roots.root_type":{"description":"The level of government (or sector) of the buyer's root, shared by every tier in the hierarchy. One of: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\" (transit, toll roads, ports, airports, bridges, ferries, parking), \"utility\" (water, sewer, electric, sanitation, flood control), \"housing\" (public housing authorities), \"healthcare\" (hospital districts, public health), \"community\" (fire, libraries, parks, recreation, cemeteries, stadiums, convention facilities), or \"private\". Null when the tier has no root linked or the root was never classified. Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"buyerTiers.buyer_roots.is_coop":{"description":"True when the buyer's root is a cooperative purchasing organization — one whose contracts other public agencies can buy from. Null means never classified, which is distinct from false; filtering with `enum.eq` matches the exact value and excludes nulls, while `enum.neq` includes them. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"naics_exists":{"description":"Whether a NAICS restriction was applied. True on EVERY returned row when `search.filterMeta.naicsCodes` was non-empty — because the codes restrict the result set, so surviving rows necessarily match — and null on every row when no codes were supplied. It is never false, and it does not vary row to row. Example: null.","anyOf":[{"type":"boolean"},{"type":"null"}]},"score":{"description":"How closely what this buyer purchases matches the matching profile, from just above 0 to 1 (1 being a perfect match). Derived by taking the records nearest the profile's centroid, attributing each to its buyer tier and to every ancestor tier, then combining the buyer's single best record distance with a small capped bonus for how many distinct on-topic records it has — so breadth can break near-ties but cannot outweigh a stronger best match. Because credit rolls up the hierarchy, a parent scores at least as well as its best descendant. Null (not 0) when no nearby record links to the buyer's subtree at all, and null for every buyer when the matching profile has no centroid yet. Example: 0.87.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["buyerTiers.id","buyerTiers.name_pretty","buyerTiers.buyer_roots.root_type","buyerTiers.buyer_roots.is_coop","naics_exists","score"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Top-matching buyers for a matching profile","description":"The default ranked view: order by \"score\" descending. `total` is -1 because the ranking cannot be counted, and `naics_exists` is null because no NAICS restriction was applied. The last row scores null — it is an unscored buyer topping up the page, and it sorts after every scored one.","request":{"matchingProfileId":"2b7f1e04-9c86-4d53-a0f7-6e3b8d5c1420","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1},"response":{"total":-1,"items":[{"buyerTiers.id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13","buyerTiers.name_pretty":"United States of America > VETERANS AFFAIRS, DEPARTMENT OF > Veterans Health Administration","buyerTiers.buyer_roots.root_type":"federal","buyerTiers.buyer_roots.is_coop":false,"naics_exists":null,"score":0.87},{"buyerTiers.id":"c4a80f27-6b13-4e95-8d2a-7f0c5e1b39d6","buyerTiers.name_pretty":"City of Austin","buyerTiers.buyer_roots.root_type":"city","buyerTiers.buyer_roots.is_coop":false,"naics_exists":null,"score":0.62},{"buyerTiers.id":"9f31d8a6-2c74-4b05-8e19-6a0c3f7b2d58","buyerTiers.name_pretty":"State of Oregon > Department of Administrative Services","buyerTiers.buyer_roots.root_type":"state","buyerTiers.buyer_roots.is_coop":null,"naics_exists":null,"score":null}]}},{"title":"Restricting to specific NAICS codes, sorted by name","description":"Two things differ from the first example. `search.filterMeta.naicsCodes` keeps only buyers with a matching record somewhere in their subtree, which is why `naics_exists` is true on every row. And ordering by \"buyerTiers.name_pretty\" instead of \"score\" switches to the attribute regime, so `total` is a real count — the scores are still attached where the profile has a nearby record.","request":{"matchingProfileId":"2b7f1e04-9c86-4d53-a0f7-6e3b8d5c1420","search":{"orderBy":"buyerTiers.name_pretty","sort":"asc","pageSize":10,"filters":{"type":"filter","column":"buyerTiers.buyer_roots.root_type","filter":{"operator":"enum.eq","value":"city"}},"filterMeta":{"naicsCodes":["236220","238220"]},"quickSearch":"austin"},"page":1},"response":{"total":2,"items":[{"buyerTiers.id":"c4a80f27-6b13-4e95-8d2a-7f0c5e1b39d6","buyerTiers.name_pretty":"City of Austin","buyerTiers.buyer_roots.root_type":"city","buyerTiers.buyer_roots.is_coop":false,"naics_exists":true,"score":0.62},{"buyerTiers.id":"6d20b4f9-8e17-4c53-a9b0-3f5e1d8c7204","buyerTiers.name_pretty":"City of Austin > Austin Water Utility Purchasing","buyerTiers.buyer_roots.root_type":"city","buyerTiers.buyer_roots.is_coop":false,"naics_exists":true,"score":null}]}}]}]},{"procedure":"buyers.get","versions":[{"version":"2026-07-05","description":"A single buyer tier: its own name, the root its hierarchy hangs off (level of government via `root.rootType`, cooperative flag via `root.isCoop`), its location, and the ancestor breadcrumb. Buyers are consolidated — many raw buyer names scraped from solicitations collapse into one canonical tier — and those tiers form a tree (department -> sub-agency -> contracting office) linked by `parentBuyerTierId`. Note that `namePretty` is only this level's name; `ancestry` is the full root-first path and always ends with the buyer itself, so it is never empty (a root-level buyer returns exactly one entry). Use `buyers.get-children` to walk down, and `buyers.get-rfps` / `get-awards` / `get-contacts` for the buyer's activity across its whole subtree. Returns 404 when no buyer tier has the given id, and 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id (`buyer_tiers.id`, as returned by `buyers.search` as `\"buyerTiers.id\"`). Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"buyer":{"description":"The requested buyer tier — one node in the consolidated buyer hierarchy, with its root attributes, location, and breadcrumb.","type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id — echoes the requested `id`. Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string"},"namePretty":{"description":"The buyer's own display name at this level only, NOT the full hierarchy path — use `ancestry` to build a breadcrumb. (Contrast `buyers.search`, whose `\"buyerTiers.name_pretty\"` is the whole path.) Example: \"Veterans Health Administration\".","type":"string"},"parentBuyerTierId":{"description":"The id of this buyer's immediate parent tier, or null when this tier is the top of its hierarchy (a root-level buyer, e.g. \"United States of America\" for US federal buyers). Equals the second-to-last entry of `ancestry` when non-null. Example: \"3d1f8c05-b472-4e69-8a10-5f2c7b9d4e83\".","anyOf":[{"type":"string"},{"type":"null"}]},"root":{"description":"The root of this buyer's hierarchy, carrying the attributes that apply to every tier beneath it (`rootType`, `isCoop`). Null in the rare case that the tier has no `buyer_root_id` set — typically a tier still awaiting consolidation.","anyOf":[{"type":"object","properties":{"id":{"description":"The `buyer_roots` id shared by every tier in this buyer's hierarchy. Example: \"0f5a2c81-9d34-4b07-a6e2-8c1b3f7d509a\".","type":"string"},"rootType":{"description":"The level of government (or sector) the whole hierarchy belongs to, carried on the root rather than on this tier. One of: \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\" (transit, toll roads, ports, airports, bridges, ferries, parking), \"utility\" (water, sewer, electric, sanitation, flood control), \"housing\" (public housing authorities), \"healthcare\" (hospital districts, public health), \"community\" (fire, libraries, parks, recreation, cemeteries, stadiums, convention facilities), or \"private\". Null when the root was created without a classification. Example: \"federal\".","anyOf":[{"type":"string"},{"type":"null"}]},"isCoop":{"description":"True when the root is a cooperative purchasing organization — one that awards contracts other public agencies can buy from. Null when the root has never been classified (treat null as unknown, not as false). Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","rootType","isCoop"],"additionalProperties":false},{"type":"null"}]},"place":{"description":"Where the buyer is located, resolved from the tier's linked place. Null when the tier has no place linked, or when the linked place has no name, no point, and no boundary — so a non-null `place` always carries at least one of `prettyName`, `latitude`/`longitude`, or `geometryGeojson`.","anyOf":[{"type":"object","properties":{"prettyName":{"description":"Human-readable name of the place, null when the linked place row has none. Example: \"Austin, Texas, United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"Country of the place, null when unknown. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"region":{"description":"First-level subdivision (US state or equivalent), null when unknown or when the place is country-level. Example: \"Texas\".","anyOf":[{"type":"string"},{"type":"null"}]},"latitude":{"description":"Latitude in decimal degrees (WGS84) of the place's representative point, null when the place has no point geometry. Example: 30.267153.","anyOf":[{"type":"number"},{"type":"null"}]},"longitude":{"description":"Longitude in decimal degrees (WGS84) of the place's representative point, null when the place has no point geometry. Example: -97.743061.","anyOf":[{"type":"number"},{"type":"null"}]},"geometryGeojson":{"description":"The place's boundary as a GeoJSON geometry object (typically a Polygon or MultiPolygon), for drawing the buyer's service area on a map. Null when the place has no boundary geometry — many places carry only a point. Example: { \"type\": \"Polygon\", \"coordinates\": [[[-97.94, 30.09], [-97.56, 30.09], [-97.56, 30.52], [-97.94, 30.52], [-97.94, 30.09]]] }."}},"required":["prettyName","country","region","latitude","longitude","geometryGeojson"],"additionalProperties":false},{"type":"null"}]},"ancestry":{"description":"The full breadcrumb from the root down to and INCLUDING the buyer itself, outermost first — the last entry is always the requested buyer. It is therefore never empty: a root-level buyer returns a single entry (itself), and a buyer nested N levels deep returns N+1 entries. Join the `namePretty` values with \" > \" to reproduce the hierarchy path that `buyers.search` returns as `\"buyerTiers.name_pretty\"`.","type":"array","items":{"type":"object","properties":{"id":{"description":"The ancestor tier's Bidscope id; pass it to `buyers.get` to open that level. Example: \"3d1f8c05-b472-4e69-8a10-5f2c7b9d4e83\".","type":"string"},"namePretty":{"description":"That level's own display name. Example: \"VETERANS AFFAIRS, DEPARTMENT OF\".","type":"string"}},"required":["id","namePretty"],"additionalProperties":false}}},"required":["id","namePretty","parentBuyerTierId","root","place","ancestry"],"additionalProperties":false}},"required":["buyer"],"additionalProperties":false},"examples":[{"title":"A nested federal sub-agency","description":"A tier two levels below the federal root, so `ancestry` has three entries ending with the buyer itself, and `parentBuyerTierId` matches the second-to-last one. US federal buyers all hang off the \"United States of America\" root.","request":{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13"},"response":{"buyer":{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13","namePretty":"Veterans Health Administration","parentBuyerTierId":"3d1f8c05-b472-4e69-8a10-5f2c7b9d4e83","root":{"id":"0f5a2c81-9d34-4b07-a6e2-8c1b3f7d509a","rootType":"federal","isCoop":false},"place":{"prettyName":"United States","country":"United States","region":null,"latitude":39.78373,"longitude":-100.445882,"geometryGeojson":null},"ancestry":[{"id":"1a7b4e92-c063-4d18-95f7-0b8e2a4d6c31","namePretty":"United States of America"},{"id":"3d1f8c05-b472-4e69-8a10-5f2c7b9d4e83","namePretty":"VETERANS AFFAIRS, DEPARTMENT OF"},{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13","namePretty":"Veterans Health Administration"}]}}},{"title":"A root-level city buyer with boundary geometry","description":"A tier at the top of its own hierarchy: `parentBuyerTierId` is null and `ancestry` contains only the buyer itself — one entry, not zero. Local buyers usually carry a real place with both a point and a boundary polygon.","request":{"id":"c4a80f27-6b13-4e95-8d2a-7f0c5e1b39d6"},"response":{"buyer":{"id":"c4a80f27-6b13-4e95-8d2a-7f0c5e1b39d6","namePretty":"City of Austin","parentBuyerTierId":null,"root":{"id":"8b2e6d09-4f71-4a3c-b58e-0d9a1c7f2e64","rootType":"city","isCoop":false},"place":{"prettyName":"Austin, Texas, United States","country":"United States","region":"Texas","latitude":30.267153,"longitude":-97.743061,"geometryGeojson":{"type":"Polygon","coordinates":[[[-97.94,30.09],[-97.56,30.09],[-97.56,30.52],[-97.94,30.52],[-97.94,30.09]]]}},"ancestry":[{"id":"c4a80f27-6b13-4e95-8d2a-7f0c5e1b39d6","namePretty":"City of Austin"}]}}}]}]},{"procedure":"buyers.get-children","versions":[{"version":"2026-07-05","description":"The direct child tiers of a buyer — one level down the consolidated buyer hierarchy, used to walk the tree (e.g. department -> sub-agency -> contracting office). Each record is one child buyer tier. Unlike the other buyer sub-resource endpoints, this covers only the immediate children, not the whole subtree, and it is unpaginated — all direct children are returned. Ordered by last-consolidated-at descending, then name ascending. There is no 404: an unknown id and a leaf tier both return an empty `children` array. Returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The parent buyer tier's Bidscope id (`buyer_tiers.id`, as returned by `buyers.search` as `\"buyerTiers.id\"`). Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"children":{"description":"The buyer's DIRECT child tiers only (one level down — tiers whose `parent_buyer_tier_id` is the requested id); it does not recurse into grandchildren. Ordered by when Bidscope last consolidated each child (most recently consolidated first), then by name ascending — so this is NOT alphabetical order. Not paginated: every direct child is returned. Empty for a leaf tier (a buyer with no sub-buyers), and also empty when the requested id does not exist.","type":"array","items":{"type":"object","properties":{"id":{"description":"The child tier's Bidscope id; pass it back to `buyers.get`, `buyers.get-children`, or any of the buyer sub-resource endpoints to walk further down the tree. Example: \"e0b47f13-6a25-4d88-b3c9-71f5e8a20d46\".","type":"string"},"namePretty":{"description":"The child tier's own display name — just this level, NOT the full hierarchy path (unlike `buyers.search`'s `\"buyerTiers.name_pretty\"`, which returns the whole path). Example: \"Veterans Health Administration\".","type":"string"}},"required":["id","namePretty"],"additionalProperties":false}}},"required":["children"],"additionalProperties":false},"examples":[{"title":"Sub-agencies of a federal department","description":"Walking down from a department-level tier. Each `id` can be passed straight back into `buyers.get-children` to descend another level.","request":{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13"},"response":{"children":[{"id":"e0b47f13-6a25-4d88-b3c9-71f5e8a20d46","namePretty":"Veterans Health Administration"},{"id":"a91c53e8-7d20-4f6b-8e14-2c9b0d5a3f71","namePretty":"National Cemetery Administration"},{"id":"72f0d6b4-1e83-4a95-b70c-8d3f5e19c2a0","namePretty":"Veterans Benefits Administration"}]}},{"title":"A leaf tier has no children","description":"A contracting office at the bottom of the hierarchy. An empty array means the tier is a leaf — it is not an error, and it is indistinguishable from passing an id that does not exist.","request":{"id":"b6e39a41-05cd-4732-9a8f-1d47e6b02c95"},"response":{"children":[]}}]}]},{"procedure":"buyers.get-rfps","versions":[{"version":"2026-07-05","description":"Recent opportunities (solicitations) issued by a buyer and ALL of its sub-buyers — the subtree, not just the tier itself, so a department-level id includes every office beneath it. Each record is one opportunity. Returns at most 10, ordered newest-first by when Bidscope recorded them (`createdAt`, not `datePosted`), regardless of open/closed status; `hasMore` is true when the subtree holds more than those 10. There is no paging on this endpoint — use `opportunities.search` to page through a buyer's full history. `title` prefers the AI-extracted title over the raw scraped one, and `blurb` comes only from the latest inference, so it is null for opportunities not yet inferred. There is no 404: an unknown buyer id returns an empty list. Returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id (`buyer_tiers.id`, as returned by `buyers.search` as `\"buyerTiers.id\"`). Opportunities are collected across this tier AND every tier beneath it, so passing a department returns its offices' solicitations too. Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rfps":{"description":"Up to 10 opportunities issued anywhere in the buyer's subtree — the buyer itself plus all of its descendant tiers, resolved through the buyer hierarchy's transitive closure. Ordered newest `createdAt` first (regardless of open/closed status). This endpoint has no paging (there is no cursor or page parameter) — use `opportunities.search` filtered by buyer to go deeper. Empty when the subtree has no opportunities, and also empty when the requested id does not exist.","type":"array","items":{"type":"object","properties":{"id":{"description":"The opportunity's Bidscope id (`rfps.id`); pass it to `opportunities.get` or `opportunities.get-awards`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"createdAt":{"type":"string","format":"date-time","description":"When Bidscope first recorded the opportunity — this is the recency used for ordering, NOT `datePosted`. Always present. Example: \"2026-06-28T14:05:22.117Z\"."},"datePosted":{"type":["string","null"],"format":"date-time","description":"When the issuing agency published the solicitation, as reported by the source; null when the source published no post date. May differ from `createdAt`, which is when Bidscope saw it. Example: \"2026-06-27T00:00:00.000Z\"."},"dateDue":{"type":["string","null"],"format":"date-time","description":"The response deadline as reported by the source; null when none was published or none could be extracted. A due date in the past does not by itself mean `status` is closed. Example: \"2026-08-15T21:00:00.000Z\"."},"status":{"description":"Bidscope's lifecycle state for the solicitation. \"open\" means still accepting responses and is what sorts first in this list; other values (e.g. \"closed\") sort after. Always present. Example: \"open\".","type":"string"},"statusReason":{"description":"Why the opportunity reached its current `status` — typically only set once it leaves \"open\" (e.g. awarded, cancelled, deadline passed). Null while the opportunity is open or when no reason was recorded. Example: \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"description":"The solicitation title, preferring the AI-extracted title from the latest inference and falling back to the raw title scraped from the source. Null only when neither exists. Example: \"Regional Medical Center HVAC Replacement\".","anyOf":[{"type":"string"},{"type":"null"}]},"blurb":{"description":"A short AI-generated summary of the solicitation, taken from the latest inference. Null when the opportunity has not been through inference yet (freshly collected opportunities commonly have a `title` but no `blurb`). Example: \"Replacement of four rooftop HVAC units at the regional medical center, including removal, installation, and one year of maintenance.\"","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","createdAt","datePosted","dateDue","status","statusReason","title","blurb"],"additionalProperties":false}},"hasMore":{"description":"True when the buyer's subtree has more than the 10 returned opportunities. It only signals that more exist — this endpoint cannot return them. Example: true.","type":"boolean"}},"required":["rfps","hasMore"],"additionalProperties":false},"examples":[{"title":"A large department with more opportunities than fit on one page","description":"Records come back strictly newest-first by `createdAt`, regardless of open/closed status — which is why the most recently recorded record (a closed, already-awarded solicitation) leads. `hasMore` is true, so the subtree holds more than these 10.","request":{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13"},"response":{"rfps":[{"id":"d5e18b74-2a90-4c63-bf05-6e7a3d1c9482","createdAt":"2026-07-02T11:18:47.005Z","datePosted":"2026-04-14T00:00:00.000Z","dateDue":"2026-05-30T20:00:00.000Z","status":"closed","statusReason":"awarded","title":"Medical Gas System Inspection and Certification","blurb":"Annual inspection and NFPA 99 certification of medical gas systems across twelve facilities."},{"id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","createdAt":"2026-06-28T14:05:22.117Z","datePosted":"2026-06-27T00:00:00.000Z","dateDue":"2026-08-15T21:00:00.000Z","status":"open","statusReason":null,"title":"Regional Medical Center HVAC Replacement","blurb":"Replacement of four rooftop HVAC units at the regional medical center, including removal, installation, and one year of maintenance."},{"id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","createdAt":"2026-06-21T09:41:03.882Z","datePosted":"2026-06-20T00:00:00.000Z","dateDue":null,"status":"open","statusReason":null,"title":"Janitorial Services — Outpatient Clinics","blurb":null}],"hasMore":true}},{"title":"A buyer with no recorded opportunities","description":"A small office tier that Bidscope knows from contract awards but has never seen issue a solicitation. An empty list is not an error — the same response comes back for an id that does not exist at all.","request":{"id":"b6e39a41-05cd-4732-9a8f-1d47e6b02c95"},"response":{"rfps":[],"hasMore":false}}]}]},{"procedure":"buyers.get-awards","versions":[{"version":"2026-07-05","description":"Contract award history for a buyer and ALL of its sub-buyers — the subtree, not just the tier itself, so a department-level id includes every office beneath it. Each record is one awarded contract, active or expired. Returns at most 10, ordered newest first by the award's effective date (the earliest of `date_awarded`, `date_started`, and when Bidscope recorded it), with awards lacking all three sorting last. Searched over the buyer's full history at any subtree size, including the largest federal departments. `hasMore` is true when more than those 10 were found, but this endpoint has no paging — use `awards.search` to go deeper. There is no 404: an unknown buyer id returns an empty list. Returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id (`buyer_tiers.id`, as returned by `buyers.search` as `\"buyerTiers.id\"`). Awards are collected across this tier AND every tier beneath it, so passing a department returns its offices' contracts too. Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"awards":{"description":"Up to 10 contract awards made anywhere in the buyer's subtree — the buyer itself plus all of its descendant tiers. Ordered newest first by the award's effective date, defined as the EARLIEST of `date_awarded`, `date_started`, and the date Bidscope recorded it; awards missing all three sort last. This is full award history: both active and expired contracts are included. Searched over the buyer's entire history at any subtree size. Empty when the subtree has no awards, and also empty when the requested id does not exist.","type":"array","items":{"type":"object","properties":{"id":{"description":"The award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract's title as reported by the awarding source, null when the source published none. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The awarding agency's contract identifier (the federal Procurement Instrument Identifier for FPDS/SAM awards), null for sources that publish none — commonly null on state and local awards. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_name":{"description":"Display name of the vendor that won the contract, resolved from the award's linked vendor record. Null when the award has no linked vendor, or when the linked vendor is flagged to be ignored. Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded, as reported by the source; null when the source published no award date. Example: \"2026-06-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the contract's period of performance, null when the source published none. Example: \"2026-07-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the contract's period of performance — in the past for expired contracts, and a useful recompete signal when it is in the near future. Null when the source published none. Example: \"2029-06-30T00:00:00.000Z\"."}},"required":["id","title","piid","vendor_name","award_value_cents","date_awarded","date_started","date_ended"],"additionalProperties":false}},"hasMore":{"description":"True when more than the 10 returned awards were found. This endpoint has no paging — use `awards.search` filtered by buyer to go deeper. Example: true.","type":"boolean"}},"required":["awards","hasMore"],"additionalProperties":false},"examples":[{"title":"Recent contracts across a department's subtree","description":"Awards made by offices beneath the requested tier, newest effective date first. `piid` and `award_value_cents` come from the awarding source, so either can be null — typically on non-federal awards.","request":{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13"},"response":{"awards":[{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Facility HVAC Maintenance Services","piid":"47QRAA24D008K","vendor_name":"Northwind Facility Services LLC","award_value_cents":128450000,"date_awarded":"2026-06-11T00:00:00.000Z","date_started":"2026-07-01T00:00:00.000Z","date_ended":"2029-06-30T00:00:00.000Z"},{"id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","title":"Medical Gas System Inspection and Certification","piid":"36C24926D0117","vendor_name":"Cascade Compliance Group Inc","award_value_cents":8730000,"date_awarded":"2026-05-29T00:00:00.000Z","date_started":"2026-06-15T00:00:00.000Z","date_ended":"2027-06-14T00:00:00.000Z"},{"id":"f38b5c62-9a04-4d71-8e3f-2b6c1a7d0954","title":"Grounds Maintenance — Outpatient Clinics","piid":null,"vendor_name":null,"award_value_cents":null,"date_awarded":"2026-05-04T00:00:00.000Z","date_started":null,"date_ended":null}],"hasMore":true}},{"title":"A buyer with no awards on record","description":"A tier Bidscope knows only from solicitations. An empty list is not an error — the same response comes back for an id that does not exist.","request":{"id":"b6e39a41-05cd-4732-9a8f-1d47e6b02c95"},"response":{"awards":[],"hasMore":false}}]}]},{"procedure":"buyers.get-contacts","versions":[{"version":"2026-07-05","description":"The people named as contacts (contracting officers, procurement staff, and similar) on opportunities and contract awards belonging to a buyer and ALL of its sub-buyers — the subtree, not just the tier itself. Each record is one person, deduplicated across every record they appear on, so the list is people rather than appearances. Both solicitation contacts and award contacts are included. Returns at most 10, ordered by `lastSeenAt` descending — the time Bidscope most recently linked that person to a record in the subtree, which reflects when the appearance was recorded rather than any date published by the source. `hasMore` is true when more exist; this endpoint has no paging, so use `buyer-contacts.search` to go deeper. `fullName`, `emailAddress`, and `phoneNumber` are each independently nullable because they are extracted from source documents that may publish only some of them. There is no 404: an unknown buyer id returns an empty list. Returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id (`buyer_tiers.id`, as returned by `buyers.search` as `\"buyerTiers.id\"`). Contacts are collected across this tier AND every tier beneath it, so passing a department returns its offices' contacts too. Example: \"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"contacts":{"description":"Up to 10 people named as contacts on opportunities OR contract awards anywhere in the buyer's subtree — the buyer itself plus all of its descendant tiers. Deduplicated per person: someone appearing on many records is returned once, with `lastSeenAt` set to their most recent appearance. Ordered by `lastSeenAt` descending, so the currently-active procurement staff lead. Empty when no contacts have been extracted for the subtree, and also empty when the requested id does not exist.","type":"array","items":{"type":"object","properties":{"id":{"description":"The person's Bidscope id (`people.id`); pass it to `buyer-contacts.get`. One id per person, not per appearance — a contact named on many solicitations appears once here. Example: \"7e2c9b41-8d05-4a37-b16f-3c0e5d8a2947\".","type":"string"},"fullName":{"description":"The contact's name as extracted from the solicitation or award document. Null when only an email address or phone number could be extracted. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailAddress":{"description":"The contact's email address as published on the source document, null when none was published or extracted. Example: \"d.whitfield@example-agency.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"description":"The contact's phone number as published on the source document — formatting is whatever the source used and is not normalized, so it may include an extension. Null when none was published or extracted. Example: \"(555) 014-2287 x310\".","anyOf":[{"type":"string"},{"type":"null"}]},"lastSeenAt":{"type":"string","format":"date-time","description":"The most recent time Bidscope linked this person to any opportunity or award in the buyer's subtree — i.e. when the appearance was recorded, NOT a date published by the source. This is the value the list is ordered by. Always present. Example: \"2026-07-09T16:33:41.204Z\"."}},"required":["id","fullName","emailAddress","phoneNumber","lastSeenAt"],"additionalProperties":false}},"hasMore":{"description":"True when more than the 10 returned people are linked to the buyer's subtree. This endpoint has no paging — use `buyer-contacts.search` to go deeper. Example: true.","type":"boolean"}},"required":["contacts","hasMore"],"additionalProperties":false},"examples":[{"title":"Active contacts for a department's subtree","description":"Most recently seen first. The third record shows the common partial case — an email published with no name attached.","request":{"id":"5c8d1a70-3e94-4b21-9f68-0a7e2d4c6b13"},"response":{"contacts":[{"id":"7e2c9b41-8d05-4a37-b16f-3c0e5d8a2947","fullName":"Dana Whitfield","emailAddress":"d.whitfield@example-agency.gov","phoneNumber":"(555) 014-2287 x310","lastSeenAt":"2026-07-09T16:33:41.204Z"},{"id":"1c6f0a83-4b27-4e59-9d31-8a5e2c7b0d64","fullName":"Marcus Elleby","emailAddress":null,"phoneNumber":"555-014-9930","lastSeenAt":"2026-06-30T08:12:55.671Z"},{"id":"a48d3e05-7f91-4c26-b0a8-5e1d9c4f2367","fullName":null,"emailAddress":"contracts.office@example-agency.gov","phoneNumber":null,"lastSeenAt":"2026-06-18T13:47:09.338Z"}],"hasMore":true}},{"title":"A buyer with no extracted contacts","description":"Common for buyers whose sources publish solicitations without named points of contact. An empty list is not an error — the same response comes back for an id that does not exist.","request":{"id":"b6e39a41-05cd-4732-9a8f-1d47e6b02c95"},"response":{"contacts":[],"hasMore":false}}]}]},{"procedure":"buyer-contacts.search","versions":[{"version":"2026-07-05","description":"Search buyer contacts — people named on government opportunities and contract awards (contracting officers, procurement staff, program contacts) — ranked against a matching profile. One row is one person, plus the buyer organization they are attributed to. That attribution is derived per row, not stored: contacts carry no employer in the data model, so `people.buyer_roots.*` is the root organization occurring most often across the records they are named on (ties broken by most recent), and it is display-only — you can filter by buyer but not sort by it. Ranking is score-only: `search.orderBy` accepts nothing but `\"score\"`, so there is no alphabetical or recency ordering available on this endpoint. Scored contacts come first in score order, then unscored contacts (score null) top up the page in id order. `total` is always -1 — the ranking makes a count impossible, so page until a page comes back short; paging is capped at 1000 results, past which you get an empty page with `total: 0`. Passing `search.filterMeta.naicsCodes` (up to 100 codes, each at most 10 characters) restricts results to contacts named on at least one opportunity or award carrying one of those codes, and sets `naics_exists` to true on every returned row; with no codes selected `naics_exists` is null everywhere. Returns 404 when the matching profile does not exist, 403 when it belongs to another organization, and 500 on an unexpected error (including a malformed `filterMeta.naicsCodes`).","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile whose embedding centroid ranks the results. Must belong to the calling organization (403 otherwise, 404 when no such profile exists). A profile with no centroid yet still returns results, but every `score` is null and rows come back in id order rather than ranked. Example: \"7f1e0a26-3b95-4c8d-90a4-6d2f8e51c073\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query state. `orderBy` accepts only `\"score\"` — the ~106k-contact universe cannot be sorted by attribute server-side, so name/email/phone are filterable but never sortable, and `sort` (\"asc\" | \"desc\") only reverses the score ranking. `pageSize` must be one of 1, 10, 25, 50 or 100. `filters` is a filter tree (or null) over `people.full_name`, `people.email_address`, `people.phone_number`, `people.id`, `score`, and the two buyer columns `people.buyer.id` / `people.buyer_roots.id` — both of which match any contact appearing on a record under that buyer tier OR any of its descendants, so passing a root id scopes to a whole organization. A malformed buyer uuid matches nothing rather than erroring. `quickSearch` is a case-insensitive substring match against full name OR email address. `filterMeta` is a free-form object; this endpoint reads only `filterMeta.naicsCodes` (see the procedure description).","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["score"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number; the window is `pageSize` rows starting at `pageSize * (page - 1)`. Paging stops at 1000 results total: once the offset reaches that cap the response is an empty page with `total: 0`, and the page straddling it is truncated. Example: 1.","type":"number","minimum":1},"skipCountTotal":{"description":"Accepted for parity with the other search endpoints and ignored here — this search can never compute a total, so `total` is -1 either way. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Always -1: the score ranking precludes a window count and counting the unscored universe would mean probing every contact link, so the match count is genuinely unknown — do not render it, and page until `items` comes back short. The one exception is 0, returned with an empty `items` when `page` is entirely past the 1000-result cap. Example: -1.","type":"number"},"items":{"description":"One row per buyer contact, ranked by `score` descending (ascending when `sort` is \"asc\"), with unscored contacts appended after the scored ones in id order. A short page means the end of the results — `total` cannot tell you.","type":"array","items":{"type":"object","properties":{"people.id":{"description":"The contact's Bidscope id (a `people` row id); pass it to `buyer-contacts.get`, `get-rfps`, `get-awards` and `get-buyers`. Example: \"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12\".","type":"string"},"people.full_name":{"description":"The person's name as published on the records they were named on. Null for nameless contacts — shared or generic office inboxes are recorded as contacts with an email but no name — in which case the email or phone is the only human-readable identifier. Example: \"Jordan Avery\".","anyOf":[{"type":"string"},{"type":"null"}]},"people.email_address":{"description":"The contact email published with the records, null when only a name and/or phone was published. Deliverability is not represented here — fetch `buyer-contacts.get` for the validation record. Example: \"jordan.avery@example.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"people.phone_number":{"description":"The contact phone number as published, in the source's own format (extensions included, no normalization). Null when none was published. Example: \"(555) 010-4477 x218\".","anyOf":[{"type":"string"},{"type":"null"}]},"people.buyer_roots.id":{"description":"Id of the ROOT BUYER TIER of the contact's attributed organization (`buyer_tiers.id` of the tier with no parent), suitable for `buyers.get`. Despite the column name it is a tier id, not a `buyer_roots` id. Null when none of the contact's records have been attributed to a consolidated buyer yet. Example: \"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49\".","anyOf":[{"type":"string"},{"type":"null"}]},"people.buyer_roots.name":{"description":"Display name of that attributed root organization (the root tier's name — `buyer_roots` rows carry no name of their own). Derived per row, not stored: it is the root that occurs most often across the contact's linked records, ties broken by the most recent link, so a contact who appears under several agencies shows only their dominant one. Null whenever `people.buyer_roots.id` is null. Example: \"City of Springfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"people.buyer_roots.root_type":{"description":"Government level / sector of the attributed root organization. One of \"federal\", \"state\", \"county\", \"city\", \"tribal\", \"k12\", \"higher-ed\", \"transportation\", \"utility\", \"housing\", \"healthcare\", \"community\" or \"private\". Null when there is no attributed root, or when the root was never typed. Example: \"city\".","anyOf":[{"type":"string"},{"type":"null"}]},"people.buyer_roots.is_coop":{"description":"True when the attributed root is a cooperative purchasing organization (buying on behalf of member agencies) rather than a single agency. Null when there is no attributed root or the flag was never set. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]},"naics_exists":{"description":"Whether the NAICS restriction is in force, not a per-row match signal: true on every row when `search.filterMeta.naicsCodes` was non-empty (the restriction already removed non-matching contacts), and null on every row when no codes were selected. Never false. Example: null.","anyOf":[{"type":"boolean"},{"type":"null"}]},"score":{"description":"How well this contact's records match the matching profile, from 0 to 1 — derived from the closest of the profile's nearest-neighbour candidate records that the contact is named on, with a small bonus for appearing on several close records. Null when no candidate record links to this contact (render it as \"-\", not 0%); the profile having no centroid makes it null for every row. Example: 0.83.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["people.id","people.full_name","people.email_address","people.phone_number","people.buyer_roots.id","people.buyer_roots.name","people.buyer_roots.root_type","people.buyer_roots.is_coop","naics_exists","score"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Top-ranked contacts for a matching profile","description":"A plain first page: no filters, ranked by score descending. The second row is unscored — no record in the profile's candidate set links to that contact — so it appears below the scored rows with `score: null`, and it is a nameless shared inbox, hence the null `people.full_name`. `naics_exists` is null on every row because no NAICS codes were selected, and `total` is -1 as always.","request":{"matchingProfileId":"7f1e0a26-3b95-4c8d-90a4-6d2f8e51c073","page":1,"search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null}},"response":{"total":-1,"items":[{"people.id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12","people.full_name":"Jordan Avery","people.email_address":"jordan.avery@example.gov","people.phone_number":"(555) 010-4477 x218","people.buyer_roots.id":"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49","people.buyer_roots.name":"City of Springfield","people.buyer_roots.root_type":"city","people.buyer_roots.is_coop":false,"naics_exists":null,"score":0.83},{"people.id":"a41b7e03-6c25-4f9a-8d30-2b5e1c7f4a99","people.full_name":null,"people.email_address":"purchasing@example.gov","people.phone_number":null,"people.buyer_roots.id":null,"people.buyer_roots.name":null,"people.buyer_roots.root_type":null,"people.buyer_roots.is_coop":null,"naics_exists":null,"score":null}]}},{"title":"Restricted to NAICS codes and one buyer organization","description":"`filterMeta.naicsCodes` keeps only contacts named on a record carrying 236220 or 237310, which is why `naics_exists` is true on the row — it reports that the restriction is active, not that this particular row matched better than another. The `people.buyer_roots.id` filter matches any contact appearing under that root's whole subtree, and `quickSearch` substring-matches name or email. Note `score` is still the only ordering available.","request":{"matchingProfileId":"7f1e0a26-3b95-4c8d-90a4-6d2f8e51c073","page":1,"search":{"orderBy":"score","sort":"desc","pageSize":10,"quickSearch":"avery","filters":{"type":"filter","column":"people.buyer_roots.id","filter":{"operator":"string.eq","value":"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49"}},"filterMeta":{"naicsCodes":["236220","237310"]}},"skipCountTotal":true},"response":{"total":-1,"items":[{"people.id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12","people.full_name":"Jordan Avery","people.email_address":"jordan.avery@example.gov","people.phone_number":"(555) 010-4477 x218","people.buyer_roots.id":"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49","people.buyer_roots.name":"City of Springfield","people.buyer_roots.root_type":"city","people.buyer_roots.is_coop":false,"naics_exists":true,"score":0.79}]}}]}]},{"procedure":"buyer-contacts.get","versions":[{"version":"2026-07-05","description":"One buyer contact: a person named on government solicitations and/or contract awards (contracting officer, procurement analyst, program contact), plus their email-deliverability check when one exists. Buyer contacts are extracted from the records themselves, so a contact carries no employer field — use `buyer-contacts.get-buyers` for the agencies they appear under, and `get-rfps`/`get-awards` for the records they are named on. `emailValidation` is null for most contacts (validation is only run selectively). Returns 404 when no person with that id exists, and 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer contact's Bidscope id — a `people` row id, as returned by `buyer-contacts.search` as `\"people.id\"`. Example: \"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"contact":{"type":"object","properties":{"id":{"description":"The contact's Bidscope id (echoes the requested `id`); use it with `buyer-contacts.get-rfps`, `get-awards` and `get-buyers`. Example: \"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12\".","type":"string"},"fullName":{"description":"The person's name as published on the solicitation or award documents they were named on. Null for nameless records — shared or generic office inboxes (e.g. a \"purchasing@\" address) are recorded as contacts with an email but no name. Example: \"Jordan Avery\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailAddress":{"description":"The contact email published with the record, null when the source listed only a name and/or phone number. Not verified by this field alone — see `emailValidation`. Example: \"jordan.avery@example.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"description":"The contact phone number as published, in whatever format the source used (no normalization, extensions included). Null when the source listed none. Example: \"(555) 010-4477 x218\".","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","description":"When Bidscope first recorded this person (`people.created_at`), not when the agency employed or published them. Example: \"2025-11-02T14:23:51.884Z\"."},"emailValidation":{"description":"The stored email-deliverability check for this contact's address (one per address at most — `email_validations` is keyed by lowercased email address). Null whenever no check has been run for the address, which is the common case: validation is run selectively, so most contacts have no record here. A null `emailValidation` says nothing about whether the address works.","anyOf":[{"type":"object","properties":{"emailAddress":{"description":"The address that was actually checked. Normally identical to the contact's `emailAddress`; it can differ if the contact's address was later corrected or re-normalized after the check ran. Example: \"jordan.avery@example.gov\".","anyOf":[{"type":"string"},{"type":"null"}]},"isDeliverable":{"description":"Result of the deliverability check: true when the mailbox accepted verification, false when it was rejected (bad mailbox, dead domain, hard bounce). Null only for a stored check that recorded no verdict — treat null as unknown, not as undeliverable. Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the deliverability check ran. Deliverability decays, so an old timestamp means a stale verdict. Example: \"2026-01-17T09:41:02.117Z\"."}},"required":["emailAddress","isDeliverable","createdAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","fullName","emailAddress","phoneNumber","createdAt","emailValidation"],"additionalProperties":false}},"required":["contact"],"additionalProperties":false},"examples":[{"title":"A named contracting officer with a verified email","description":"The common fully-populated case: name, email, phone, plus a deliverability check that came back deliverable. Note `emailValidation.createdAt` is when the check ran, while the outer `createdAt` is when Bidscope first saw the person.","request":{"id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12"},"response":{"contact":{"id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12","fullName":"Jordan Avery","emailAddress":"jordan.avery@example.gov","phoneNumber":"(555) 010-4477 x218","createdAt":"2025-11-02T14:23:51.884Z","emailValidation":{"emailAddress":"jordan.avery@example.gov","isDeliverable":true,"createdAt":"2026-01-17T09:41:02.117Z"}}}},{"title":"A nameless shared inbox with no validation on file","description":"Generic office inboxes are recorded as contacts too: `fullName` and `phoneNumber` are null because the record published only an address. `emailValidation: null` means no check has been run — it is not evidence the address is bad.","request":{"id":"a41b7e03-6c25-4f9a-8d30-2b5e1c7f4a99"},"response":{"contact":{"id":"a41b7e03-6c25-4f9a-8d30-2b5e1c7f4a99","fullName":null,"emailAddress":"purchasing@example.gov","phoneNumber":null,"createdAt":"2026-04-28T03:12:09.402Z","emailValidation":null}}}]}]},{"procedure":"buyer-contacts.get-rfps","versions":[{"version":"2026-07-05","description":"Opportunities a buyer contact is named on — the solicitations whose contact details include this person. Returns at most 10 rows, open opportunities first and then newest-recorded first, with `hasMore` set when further records exist; there is no paging. `title`/`blurb` come from the opportunity's latest inference (`title` falls back to the crawled title). For contacts with an unusually large number of links (generic shared inboxes can carry tens of thousands), the underlying scan is windowed to the person's most recent links, so the result is a recency-bounded approximation rather than an exhaustive list. Unknown ids are not an error: they return an empty list, not a 404. Returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer contact's Bidscope id (a `people` row id, as returned by `buyer-contacts.search` as `\"people.id\"`). Example: \"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rfps":{"description":"Up to 10 opportunities the contact is named on, ordered open-first and then newest `createdAt` first (ties broken by id) — so this is a recency list, not a deadline list. Empty when the contact is named only on awards, or when no person with the given id exists (this endpoint does not 404).","type":"array","items":{"type":"object","properties":{"id":{"description":"The opportunity's Bidscope id (`rfps.id`); pass it to `opportunities.get`. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","type":"string"},"createdAt":{"type":"string","format":"date-time","description":"When Bidscope first recorded the opportunity, not when the agency posted it (see `datePosted`). This is the field the list is sorted by within each status group. Example: \"2026-05-14T18:02:44.301Z\"."},"datePosted":{"type":["string","null"],"format":"date-time","description":"When the agency published the solicitation, as reported by the source. Null when the source published no posting date. Example: \"2026-05-14T00:00:00.000Z\"."},"dateDue":{"type":["string","null"],"format":"date-time","description":"The response deadline as reported by the source. Null when no deadline was published — which is also why a row can still be `status: \"open\"` long after it is stale. Example: \"2026-06-30T21:00:00.000Z\"."},"status":{"description":"Lifecycle state of the opportunity. One of \"open\" (still accepting responses as far as Bidscope knows) or \"closed\". Open rows sort ahead of closed ones. Example: \"open\".","type":"string"},"statusReason":{"description":"Short free-text reason attached when the opportunity was closed. Null for open opportunities. Set automatically to \"past due\" (deadline elapsed) or \"expired\" (no deadline, and stale since posting), otherwise a 1-3 word reason derived from the solicitation documents. Example: \"awarded\".","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"description":"The opportunity title, preferring the title from the latest inference over the raw crawled `rfps.title`. Null only when neither carries one. Example: \"Citywide Fleet Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"blurb":{"description":"One-line AI summary of the solicitation, taken from the latest inference. Null when the opportunity has no current inference yet (newly crawled) or the inference produced none — note this is independent of `title`, which falls back to the crawled title. Example: \"Annual preventive maintenance and repair for the city's light-duty vehicle fleet.\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","createdAt","datePosted","dateDue","status","statusReason","title","blurb"],"additionalProperties":false}},"hasMore":{"description":"True when the contact is named on more than the 10 opportunities returned. There is no paging here — use `opportunities.search` filtered by the contact's buyer to go deeper. Example: true.","type":"boolean"}},"required":["rfps","hasMore"],"additionalProperties":false},"examples":[{"title":"A contracting officer's recent solicitations","description":"The open opportunity sorts ahead of the closed one even though the closed one was recorded later. `statusReason` is null while open, and `blurb` is null on the row whose latest inference produced no summary.","request":{"id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12"},"response":{"rfps":[{"id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","createdAt":"2026-05-14T18:02:44.301Z","datePosted":"2026-05-14T00:00:00.000Z","dateDue":"2026-06-30T21:00:00.000Z","status":"open","statusReason":null,"title":"Citywide Fleet Maintenance Services","blurb":"Annual preventive maintenance and repair for the city's light-duty vehicle fleet."},{"id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","createdAt":"2026-06-02T07:55:10.220Z","datePosted":"2026-06-01T00:00:00.000Z","dateDue":"2026-06-20T17:00:00.000Z","status":"closed","statusReason":"awarded","title":"Emergency Generator Replacement — Public Works Yard","blurb":null}],"hasMore":true}},{"title":"A contact named only on awards","description":"An empty page. The same shape is returned for an id that does not exist — this endpoint never 404s, so check `buyer-contacts.get` if you need to distinguish the two.","request":{"id":"a41b7e03-6c25-4f9a-8d30-2b5e1c7f4a99"},"response":{"rfps":[],"hasMore":false}}]}]},{"procedure":"buyer-contacts.get-awards","versions":[{"version":"2026-07-05","description":"Contract awards a buyer contact is named on — the contracts whose award records list this person (contracting officer, contract specialist, etc.). Returns at most 10 awards, newest first by effective date (the earliest of `date_awarded`, `date_started` and the record's creation date), with `hasMore` set when further awards exist; there is no paging. Awards flagged inactive are omitted. For contacts with an unusually large number of links — generic shared inboxes can carry tens of thousands of award links — the underlying scan is windowed to the person's most recent links, so the result is a recency-bounded approximation rather than an exhaustive list. Unknown ids are not an error: they return an empty list, not a 404. Returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer contact's Bidscope id (a `people` row id, as returned by `buyer-contacts.search` as `\"people.id\"`). Example: \"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"awards":{"description":"Up to 10 contract awards the contact is named on, newest first by the award's effective date — the earliest of `date_awarded`, `date_started` and the record's creation date — with nulls last and ties broken by id. Inactive awards are excluded. Empty when the contact is named only on opportunities, or when no person with the given id exists (this endpoint does not 404).","type":"array","items":{"type":"object","properties":{"id":{"description":"The award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract's title as reported by the awarding source, null when the source published none. Example: \"Light-Duty Fleet Maintenance — Base Year\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The awarding agency's contract identifier (the federal Procurement Instrument Identifier for FPDS/SAM awards), null for sources that publish none. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_name":{"description":"Display name of the vendor that won the contract, taken from the linked vendor record. Null when the award has no linked vendor, or when the linked vendor is suppressed from display. Example: \"Northwind Facility Services LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded, as reported by the source. Null when the source published no award date. Example: \"2026-03-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the contract's period of performance, null when the source published none. Example: \"2026-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the contract's period of performance — in the past for expired contracts, null when the source published none. Example: \"2029-03-31T00:00:00.000Z\"."}},"required":["id","title","piid","vendor_name","award_value_cents","date_awarded","date_started","date_ended"],"additionalProperties":false}},"hasMore":{"description":"True when the contact is named on more than the 10 awards returned. There is no paging here — use `awards.search` to go deeper. Example: true.","type":"boolean"}},"required":["awards","hasMore"],"additionalProperties":false},"examples":[{"title":"Recent contracts a contracting officer is named on","description":"Two contracts under the same vehicle. `piid` and `award_value_cents` come from the awarding source, so either can be null on non-federal awards — as on the second row, where the agency published no dollar value.","request":{"id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12"},"response":{"awards":[{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Light-Duty Fleet Maintenance — Base Year","piid":"47QRAA24D008K","vendor_name":"Northwind Facility Services LLC","award_value_cents":128450000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2026-04-01T00:00:00.000Z","date_ended":"2029-03-31T00:00:00.000Z"},{"id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","title":"Emergency Generator Replacement","piid":null,"vendor_name":"Cascade Power Systems Inc.","award_value_cents":null,"date_awarded":"2025-12-04T00:00:00.000Z","date_started":null,"date_ended":null}],"hasMore":true}},{"title":"A contact named only on open solicitations","description":"An empty page. The same shape is returned for an id that does not exist — this endpoint never 404s, so check `buyer-contacts.get` if you need to distinguish the two.","request":{"id":"a41b7e03-6c25-4f9a-8d30-2b5e1c7f4a99"},"response":{"awards":[],"hasMore":false}}]}]},{"procedure":"buyer-contacts.get-buyers","versions":[{"version":"2026-07-05","description":"The buyer organizations a contact appears under, as a flat buyer-tier tree. People carry no employer field in Bidscope — affiliation is derived from the records they are named on, so a tier is `isLinked: true` when at least one of the contact's opportunities or awards was solicited/awarded under it. Ancestor tiers are added with `isLinked: false` purely so every returned row is reachable from a root; nest the rows by `parentBuyerTierId` (root rows have a null parent) to build the tree. Rows are sorted alphabetically by `namePretty`, not in tree order, and a contact can legitimately span several roots. For contacts with an unusually large number of links (generic shared inboxes), the underlying scan is windowed to the most recent links, so the tree is complete for ordinary contacts and a recency-bounded approximation for those. Unknown ids return an empty list rather than a 404; returns 500 on an unexpected error.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The buyer contact's Bidscope id (a `people` row id, as returned by `buyer-contacts.search` as `\"people.id\"`). Example: \"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"buyers":{"description":"Every buyer tier the contact's opportunities and awards fall under (`isLinked: true`), plus all of their ancestors up to each root (`isLinked: false`), returned flat and sorted alphabetically by `namePretty` — NOT in tree order. Nest by `parentBuyerTierId` to render. A contact can appear under several unrelated roots, so this list may contain more than one root row. Empty when the contact's records carry no consolidated buyer yet, and also when no person with the given id exists (this endpoint does not 404).","type":"array","items":{"type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id (`buyer_tiers.id`); pass it to `buyers.get`, or use it as the parent target of other rows in this list. Example: \"6b3f2a80-15cd-4e77-9a41-c2e0d8b93f14\".","type":"string"},"namePretty":{"description":"The tier's display name — just this level of the hierarchy, not the full path (join the ancestors yourself for a breadcrumb). Never null. Example: \"Office of Fleet Management\".","type":"string"},"parentBuyerTierId":{"description":"The id of this tier's parent, which is always also present in `buyers` when non-null. Null exactly for root tiers — the top of an organization (e.g. a city, a state, or a federal department). Example: \"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49\".","anyOf":[{"type":"string"},{"type":"null"}]},"isLinked":{"description":"True when the contact is directly attributed to this tier — i.e. at least one opportunity or award they are named on was solicited or awarded under it. False for rows included only so the tree is connected up to its root; those ancestors are structural context, not evidence the contact works there. Example: true.","type":"boolean"}},"required":["id","namePretty","parentBuyerTierId","isLinked"],"additionalProperties":false}}},"required":["buyers"],"additionalProperties":false},"examples":[{"title":"A contact inside one department, with its ancestors","description":"The contact is directly linked only to the \"Office of Fleet Management\" tier. Its parent department and the city root are returned with `isLinked: false` so the client can render the full path — reading them as places the contact works would be wrong. Note the alphabetical ordering: the root is not first.","request":{"id":"5d2c9f61-7a34-4e08-b1c7-90f4a6e35b12"},"response":{"buyers":[{"id":"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49","namePretty":"City of Springfield","parentBuyerTierId":null,"isLinked":false},{"id":"6b3f2a80-15cd-4e77-9a41-c2e0d8b93f14","namePretty":"Office of Fleet Management","parentBuyerTierId":"d0a72b54-9f6e-4c31-b58a-3e7c1d9f40a2","isLinked":true},{"id":"d0a72b54-9f6e-4c31-b58a-3e7c1d9f40a2","namePretty":"Public Works Department","parentBuyerTierId":"1e9d4c73-58b2-4a06-8f35-7c1a0b6e2d49","isLinked":false}]}},{"title":"A contact with no consolidated buyer","description":"An empty tree — the contact's records have not been attributed to a buyer tier yet. The same shape is returned for an id that does not exist.","request":{"id":"a41b7e03-6c25-4f9a-8d30-2b5e1c7f4a99"},"response":{"buyers":[]}}]}]},{"procedure":"vendors.search","versions":[{"version":"2026-07-05","description":"Search the vendor universe — every company Bidscope has seen on a bidder list, in an award record or in a registration — ranked against one of your matching profiles. Each row is one company. `score` is a 0–1 match fraction against the profile's capability vector, and is null for vendors Bidscope has not profiled: those still appear, sort last on a score sort, and are excluded by any score filter above 0. `total` is always `-1` — ranking by vector distance precludes counting, so page until a short page comes back rather than reading a result count. Results are capped at 1,000 overall; a `page` past that ceiling returns `total: 0` with empty `items` instead of an error. Returns 404 when the matching profile does not exist and 403 when it belongs to another organization; unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile to rank vendors against — its averaged capability vector is the point every vendor is scored by distance from. Must belong to your organization (403 otherwise) and exist (404 otherwise). A profile with no vector yet still works: every vendor comes back with `score: null`, unranked but listed. Example: \"6e1a9c30-4b78-4d52-8f06-2a5c7e3b1d94\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query itself. `orderBy` + `sort` set the ordering (default and fastest: `orderBy: \"score\"`, `sort: \"desc\"`). `pageSize` must be one of 1, 10, 25, 50 or 100. `quickSearch` is an optional substring match, case-insensitive, against the vendor's display name, raw name and UEI. `filters` is a filter tree (`null` for none): each leaf names a column and an operator/value, and groups combine leaves with `isAnd`. Filterable columns are the response's item keys plus `\"vendors.all_naics_codes.code\"`, a virtual column matching the primary OR any secondary NAICS code. Notable leaves: `\"vendors.set_asides\"` with `enum.eq` takes a canonical set-aside name and matches through the raw-certification mapping; `\"score\"` with `number.gt` takes a fraction 0–1 and, above 0, drops unscored vendors; `\"distance\"` with `number.lt` takes metres. `filterMeta` is passed through untouched and does not affect results.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["vendors.name_pretty","vendors.naics_codes.code","vendors.certifications","vendors.places.country","vendors.places.region","distance","vendors.website_url","vendors.uei","vendors.cage_code","vendors.created_at","vendors.award_count","vendors.last_awarded_at","score","vendors.id"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Paging stops at 1,000 results overall — request a page beyond that and you get `total: 0` with an empty `items` array rather than an error. Example: 1.","type":"number","minimum":1},"skipCountTotal":{"description":"Accepted for parity with the other search endpoints but ignored here: vendor search is always ranked by vector distance, which can never produce a count, so `total` is `-1` regardless. Example: false.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Always `-1` — vendor search ranks by vector distance, which cannot be counted, so the number of matches is genuinely unknown. Do not render it as a result count; page until `items` comes back short. The one exception is `0`, returned together with an empty `items` array when `page` is past the 1,000-result ceiling. Example: -1.","type":"number"},"items":{"description":"One page of matching vendors, in the requested order. A row is one company, not one bid or contract. At most `search.pageSize` rows, and possibly fewer on the last reachable page: results are capped at 1,000 overall, so the page spanning that ceiling is truncated. An empty array means either no matches or a page past the ceiling.","type":"array","items":{"type":"object","properties":{"vendors.id":{"description":"The vendor's Bidscope id; pass it to `vendors.get` and the other `vendors.*` endpoints. Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string"},"vendors.name_pretty":{"description":"The vendor's cleaned-up display name. Example: \"Ridgeline Tactical Supply LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.naics_codes.code":{"description":"The vendor's primary NAICS industry code as stated on its own record, null when no source stated one. This is the record code only — unlike `vendors.get`, search never falls back to the AI-inferred code. Example: \"811310\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.secondary_naics_codes":{"description":"Additional NAICS codes declared on the vendor's record beyond the primary one, null when it declared none. Codes only — use `vendors.get` for their labels. Example: [\"332710\", \"336992\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"vendors.certifications":{"description":"The certifications claimed for this vendor, as the raw strings the sources published — wording varies by portal and near-duplicates are normal. Null when the record carries none. For a normalised view use `vendors.set_asides`. Example: [\"SDVOSB\", \"Service Disabled Veteran Owned Small Business (SDVOSB)\", \"Small Business Concern\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"vendors.set_asides":{"description":"The distinct canonical set-aside categories the raw `vendors.certifications` map to, sorted alphabetically: any of \"Disadvantaged Business\", \"Minority-Owned Business\", \"Native-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Small Business\", \"Veteran-Owned Business\", \"Woman-Owned Business\". Empty when the vendor has certifications but none of them are recognised set-asides (e.g. only quality standards). This is the field to filter on. Example: [\"Service-Disabled Veteran-Owned Business\", \"Small Business\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"vendors.places.country":{"description":"Country of the vendor's own location — where the company is, not a place of performance. Null when no source gave a locatable address. Example: \"United States of America\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.places.region":{"description":"First-level subdivision of the vendor's own location — the state for US vendors. Null when unlocated or when the place resolved only to country level. Example: \"Ohio\".","anyOf":[{"type":"string"},{"type":"null"}]},"distance":{"description":"How far the vendor is from your organization's saved location, in metres. Null when your organization has no coordinates configured, or when the vendor's place has no geometry. Note that a distance filter matches nothing at all while your organization is missing coordinates. Example: 42350.7 (about 26 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"vendors.website_url":{"description":"The company website as published by a source, null when none was. Stored as published, so it may lack a scheme. Example: \"https://example-ridgeline.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.uei":{"description":"The vendor's 12-character federal Unique Entity ID, null for vendors known only from state or local bidder lists. Example: \"ZQK7M4TN8P2C\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.cage_code":{"description":"The vendor's 5-character CAGE code, null for vendors with no federal registration. Example: \"8LM42\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.created_at":{"type":["string","null"],"format":"date-time","description":"When Bidscope first recorded this vendor — not when the company was founded or registered. Example: \"2024-09-18T03:41:22.507Z\"."},"vendors.award_count":{"description":"How many contracts Bidscope has recorded this vendor winning, denormalized onto the vendor record. 0 for vendors that have never won recorded work. Example: 37.","anyOf":[{"type":"number"},{"type":"null"}]},"vendors.last_awarded_at":{"type":["string","null"],"format":"date-time","description":"When this vendor most recently won a contract, null when it has never won recorded work. Example: \"2026-06-14T00:00:00.000Z\"."},"score":{"description":"How well the vendor matches the requested matching profile, as a 0–1 fraction derived from the cosine distance between the vendor's capability vector and the profile's. Higher is closer. Null — not 0 — when Bidscope has not profiled the vendor (no capability vector); such vendors are still returned, sort last on a score sort, and render as \"-\" rather than a bad match. A score filter above 0 excludes them. Example: 0.82.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["vendors.id","vendors.name_pretty","vendors.naics_codes.code","vendors.secondary_naics_codes","vendors.certifications","vendors.set_asides","vendors.places.country","vendors.places.region","distance","vendors.website_url","vendors.uei","vendors.cage_code","vendors.created_at","vendors.award_count","vendors.last_awarded_at","score"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best-matching vendors for a profile","description":"The default query: no filters, ranked by match score descending. Note `total: -1` (never a count) and the second row's `score: null` — an unprofiled vendor, sorted after every scored one, not a zero-percent match. `distance` is null throughout because this organization has no saved coordinates.","request":{"matchingProfileId":"6e1a9c30-4b78-4d52-8f06-2a5c7e3b1d94","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1},"response":{"total":-1,"items":[{"vendors.id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53","vendors.name_pretty":"Ridgeline Tactical Supply LLC","vendors.naics_codes.code":"811310","vendors.secondary_naics_codes":["332710","336992"],"vendors.certifications":["SDVOSB","Small Business Concern"],"vendors.set_asides":["Service-Disabled Veteran-Owned Business","Small Business"],"vendors.places.country":"United States of America","vendors.places.region":"Ohio","distance":null,"vendors.website_url":"https://example-ridgeline.com","vendors.uei":"ZQK7M4TN8P2C","vendors.cage_code":"8LM42","vendors.created_at":"2024-09-18T03:41:22.507Z","vendors.award_count":37,"vendors.last_awarded_at":"2026-06-14T00:00:00.000Z","score":0.82},{"vendors.id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28","vendors.name_pretty":"Cascade Grounds Care","vendors.naics_codes.code":null,"vendors.secondary_naics_codes":null,"vendors.certifications":null,"vendors.set_asides":[],"vendors.places.country":"United States of America","vendors.places.region":"Washington","distance":null,"vendors.website_url":null,"vendors.uei":null,"vendors.cage_code":null,"vendors.created_at":"2026-02-04T19:07:55.310Z","vendors.award_count":0,"vendors.last_awarded_at":null,"score":null}]}},{"title":"Filtered: SDVOSB or woman-owned, in Ohio, with award history","description":"A realistic filter tree of the shape the app's simple search builds. The root ANDs four things together: an inner OR group of `enum.eq` leaves on `\"vendors.set_asides\"` (any of the listed categories — canonical names, matched through the raw-certification mapping, so you never filter on raw strings); a `string.eq` leaf on the vendor's own state; a `number.gt` leaf on `\"vendors.award_count\"` (strictly more than 5 recorded wins); and a `date.after` leaf on `\"vendors.last_awarded_at\"` to require recent activity. `quickSearch` narrows further by name/UEI substring. Sorting by `\"vendors.award_count\"` descending rather than score is allowed — `score` is still computed and returned.","request":{"matchingProfileId":"6e1a9c30-4b78-4d52-8f06-2a5c7e3b1d94","search":{"orderBy":"vendors.award_count","sort":"desc","pageSize":25,"quickSearch":"supply","filters":{"type":"group","isAnd":true,"filters":[{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Service-Disabled Veteran-Owned Business"}},{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Woman-Owned Business"}}]},{"type":"filter","column":"vendors.places.region","filter":{"operator":"string.eq","value":"Ohio"}},{"type":"filter","column":"vendors.award_count","filter":{"operator":"number.gt","value":5}},{"type":"filter","column":"vendors.last_awarded_at","filter":{"operator":"date.after","value":"2025-01-01T00:00:00.000Z"}}]}},"page":1},"response":{"total":-1,"items":[{"vendors.id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53","vendors.name_pretty":"Ridgeline Tactical Supply LLC","vendors.naics_codes.code":"811310","vendors.secondary_naics_codes":["332710","336992"],"vendors.certifications":["SDVOSB","Small Business Concern"],"vendors.set_asides":["Service-Disabled Veteran-Owned Business","Small Business"],"vendors.places.country":"United States of America","vendors.places.region":"Ohio","distance":42350.7,"vendors.website_url":"https://example-ridgeline.com","vendors.uei":"ZQK7M4TN8P2C","vendors.cage_code":"8LM42","vendors.created_at":"2024-09-18T03:41:22.507Z","vendors.award_count":37,"vendors.last_awarded_at":"2026-06-14T00:00:00.000Z","score":0.82}]}}]},{"version":"2026-08-19","description":"Search the vendor universe — every company Bidscope has seen on a bidder list, in an award record or in a registration — ranked against one of your matching profiles. Each row is one company. `score` is a 0–1 match fraction against the profile's capability vector, and is null for vendors Bidscope has not profiled: those still appear, sort last on a score sort, and are excluded by any score filter above 0. `total` is always `-1` — ranking by vector distance precludes counting, so page until a short page comes back rather than reading a result count. Results are capped at 1,000 overall; a `page` past that ceiling returns `total: 0` with empty `items` instead of an error. Returns 404 when the matching profile does not exist and 403 when it belongs to another organization; unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile to rank vendors against — its averaged capability vector is the point every vendor is scored by distance from. Must belong to your organization (403 otherwise) and exist (404 otherwise). A profile with no vector yet still works: every vendor comes back with `score: null`, unranked but listed. Example: \"6e1a9c30-4b78-4d52-8f06-2a5c7e3b1d94\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The query itself. `orderBy` + `sort` set the ordering (default and fastest: `orderBy: \"score\"`, `sort: \"desc\"`). `pageSize` must be one of 1, 10, 25, 50 or 100. `quickSearch` is an optional substring match, case-insensitive, against the vendor's display name, raw name and UEI. `filters` is a filter tree (`null` for none): each leaf names a column and an operator/value, and groups combine leaves with `isAnd`. Filterable columns are the response's item keys plus `\"vendors.all_naics_codes.code\"`, a virtual column matching the primary OR any secondary NAICS code. Notable leaves: `\"vendors.set_asides\"` with `enum.eq` takes a canonical set-aside name and matches through the raw-certification mapping; `\"score\"` with `number.gt` takes a fraction 0–1 and, above 0, drops unscored vendors; `\"distance\"` with `number.lt` takes metres. `filterMeta` is passed through untouched and does not affect results.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["vendors.name_pretty","vendors.naics_codes.code","vendors.certifications","vendors.places.country","vendors.places.region","distance","vendors.website_url","vendors.uei","vendors.cage_code","vendors.created_at","vendors.award_count","vendors.last_awarded_at","score","vendors.id"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number. Paging stops at 1,000 results overall — request a page beyond that and you get `total: 0` with an empty `items` array rather than an error. Example: 1.","type":"number","minimum":1},"location":{"description":"Optional point to measure distances from. When supplied it replaces your organization's saved location as the center for the distance column(s) and any distance filter, for this request only. Omit it (or pass null) to use the organization's saved location, which is the previous behaviour. Example: { \"latitude\": 30.267153, \"longitude\": -97.743057 }.","anyOf":[{"type":"object","properties":{"latitude":{"description":"Latitude in decimal degrees. Example: 30.267153.","type":"number","minimum":-90,"maximum":90},"longitude":{"description":"Longitude in decimal degrees. Example: -97.743057.","type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}]},"skipCountTotal":{"description":"Accepted for parity with the other search endpoints but ignored here: vendor search is always ranked by vector distance, which can never produce a count, so `total` is `-1` regardless. Example: false.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Always `-1` — vendor search ranks by vector distance, which cannot be counted, so the number of matches is genuinely unknown. Do not render it as a result count; page until `items` comes back short. The one exception is `0`, returned together with an empty `items` array when `page` is past the 1,000-result ceiling. Example: -1.","type":"number"},"items":{"description":"One page of matching vendors, in the requested order. A row is one company, not one bid or contract. At most `search.pageSize` rows, and possibly fewer on the last reachable page: results are capped at 1,000 overall, so the page spanning that ceiling is truncated. An empty array means either no matches or a page past the ceiling.","type":"array","items":{"type":"object","properties":{"vendors.id":{"description":"The vendor's Bidscope id; pass it to `vendors.get` and the other `vendors.*` endpoints. Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string"},"vendors.name_pretty":{"description":"The vendor's cleaned-up display name. Example: \"Ridgeline Tactical Supply LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.naics_codes.code":{"description":"The vendor's primary NAICS industry code as stated on its own record, null when no source stated one. This is the record code only — unlike `vendors.get`, search never falls back to the AI-inferred code. Example: \"811310\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.secondary_naics_codes":{"description":"Additional NAICS codes declared on the vendor's record beyond the primary one, null when it declared none. Codes only — use `vendors.get` for their labels. Example: [\"332710\", \"336992\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"vendors.certifications":{"description":"The certifications claimed for this vendor, as the raw strings the sources published — wording varies by portal and near-duplicates are normal. Null when the record carries none. For a normalised view use `vendors.set_asides`. Example: [\"SDVOSB\", \"Service Disabled Veteran Owned Small Business (SDVOSB)\", \"Small Business Concern\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"vendors.set_asides":{"description":"The distinct canonical set-aside categories the raw `vendors.certifications` map to, sorted alphabetically: any of \"Disadvantaged Business\", \"Minority-Owned Business\", \"Native-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Small Business\", \"Veteran-Owned Business\", \"Woman-Owned Business\". Empty when the vendor has certifications but none of them are recognised set-asides (e.g. only quality standards). This is the field to filter on. Example: [\"Service-Disabled Veteran-Owned Business\", \"Small Business\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"vendors.places.country":{"description":"Country of the vendor's own location — where the company is, not a place of performance. Null when no source gave a locatable address. Example: \"United States of America\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.places.region":{"description":"First-level subdivision of the vendor's own location — the state for US vendors. Null when unlocated or when the place resolved only to country level. Example: \"Ohio\".","anyOf":[{"type":"string"},{"type":"null"}]},"distance":{"description":"How far the vendor is from the request's `location` when supplied, and otherwise from your organization's saved location, in metres. Null when your organization has no coordinates configured, or when the vendor's place has no geometry. Note that a distance filter matches nothing at all while your organization is missing coordinates. Example: 42350.7 (about 26 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"vendors.website_url":{"description":"The company website as published by a source, null when none was. Stored as published, so it may lack a scheme. Example: \"https://example-ridgeline.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.uei":{"description":"The vendor's 12-character federal Unique Entity ID, null for vendors known only from state or local bidder lists. Example: \"ZQK7M4TN8P2C\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.cage_code":{"description":"The vendor's 5-character CAGE code, null for vendors with no federal registration. Example: \"8LM42\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.created_at":{"type":["string","null"],"format":"date-time","description":"When Bidscope first recorded this vendor — not when the company was founded or registered. Example: \"2024-09-18T03:41:22.507Z\"."},"vendors.award_count":{"description":"How many contracts Bidscope has recorded this vendor winning, denormalized onto the vendor record. 0 for vendors that have never won recorded work. Example: 37.","anyOf":[{"type":"number"},{"type":"null"}]},"vendors.last_awarded_at":{"type":["string","null"],"format":"date-time","description":"When this vendor most recently won a contract, null when it has never won recorded work. Example: \"2026-06-14T00:00:00.000Z\"."},"score":{"description":"How well the vendor matches the requested matching profile, as a 0–1 fraction derived from the cosine distance between the vendor's capability vector and the profile's. Higher is closer. Null — not 0 — when Bidscope has not profiled the vendor (no capability vector); such vendors are still returned, sort last on a score sort, and render as \"-\" rather than a bad match. A score filter above 0 excludes them. Example: 0.82.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["vendors.id","vendors.name_pretty","vendors.naics_codes.code","vendors.secondary_naics_codes","vendors.certifications","vendors.set_asides","vendors.places.country","vendors.places.region","distance","vendors.website_url","vendors.uei","vendors.cage_code","vendors.created_at","vendors.award_count","vendors.last_awarded_at","score"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"Best-matching vendors for a profile","description":"The default query: no filters, ranked by match score descending. Note `total: -1` (never a count) and the second row's `score: null` — an unprofiled vendor, sorted after every scored one, not a zero-percent match. `distance` is null throughout because this organization has no saved coordinates.","request":{"matchingProfileId":"6e1a9c30-4b78-4d52-8f06-2a5c7e3b1d94","search":{"orderBy":"score","sort":"desc","pageSize":10,"filters":null},"page":1},"response":{"total":-1,"items":[{"vendors.id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53","vendors.name_pretty":"Ridgeline Tactical Supply LLC","vendors.naics_codes.code":"811310","vendors.secondary_naics_codes":["332710","336992"],"vendors.certifications":["SDVOSB","Small Business Concern"],"vendors.set_asides":["Service-Disabled Veteran-Owned Business","Small Business"],"vendors.places.country":"United States of America","vendors.places.region":"Ohio","distance":null,"vendors.website_url":"https://example-ridgeline.com","vendors.uei":"ZQK7M4TN8P2C","vendors.cage_code":"8LM42","vendors.created_at":"2024-09-18T03:41:22.507Z","vendors.award_count":37,"vendors.last_awarded_at":"2026-06-14T00:00:00.000Z","score":0.82},{"vendors.id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28","vendors.name_pretty":"Cascade Grounds Care","vendors.naics_codes.code":null,"vendors.secondary_naics_codes":null,"vendors.certifications":null,"vendors.set_asides":[],"vendors.places.country":"United States of America","vendors.places.region":"Washington","distance":null,"vendors.website_url":null,"vendors.uei":null,"vendors.cage_code":null,"vendors.created_at":"2026-02-04T19:07:55.310Z","vendors.award_count":0,"vendors.last_awarded_at":null,"score":null}]}},{"title":"Filtered: SDVOSB or woman-owned, in Ohio, with award history","description":"A realistic filter tree of the shape the app's simple search builds. The root ANDs four things together: an inner OR group of `enum.eq` leaves on `\"vendors.set_asides\"` (any of the listed categories — canonical names, matched through the raw-certification mapping, so you never filter on raw strings); a `string.eq` leaf on the vendor's own state; a `number.gt` leaf on `\"vendors.award_count\"` (strictly more than 5 recorded wins); and a `date.after` leaf on `\"vendors.last_awarded_at\"` to require recent activity. `quickSearch` narrows further by name/UEI substring. Sorting by `\"vendors.award_count\"` descending rather than score is allowed — `score` is still computed and returned.","request":{"matchingProfileId":"6e1a9c30-4b78-4d52-8f06-2a5c7e3b1d94","search":{"orderBy":"vendors.award_count","sort":"desc","pageSize":25,"quickSearch":"supply","filters":{"type":"group","isAnd":true,"filters":[{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Service-Disabled Veteran-Owned Business"}},{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Woman-Owned Business"}}]},{"type":"filter","column":"vendors.places.region","filter":{"operator":"string.eq","value":"Ohio"}},{"type":"filter","column":"vendors.award_count","filter":{"operator":"number.gt","value":5}},{"type":"filter","column":"vendors.last_awarded_at","filter":{"operator":"date.after","value":"2025-01-01T00:00:00.000Z"}}]}},"page":1},"response":{"total":-1,"items":[{"vendors.id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53","vendors.name_pretty":"Ridgeline Tactical Supply LLC","vendors.naics_codes.code":"811310","vendors.secondary_naics_codes":["332710","336992"],"vendors.certifications":["SDVOSB","Small Business Concern"],"vendors.set_asides":["Service-Disabled Veteran-Owned Business","Small Business"],"vendors.places.country":"United States of America","vendors.places.region":"Ohio","distance":42350.7,"vendors.website_url":"https://example-ridgeline.com","vendors.uei":"ZQK7M4TN8P2C","vendors.cage_code":"8LM42","vendors.created_at":"2024-09-18T03:41:22.507Z","vendors.award_count":37,"vendors.last_awarded_at":"2026-06-14T00:00:00.000Z","score":0.82}]}}]}]},{"procedure":"vendors.get","versions":[{"version":"2026-07-05","description":"One vendor's full profile: display name, federal identifiers (UEI, CAGE, legacy DUNS), website, the certifications it claims paired with the canonical set-aside category each maps to, Bidscope's AI company summary and capability keywords, NAICS classification from three angles (`naics` stated on the record, `inferred_naics` derived from the website, `secondary_naics` additional declared codes), its own location, and denormalized award statistics (`award_count`, `last_awarded_at`). A vendor is a `leads` row — a company Bidscope has seen on a bidder list, in an award record, or in a registration — so how complete this profile is varies enormously by source. Returns 404 when no vendor has that id or the vendor has been suppressed; unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The vendor's Bidscope id (`leads.id`, as returned by `vendors.search` as `\"vendors.id\"`). Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"vendor":{"type":"object","properties":{"id":{"description":"The vendor's Bidscope id — the same value you passed in. Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string"},"name_pretty":{"description":"The vendor's cleaned-up display name (the raw source name normalised for casing and punctuation). Example: \"Ridgeline Tactical Supply LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"website_url":{"description":"The company website as published by the source (bidder list or registration). Null when no source gave one — check `inferred_website_url` in that case. Stored as published, so it may lack a scheme. Example: \"https://example-ridgeline.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"uei":{"description":"Unique Entity ID — the 12-character identifier the US federal government issues to registered entities (it replaced DUNS in 2022). Present for vendors seen in SAM registrations or federal award records; null for vendors known only from state/local bidder lists. Example: \"ZQK7M4TN8P2C\".","anyOf":[{"type":"string"},{"type":"null"}]},"cage_code":{"description":"Commercial and Government Entity code — a 5-character US Defense Logistics Agency identifier. Same availability as `uei`: federal sources only. Example: \"8LM42\".","anyOf":[{"type":"string"},{"type":"null"}]},"duns":{"description":"Legacy 9-digit Dun & Bradstreet number, retained for vendors captured before the federal switch to UEI. Null for anything registered since. Example: \"084729315\".","anyOf":[{"type":"string"},{"type":"null"}]},"certifications":{"description":"Every distinct certification claimed for this vendor, each paired with the canonical set-aside category it consolidates to, sorted by `raw`. Null (not an empty array) when the vendor record carries no certifications at all. Note this is the raw-string view — `vendors.search` returns the already-consolidated `vendors.set_asides` list instead.","anyOf":[{"type":"array","items":{"type":"object","properties":{"raw":{"description":"The certification string exactly as the source published it — wording varies wildly between portals. Example: \"Service Disabled Veteran Owned Small Business (SDVOSB)\".","type":"string"},"set_aside_type":{"description":"The canonical set-aside category this raw string maps to, one of \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Native-Owned Business\", \"Disadvantaged Business\" or \"Minority-Owned Business\". Null when the raw string is not a set-aside at all (e.g. an ISO quality certification or a portal artefact) or has not been classified yet. Several raw strings commonly collapse onto the same type — group by this field to render one chip per category. Example: \"Service-Disabled Veteran-Owned Business\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["raw","set_aside_type"],"additionalProperties":false}},{"type":"null"}]},"company_keywords":{"description":"Short capability keywords describing what the company does, derived from its website and profile. Null when the vendor has not been profiled. Example: [\"vehicle maintenance\", \"tactical equipment\", \"field logistics\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"company_description":{"description":"The company description as published by a source (self-written boilerplate, verbatim). Null when no source published one. Prefer `company_summary` when it is present — the app falls back to this field. Example: \"Ridgeline Tactical Supply LLC is a veteran-owned distributor of field maintenance equipment.\"","anyOf":[{"type":"string"},{"type":"null"}]},"company_summary":{"description":"Bidscope's AI-generated summary of what the company does, written from its website. Null when the vendor has not been profiled (no website found, or profiling has not run). This is the field the vendor page shows first. Example: \"A veteran-owned distributor supplying vehicle repair kits, shelter systems and field maintenance equipment to defence and public-safety buyers.\"","anyOf":[{"type":"string"},{"type":"null"}]},"inferred_website_url":{"description":"The website Bidscope actually profiled the company from — resolved independently of `website_url`, sometimes from a contact email domain when no source published a URL. Null when the vendor has not been profiled. Where both exist they can disagree; the app prefers this one. Example: \"https://example-ridgeline.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","description":"When Bidscope first recorded this vendor — not when the company was founded or registered. Example: \"2024-09-18T03:41:22.507Z\"."},"award_count":{"description":"How many contracts Bidscope has recorded this vendor winning, denormalized onto the vendor record and maintained as awards are ingested. 0 for vendors that have never won recorded work. Example: 37.","anyOf":[{"type":"number"},{"type":"null"}]},"last_awarded_at":{"type":["string","null"],"format":"date-time","description":"When this vendor most recently won a contract. Null when it has never won recorded work. Example: \"2026-06-14T00:00:00.000Z\"."},"naics":{"description":"The vendor's primary NAICS industry classification as stated on its own record (from a registration or bidder-list profile). Null when no source stated one — fall back to `inferred_naics`, which is what the vendor page does.","anyOf":[{"type":"object","properties":{"code":{"description":"The 6-digit NAICS industry code. Example: \"811310\".","type":"string"},"label":{"description":"The official NAICS description for that code, null when the code is not in Bidscope's NAICS reference table (unknown or retired codes still return with a null label). Example: \"Commercial and Industrial Machinery and Equipment (except Automotive and Electronic) Repair and Maintenance\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"inferred_naics":{"description":"The primary NAICS code Bidscope's AI derived from the company's website, used when `naics` is absent. Null when the vendor has not been profiled. Can differ from `naics` when both exist — that is a genuine disagreement between the vendor's self-declaration and its observed business, not an error.","anyOf":[{"type":"object","properties":{"code":{"description":"The 6-digit NAICS industry code. Example: \"423840\".","type":"string"},"label":{"description":"The official NAICS description for that code, null for codes absent from Bidscope's reference table. Example: \"Industrial Supplies Merchant Wholesalers\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false},{"type":"null"}]},"secondary_naics":{"description":"Additional NAICS codes stated on the vendor's own record beyond the primary one, sorted by code. Always an array — empty (never null) when the vendor declared none. These come from the record only; there is no inferred equivalent.","type":"array","items":{"type":"object","properties":{"code":{"description":"The 6-digit NAICS industry code. Example: \"332710\".","type":"string"},"label":{"description":"The official NAICS description for that code, null for codes absent from Bidscope's reference table. Example: \"Machine Shops\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","label"],"additionalProperties":false}},"address":{"description":"The vendor's street address as published by a source, unparsed. Null when none was published — `place` may still locate the vendor at city level. Example: \"4120 Ridge Line Road, Suite 200, Columbus, OH 43215\".","anyOf":[{"type":"string"},{"type":"null"}]},"place":{"description":"The vendor's own resolved location — where the company is, not a place of performance. Null when no source gave a locatable address. Present whenever Bidscope resolved either a name or coordinates, so individual sub-fields can still be null.","anyOf":[{"type":"object","properties":{"pretty_name":{"description":"Display name of the resolved location. Example: \"Columbus, Ohio, United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"Country name. Example: \"United States of America\".","anyOf":[{"type":"string"},{"type":"null"}]},"region":{"description":"First-level subdivision — the state for US vendors. Example: \"Ohio\".","anyOf":[{"type":"string"},{"type":"null"}]},"latitude":{"description":"Latitude of the location's representative point in decimal degrees (WGS 84), null when the place has no point geometry. Example: 39.9612.","anyOf":[{"type":"number"},{"type":"null"}]},"longitude":{"description":"Longitude of the location's representative point in decimal degrees (WGS 84), null when the place has no point geometry. Example: -82.9988.","anyOf":[{"type":"number"},{"type":"null"}]},"bbox":{"description":"Bounding box of the place's area geometry as `[minLongitude, minLatitude, maxLongitude, maxLatitude]`, null when the place has no area geometry (points-only places). Example: [-83.2001, 39.8086, -82.7714, 40.1573].","anyOf":[{"type":"array","items":{"type":"number"}},{"type":"null"}]}},"required":["pretty_name","country","region","latitude","longitude","bbox"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name_pretty","website_url","uei","cage_code","duns","certifications","company_keywords","company_description","company_summary","inferred_website_url","created_at","award_count","last_awarded_at","naics","inferred_naics","secondary_naics","address","place"],"additionalProperties":false}},"required":["vendor"],"additionalProperties":false},"examples":[{"title":"A well-profiled federal contractor","description":"Registered in SAM (hence UEI and CAGE) and profiled by Bidscope (hence `company_summary`, `company_keywords` and `inferred_naics`). Note the two raw certification strings that both consolidate to \"Service-Disabled Veteran-Owned Business\", and the third that maps to nothing because it is a quality standard rather than a set-aside.","request":{"id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53"},"response":{"vendor":{"id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53","name_pretty":"Ridgeline Tactical Supply LLC","website_url":"https://example-ridgeline.com","uei":"ZQK7M4TN8P2C","cage_code":"8LM42","duns":null,"certifications":[{"raw":"ISO 9001:2015 Certified","set_aside_type":null},{"raw":"SDVOSB","set_aside_type":"Service-Disabled Veteran-Owned Business"},{"raw":"Service Disabled Veteran Owned Small Business (SDVOSB)","set_aside_type":"Service-Disabled Veteran-Owned Business"},{"raw":"Small Business Concern","set_aside_type":"Small Business"}],"company_keywords":["vehicle maintenance","tactical equipment","field logistics"],"company_description":"Ridgeline Tactical Supply LLC is a veteran-owned distributor of field maintenance equipment.","company_summary":"A veteran-owned distributor supplying vehicle repair kits, shelter systems and field maintenance equipment to defence and public-safety buyers.","inferred_website_url":"https://example-ridgeline.com","created_at":"2024-09-18T03:41:22.507Z","award_count":37,"last_awarded_at":"2026-06-14T00:00:00.000Z","naics":{"code":"811310","label":"Commercial and Industrial Machinery and Equipment (except Automotive and Electronic) Repair and Maintenance"},"inferred_naics":{"code":"423840","label":"Industrial Supplies Merchant Wholesalers"},"secondary_naics":[{"code":"332710","label":"Machine Shops"},{"code":"336992","label":null}],"address":"4120 Ridge Line Road, Suite 200, Columbus, OH 43215","place":{"pretty_name":"Columbus, Ohio, United States","country":"United States of America","region":"Ohio","latitude":39.9612,"longitude":-82.9988,"bbox":[-83.2001,39.8086,-82.7714,40.1573]}}}},{"title":"A thin record from a local bidder list","description":"The realistic other extreme, and what most non-federal vendors look like: a name and a state, nothing more. No federal identifiers (never registered in SAM), no AI profile (`company_summary`, `company_keywords`, `inferred_naics`, `inferred_website_url` all null because no website was found), no awards, and `certifications` null rather than an empty array. Expect to handle this shape — do not assume a populated profile.","request":{"id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28"},"response":{"vendor":{"id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28","name_pretty":"Cascade Grounds Care","website_url":null,"uei":null,"cage_code":null,"duns":null,"certifications":null,"company_keywords":null,"company_description":null,"company_summary":null,"inferred_website_url":null,"created_at":"2026-02-04T19:07:55.310Z","award_count":0,"last_awarded_at":null,"naics":null,"inferred_naics":null,"secondary_naics":[],"address":null,"place":{"pretty_name":"Washington, United States","country":"United States of America","region":"Washington","latitude":47.3826,"longitude":-120.4472,"bbox":null}}}}]}]},{"procedure":"vendors.get-awards","versions":[{"version":"2026-07-05","description":"A vendor's contract award history. Each row is one contract awarded to this vendor (`awards.awardee_lead_id`), including expired ones. Returns the 10 most recent by earliest-known-date — `LEAST(date_awarded, date_started, created_at)` descending, undated last — with `hasMore` true when further awards exist; there is no paging here, use `awards.search` to go deeper. Unlike `vendors.get`, an unknown or suppressed vendor id is not an error: it simply yields an empty list. Unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The vendor's Bidscope id (`leads.id`, as returned by `vendors.search` as `\"vendors.id\"`). Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"awards":{"description":"The vendor's 10 most recent contract awards, newest first. Ordered by the earliest known date on each award — `LEAST(date_awarded, date_started, created_at)` — descending, with undated awards last; that is NOT strictly `date_awarded` order. Includes expired contracts: this is the vendor's award history, not just its live work. Empty when the vendor has won nothing (and also for an id that matches no vendor).","type":"array","items":{"type":"object","properties":{"id":{"description":"The award's Bidscope id; pass it to `awards.get`. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","type":"string"},"title":{"description":"The contract's title as reported by the awarding source, null when the source published none. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"piid":{"description":"The awarding agency's contract identifier (the federal Procurement Instrument Identifier for FPDS/SAM awards), null for sources that publish none. Example: \"47QRAA24D008K\".","anyOf":[{"type":"string"},{"type":"null"}]},"buyer_id":{"description":"The Bidscope id of the consolidated buyer tier that awarded the contract; pass it to `buyers.get`. Null when the award's raw buyer has not been consolidated onto a tier yet — in that case `buyer_name` still carries the raw name. Example: \"a4f1b208-6c7d-4e93-8b25-1f0a3d9c6e47\".","anyOf":[{"type":"string"},{"type":"null"}]},"buyer_name":{"description":"Display name of the awarding buyer, taken from the first raw buyer recorded against the award. When that raw buyer is consolidated this is the tier's full hierarchy path (levels joined with \" > \"); when it is not, it falls back to the raw root buyer's name and `buyer_id` is null. Null only when the award has no buyer recorded at all. Example: \"Department of Defense > Defense Logistics Agency > DLA Land and Maritime\".","anyOf":[{"type":"string"},{"type":"null"}]},"award_value_cents":{"description":"Total awarded value in integer USD cents, null when the source published no value. Example: 128450000 (i.e. $1,284,500.00).","anyOf":[{"type":"number"},{"type":"null"}]},"date_awarded":{"type":["string","null"],"format":"date-time","description":"When the contract was awarded, null when the source published no award date. Example: \"2026-03-11T00:00:00.000Z\"."},"date_started":{"type":["string","null"],"format":"date-time","description":"Start of the contract's period of performance, null when the source published none. Example: \"2026-04-01T00:00:00.000Z\"."},"date_ended":{"type":["string","null"],"format":"date-time","description":"End of the contract's period of performance — in the past for expired contracts. Null when the source published no end date. Example: \"2029-03-31T00:00:00.000Z\"."},"is_active":{"description":"Whether the contract is still live: true = active, false = expired (roughly 88% of federal award records), null = the source gave no basis to decide (the UI renders this as \"Unknown\"). Independent of `date_ended` — do not derive one from the other. Example: false.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","title","piid","buyer_id","buyer_name","award_value_cents","date_awarded","date_started","date_ended","is_active"],"additionalProperties":false}},"hasMore":{"description":"True when the vendor has more than 10 awards. This endpoint has no paging — use `awards.search` filtered to the vendor to page through the full history. Example: true.","type":"boolean"}},"required":["awards","hasMore"],"additionalProperties":false},"examples":[{"title":"A federal contractor's recent awards","description":"The first award is expired (`is_active: false`, `date_ended` in the past) but still listed — this is a full history. `hasMore` is true, so this vendor has more than 10 contracts; page the rest via `awards.search`.","request":{"id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53"},"response":{"awards":[{"id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","title":"Facility HVAC Maintenance Services","piid":"47QRAA24D008K","buyer_id":"a4f1b208-6c7d-4e93-8b25-1f0a3d9c6e47","buyer_name":"Department of Defense > Defense Logistics Agency > DLA Land and Maritime","award_value_cents":128450000,"date_awarded":"2026-03-11T00:00:00.000Z","date_started":"2026-04-01T00:00:00.000Z","date_ended":"2029-03-31T00:00:00.000Z","is_active":true},{"id":"c7e4a015-2d88-4b3f-9c60-1a5f3e8d7b22","title":"Grounds Maintenance, Building 400 Complex","piid":"W912DR21C0043","buyer_id":"e8c50a73-1d62-4f09-b3a8-6c9e2f7d0b14","buyer_name":"General Services Administration","award_value_cents":4180000,"date_awarded":"2021-08-02T00:00:00.000Z","date_started":"2021-09-01T00:00:00.000Z","date_ended":"2024-08-31T00:00:00.000Z","is_active":false}],"hasMore":true}},{"title":"A vendor with no award history","description":"Vendors sourced only from bidder lists (they follow solicitations but have not won anything Bidscope has recorded) return an empty list, not a 404. The same empty response comes back for an id that matches no vendor at all — use `vendors.get` if you need to tell those apart.","request":{"id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28"},"response":{"awards":[],"hasMore":false}}]}]},{"procedure":"vendors.get-contacts","versions":[{"version":"2026-07-05","description":"People associated with a vendor — the names, email addresses and phone numbers captured alongside it on bidder lists, registrations and award records. Each row is one person (`people` via `lead_contacts`), carrying any email-deliverability validations recorded for their address at this vendor. Returns the first 10 ordered oldest-first (stable, not ranked), with `hasMore` true when more exist; there is no paging beyond that. People whose name, email and phone are all null are filtered out. An unknown vendor id returns an empty list rather than an error; unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The vendor's Bidscope id (`leads.id`, as returned by `vendors.search` as `\"vendors.id\"`). Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"people":{"description":"The vendor's first 10 known contacts, oldest first by when Bidscope recorded the person — a stable order, not a relevance ranking. Contacts with no name, email and phone at all (dedupe leftovers) are omitted. Empty when the vendor has no contacts (and also for an id that matches no vendor).","type":"array","items":{"type":"object","properties":{"id":{"description":"The person's Bidscope id (`people.id`). Stable per contact record — the same human can appear under more than one id if they were captured from separate sources. Example: \"d3a71f60-9c28-4b45-8e13-5a7f0c2d6b91\".","type":"string"},"fullName":{"description":"The contact's name as captured from the source (bidder list, registration or award record). Null when only an email address or phone number was published. Example: \"Dana Whitfield\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailAddress":{"description":"The contact's email address, null when the source published none. Not normalised to lower case here — the app lower-cases it for display. Example: \"d.whitfield@example-contracting.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"description":"The contact's phone number, in whatever form the source published it (no canonical formatting). Null when none was published. Example: \"+1 555-0142\".","anyOf":[{"type":"string"},{"type":"null"}]},"emailValidations":{"description":"Deliverability checks recorded for this contact's email address against this vendor. Usually empty (most contacts are never validated) or a single entry; several appear when the address was re-checked over time. Always empty when `emailAddress` is null.","type":"array","items":{"type":"object","properties":{"id":{"description":"The validation record's Bidscope id. Example: \"8f14c2b7-06d3-4e59-a82f-1b7d5e0c3a64\".","type":"string"},"emailAddress":{"description":"The address that was checked. Always equal to the parent contact's `emailAddress` — the join matches on it — so it is never null in practice. Example: \"d.whitfield@example-contracting.com\".","anyOf":[{"type":"string"},{"type":"null"}]},"isDeliverable":{"description":"Result of the third-party deliverability check: true = the mailbox accepted verification, false = it did not (bounced, rejected or unknown domain). Example: true.","anyOf":[{"type":"boolean"},{"type":"null"}]},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the validation was performed — useful for judging how stale the verdict is. Example: \"2026-05-22T14:08:31.204Z\"."}},"required":["id","emailAddress","isDeliverable","createdAt"],"additionalProperties":false}}},"required":["id","fullName","emailAddress","phoneNumber","emailValidations"],"additionalProperties":false}},"hasMore":{"description":"True when the vendor has more than 10 contacts. This endpoint has no paging and no way to reach contacts 11+. Example: false.","type":"boolean"}},"required":["people","hasMore"],"additionalProperties":false},"examples":[{"title":"A vendor with verified contacts","description":"The first contact's address has been validated twice — the newest entry is the current verdict. The second contact has a phone number only, so no validations are possible.","request":{"id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53"},"response":{"people":[{"id":"d3a71f60-9c28-4b45-8e13-5a7f0c2d6b91","fullName":"Dana Whitfield","emailAddress":"d.whitfield@example-contracting.com","phoneNumber":"+1 555-0142","emailValidations":[{"id":"8f14c2b7-06d3-4e59-a82f-1b7d5e0c3a64","emailAddress":"d.whitfield@example-contracting.com","isDeliverable":true,"createdAt":"2026-05-22T14:08:31.204Z"},{"id":"2c9e5a83-7b41-4d06-9f28-3e6b0d1c8a75","emailAddress":"d.whitfield@example-contracting.com","isDeliverable":false,"createdAt":"2025-11-03T09:41:17.882Z"}]},{"id":"6b0f8d25-4a93-4c71-8e50-9d2c7f1a3b64","fullName":"Marcus Iwuoha","emailAddress":null,"phoneNumber":"+1 555-0177","emailValidations":[]}],"hasMore":false}},{"title":"A vendor with no recorded contacts","description":"Common for vendors known only from federal award records, which publish a company but no named point of contact. An empty list, not a 404 — the same response an unknown vendor id produces.","request":{"id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28"},"response":{"people":[],"hasMore":false}}]}]},{"procedure":"vendors.get-buyers","versions":[{"version":"2026-07-05","description":"The government buyers a vendor does business with, as a flat buyer-tier tree. Each row is one buyer tier: either a tier the vendor's own activity attaches to (`isLinked: true`) or an ancestor included so the client can nest the list into complete trees up to each root. `rfpCount` and `awardCount` are rolled up — an ancestor's counts include every descendant's — so a parent's numbers routinely exceed those of the linked tier beneath it. Rows are ordered alphabetically by `namePretty`, and the whole set is returned at once (no paging, no `hasMore`). Counts are computed over the vendor's 5,000 most recent follows and 5,000 most recent awards. An unknown vendor id returns an empty list rather than an error; unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The vendor's Bidscope id (`leads.id`, as returned by `vendors.search` as `\"vendors.id\"`). Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"buyers":{"description":"Every buyer tier the vendor is linked to, plus all of their ancestors, as a flat list ordered alphabetically by `namePretty`. Not a page — there is no limit and no `hasMore`; the counts behind it are computed over the vendor's 5,000 most recent follows and 5,000 most recent awards, so extremely prolific federal primes get a recency-windowed approximation. Empty when the vendor has no followed solicitations and no awards that resolve to a consolidated buyer tier.","type":"array","items":{"type":"object","properties":{"id":{"description":"The buyer tier's Bidscope id; pass it to `buyers.get`. Example: \"a4f1b208-6c7d-4e93-8b25-1f0a3d9c6e47\".","type":"string"},"namePretty":{"description":"The tier's own display name — just this level, not the full hierarchy path (contrast `vendors.get-awards`'s `buyer_name`, which is the hierarchy string). Example: \"Defense Logistics Agency\".","type":"string"},"parentBuyerTierId":{"description":"The id of this tier's parent, or null when the tier is a root (a top-level government/organisation). Every non-null value is guaranteed to also appear as an `id` in this same array, so the flat list always nests into complete trees. Example: \"7b3e9d41-0a56-4c82-9e17-5d4f8b2a6c09\".","anyOf":[{"type":"string"},{"type":"null"}]},"rfpCount":{"description":"How many distinct solicitations this vendor followed under this tier OR any of its descendants — counts roll up the tree, so an ancestor's number is always >= the sum it contributes from below (distinct-counted, so one solicitation reaching the tier through several raw buyers still counts once). 0 when the vendor only won awards under this branch and followed nothing. Example: 12.","type":"number"},"awardCount":{"description":"How many distinct contracts this vendor won under this tier OR any of its descendants, rolled up and distinct-counted the same way as `rfpCount`. 0 when the vendor only followed solicitations under this branch. Example: 4.","type":"number"},"isLinked":{"description":"True when the vendor's own activity attaches directly to THIS tier (a followed solicitation or a won award resolved to exactly this buyer tier). False for a tier that is present only as an ancestor needed to complete the tree — such rows still carry rolled-up counts from their descendants. Example: true.","type":"boolean"}},"required":["id","namePretty","parentBuyerTierId","rfpCount","awardCount","isLinked"],"additionalProperties":false}}},"required":["buyers"],"additionalProperties":false},"examples":[{"title":"A vendor active across two federal branches","description":"Note that the two roots are returned flat alongside their children — nest them yourself via `parentBuyerTierId`.","request":{"id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53"},"response":{"buyers":[{"id":"a4f1b208-6c7d-4e93-8b25-1f0a3d9c6e47","namePretty":"Defense Logistics Agency","parentBuyerTierId":"7b3e9d41-0a56-4c82-9e17-5d4f8b2a6c09","rfpCount":9,"awardCount":3,"isLinked":true},{"id":"7b3e9d41-0a56-4c82-9e17-5d4f8b2a6c09","namePretty":"Department of Defense","parentBuyerTierId":null,"rfpCount":9,"awardCount":3,"isLinked":false},{"id":"e8c50a73-1d62-4f09-b3a8-6c9e2f7d0b14","namePretty":"General Services Administration","parentBuyerTierId":null,"rfpCount":2,"awardCount":1,"isLinked":true}]}},{"title":"Roll-up: an ancestor's counts exceed any single linked tier's","description":"The vendor won work under two sibling offices (4 + 2 awards). Their shared parent \"Department of the Navy\" is not itself linked (`isLinked: false`) yet reports `awardCount: 6` — the sum rolled up from both children. The root reports the same 6 plus the 3 solicitations followed under one office. Do not add sibling counts to an ancestor's: the ancestor already includes them.","request":{"id":"c19f4a80-52b7-4d36-8e0a-9b3c7f1d5e62"},"response":{"buyers":[{"id":"1a7d3e95-8c04-4b21-9f6e-2d5a0c8b7f34","namePretty":"Department of Defense","parentBuyerTierId":null,"rfpCount":3,"awardCount":6,"isLinked":false},{"id":"36b0c8f2-4e19-4a75-b8d3-0c7f5a2e9d61","namePretty":"Department of the Navy","parentBuyerTierId":"1a7d3e95-8c04-4b21-9f6e-2d5a0c8b7f34","rfpCount":3,"awardCount":6,"isLinked":false},{"id":"9e2f6b41-7a38-4c50-8d19-3b6e0f4a2c85","namePretty":"Naval Facilities Engineering Systems Command","parentBuyerTierId":"36b0c8f2-4e19-4a75-b8d3-0c7f5a2e9d61","rfpCount":3,"awardCount":4,"isLinked":true},{"id":"b5c81d07-2f64-4e93-a017-8d2c6b9f0a53","namePretty":"Naval Sea Systems Command","parentBuyerTierId":"36b0c8f2-4e19-4a75-b8d3-0c7f5a2e9d61","rfpCount":0,"awardCount":2,"isLinked":true}]}}]}]},{"procedure":"vendors.get-activity","versions":[{"version":"2026-07-05","description":"A vendor's recent market activity. Each row is one event: the vendor engaged with a solicitation (`activity.rfp.id` set, `activity.action` describing how — downloaded documents, placed a bid, registered as a prospective bidder, or followed) or was awarded a contract (`activity.award.id` set, `activity.action` `\"awarded\"`). The two are mutually exclusive per row. Returns the 10 most recent, newest first by `activity.date`, with `hasMore` true when more exist; there is no paging here, use `vendor-activity.search` for the full feed. Rows use the same keys as `vendor-activity.search` results. An unknown or suppressed vendor id returns an empty list rather than an error; unexpected failures return 500.","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"The vendor's Bidscope id (`leads.id`, as returned by `vendors.search` as `\"vendors.id\"`). Example: \"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"description":"The vendor's 10 most recent activity events, newest first by `activity.date`. One row is one thing the vendor did: engaged with a solicitation, or won a contract. Follows whose underlying record was later removed by deduplication are excluded. Empty when the vendor has no recorded activity (and also for an id that matches no vendor, or one that has been suppressed).","type":"array","items":{"type":"object","properties":{"activity.id":{"description":"The activity row's Bidscope id (`lead_activity.id`). Example: \"f47a0c39-8b25-4e61-9d03-7c5f2a8e1b60\".","type":"string"},"activity.date":{"type":"string","format":"date-time","description":"When the activity happened — the source-reported timestamp, falling back to when Bidscope recorded the row if the source published none. This is the sort key. Example: \"2026-06-14T17:22:05.113Z\"."},"activity.action":{"description":"What the vendor did. `\"awarded\"` for a won contract; otherwise the way the vendor engaged with a solicitation, one of `\"download-documents\"`, `\"placed-bid\"`, `\"prospective-bidder\"` or `\"follow\"` (in rough order of buying signal — a placed bid is stronger evidence than appearing on a plan-holder list). Null only if the underlying follow record carries no type. Example: \"placed-bid\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.rfp.id":{"description":"The Bidscope id of the solicitation the vendor engaged with; pass it to `opportunities.get`. Null on award rows. Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.rfp.title":{"description":"Title of that solicitation — Bidscope's AI-extracted title, falling back to the raw title published by the source. Null on award rows. Example: \"Tactical Vehicle Repair Kits\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.award.id":{"description":"The Bidscope id of the contract the vendor won; pass it to `awards.get`. Null on solicitation-follow rows. Exactly one of `activity.rfp.id` / `activity.award.id` is set per row — the two are mutually exclusive by design. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.award.title":{"description":"Title of that contract as reported by the awarding source. Null on solicitation-follow rows, and also on award rows whose source published no title. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.name_pretty":{"description":"The vendor's display name — the same on every row here, since all rows belong to the requested vendor. Present because these rows share their shape with `vendor-activity.search`, where the feed spans many vendors. Example: \"Ridgeline Tactical Supply LLC\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["activity.id","activity.date","activity.action","activity.rfp.id","activity.rfp.title","activity.award.id","activity.award.title","vendors.name_pretty"],"additionalProperties":false}},"hasMore":{"description":"True when the vendor has more than 10 activity events. This endpoint has no paging — use `vendor-activity.search` filtered to the vendor to go deeper. Example: true.","type":"boolean"}},"required":["items","hasMore"],"additionalProperties":false},"examples":[{"title":"A vendor's mixed follow-and-win feed","description":"Read each row as a sentence: vendor + `activity.action` + the solicitation or contract title. Here the vendor won a contract, then bid on and downloaded documents for other solicitations.","request":{"id":"5d2c7f18-3a94-4e60-b7c1-8e0f2a6d4b53"},"response":{"items":[{"activity.id":"f47a0c39-8b25-4e61-9d03-7c5f2a8e1b60","activity.date":"2026-06-14T17:22:05.113Z","activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","activity.award.title":"Facility HVAC Maintenance Services","vendors.name_pretty":"Ridgeline Tactical Supply LLC"},{"activity.id":"a08d5f16-3c74-4b92-8e05-1f6a9d2c7b43","activity.date":"2026-05-30T11:04:48.671Z","activity.action":"placed-bid","activity.rfp.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","activity.rfp.title":"Tactical Vehicle Repair Kits","activity.award.id":null,"activity.award.title":null,"vendors.name_pretty":"Ridgeline Tactical Supply LLC"},{"activity.id":"7d2b6e04-9a13-4f58-b0c7-5e8d3f1a6c92","activity.date":"2026-05-12T08:15:00.000Z","activity.action":"download-documents","activity.rfp.id":"9c0b6e31-77af-4f2a-8b19-4d3e2c1a5f68","activity.rfp.title":"Cold Weather Shelter Systems","activity.award.id":null,"activity.award.title":null,"vendors.name_pretty":"Ridgeline Tactical Supply LLC"}],"hasMore":true}},{"title":"A vendor with no recorded activity","description":"Vendors sourced purely from a registration — never seen on a bidder list, never matched to an award — have an empty feed. An empty list, not a 404.","request":{"id":"0f6b2c94-8d51-4a37-9e0b-4c1d7f3a6b28"},"response":{"items":[],"hasMore":false}}]}]},{"procedure":"vendor-activity.search","versions":[{"version":"2026-07-05","description":"A cross-vendor feed of market activity, scored against one of your matching profiles.\n\nOne row is one thing a vendor did. Either the vendor FOLLOWED a solicitation — downloaded its documents, placed a bid, registered as a prospective bidder, or plain followed it (`activity.type: \"solicitation\"`) — or the vendor WAS AWARDED a contract (`activity.type: \"contract\"`). The two kinds are mutually exclusive, and each nulls the other's columns: award rows carry `activity.award.id` / `activity.award.title` with `activity.rfp.*` null, follow rows carry `activity.rfp.id` / `activity.rfp.title` with `activity.award.*` null. `activity.action` is the verb (\"awarded\" on contract rows; \"download-documents\", \"placed-bid\", \"prospective-bidder\" or \"follow\" on solicitation rows).\n\nEvery row carries three independent match scores, each in (0, 1] and each measured against the centroid of the `matchingProfileId` you pass:\n- `vendor_similarity_score` — how similar the VENDOR is to your profile. High = a competitor or a lookalike firm.\n- `opportunity_score` — how similar the OPPORTUNITY is to your profile. High = work you could plausibly bid yourself.\n- `complementary_score` — how well your profile complements the VENDOR on THIS opportunity. It scores you against the opportunity's smart code furthest outside that vendor's own capabilities, so a high value means the scope they most likely cannot self-perform is exactly what you do. This is the teaming/subcontracting signal: sort by it descending, optionally filtered to `activity.type = \"contract\"`, to surface primes worth approaching as a sub.\n\nA score is null (never 0) when it cannot be computed: the matching profile has no centroid yet (all three go null), the vendor has no capability inference (`vendor_similarity_score`), the opportunity has no inference (`opportunity_score`), or either side lacks embedded smart codes / the opportunity has fewer than two of them (`complementary_score`). Null scores fail any score threshold above 0 and always sort last, in either direction.\n\n`vendor_distance` and `opportunity_distance` are METRES from your organization's saved location — the vendor's own address and the opportunity's place of performance respectively. Both are null when your organization has no saved coordinates or the relevant side has no located place.\n\nOrdering is whatever `search.orderBy` / `search.sort` request, tie-broken by ingestion time (newest first) then row id; the app's default view is `activity.date` descending. Results are capped at the first 1,000 rows — a page starting at or beyond that ceiling comes back empty with `total: 0`. Otherwise `total` is always -1: this feed cannot be counted alongside its sorts, so page until `items` is shorter than `pageSize`.\n\nErrors: 404 when `matchingProfileId` does not exist, 403 when it belongs to another organization, 500 on an unexpected failure (including sorting by the filter-only columns `activity.rfp.id` / `activity.buyer.id`, which have no sortable expression).","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile to score this feed against (`matching_profiles.id`). Must belong to your organization — a profile owned by another organization returns 403, an unknown id returns 404. The profile's averaged smart-code centroid is what every row's `vendor_similarity_score`, `opportunity_score` and `complementary_score` is measured against; a profile that has no centroid yet (still processing smart codes) returns the feed with all three scores null. Example: \"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The feed's query state — the same table state the Bidscope app persists for its saved views.\n\n`orderBy` — the column to sort by. Sortable values: \"activity.date\", \"activity.type\", \"vendors.name_pretty\", \"vendors.award_count\", \"vendors.last_awarded_at\", \"vendors.naics_codes.code\", \"opportunity.naics_codes.code\", \"vendors.places.country\", \"vendors.places.region\", \"vendor_distance\", \"opportunity.places.country\", \"opportunity.places.region\", \"opportunity_distance\", \"vendor_similarity_score\", \"complementary_score\", \"opportunity_score\", \"vendors.id\", \"activity.id\". The schema also accepts the two filter-only columns \"activity.rfp.id\" and \"activity.buyer.id\", but they have no sortable SQL expression — passing either as `orderBy` fails with a 500. Unscored/empty values always sort last regardless of direction.\n\n`sort` — \"asc\" or \"desc\". For the three score columns \"desc\" means best match first.\n\n`pageSize` — rows per page; must be one of 1, 10, 25, 50, 100.\n\n`filters` — a filter tree, or null for the unfiltered feed. A node is either a group (`{ type: \"group\", isAnd, filters: [...] }`) or a leaf (`{ type: \"filter\", column, filter: { operator, value } }`). Operators: string.eq, string.contains, string.ncontains, date.before, date.after, number.gt, number.lt, enum.eq, enum.neq. Filterable columns beyond the sortable list above: \"vendors.set_asides\" (enum.eq/enum.neq against a consolidated set-aside type), \"vendors.all_naics_codes.code\" (the vendor's primary OR any secondary NAICS code), \"activity.rfp.id\" (string.eq; matches BOTH that solicitation's follow rows and its awards' award rows), \"activity.buyer.id\" (string.eq; matches everything under that buyer tier's whole subtree) and \"vendors.id\" (string.eq against the vendor's lead id). Score filters take the displayed 0–1 score, not the raw distance: `{ column: \"complementary_score\", filter: { operator: \"number.gt\", value: 0.55 } }` keeps rows scoring above 55%; unscored (null) rows fail any threshold above 0.\n\n`quickSearch` — accepted for table-state parity but ignored: the activity feed has no free-text search by design.\n\n`filterMeta` — free-form UI metadata carried alongside the view (e.g. id → label maps for the deep-link filters). Ignored by the server; it never affects results.\n\nExample: `{ \"orderBy\": \"activity.date\", \"sort\": \"desc\", \"pageSize\": 25, \"filters\": null }`.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["activity.date","activity.type","vendors.name_pretty","vendors.award_count","vendors.last_awarded_at","vendors.naics_codes.code","opportunity.naics_codes.code","vendors.places.country","vendors.places.region","vendor_distance","opportunity.places.country","opportunity.places.region","opportunity_distance","vendor_similarity_score","complementary_score","opportunity_score","activity.rfp.id","activity.buyer.id","vendors.id","activity.id"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number, applied against `search.pageSize`. Paging is capped at the first 1,000 rows: once `pageSize * (page - 1)` reaches 1,000 the response is an empty page (`items: []`, `total: 0`). Example: 1.","type":"number","minimum":1},"skipCountTotal":{"description":"Accepted for parity with the other search endpoints and otherwise ignored — this feed can never be counted alongside its sorts, so `total` is always -1. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Always -1 for this endpoint: the activity feed cannot be counted alongside its sorts, so the total is never known — page until `items` comes back shorter than `pageSize`. The one exception is the paging ceiling: a page starting at or beyond row 1,000 returns `total: 0` with an empty `items`. Example: -1.","type":"number"},"items":{"description":"One page of activity rows, in the order requested by `search.orderBy` / `search.sort`, tie-broken by ingestion time (newest first) then row id. Empty when nothing matches, or when the page starts at or beyond the 1,000-row ceiling.","type":"array","items":{"type":"object","properties":{"activity.id":{"description":"The activity row's id (`lead_activity.id`) — unique per row and stable, so it works as a de-duplication key across polls. Example: \"d41c8a67-3b95-4e02-8f7a-2c6b91e4d503\".","type":"string"},"activity.date":{"type":"string","format":"date-time","description":"When the activity happened: the recorded occurrence time for award rows, falling back to when Bidscope ingested the row (follow rows generally carry no separate occurrence time, so this is their ingestion time). This is the column the default feed sorts on. Example: \"2026-07-14T00:00:00.000Z\"."},"activity.type":{"description":"What kind of opportunity the row is about, derived from which side of the row is populated. One of \"solicitation\" (the vendor followed an open solicitation — `activity.rfp.*` is set, `activity.award.*` is null) or \"contract\" (the vendor was awarded a contract — `activity.award.*` is set, `activity.rfp.*` is null). Never null in practice. Example: \"solicitation\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.id":{"description":"The vendor's Bidscope id; pass it to `vendors.get`. Present on every row (the feed is joined to the vendor record). Example: \"8ad3f21c-6e07-4b59-9d84-0f5a7c2e6b19\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.name_pretty":{"description":"The vendor's cleaned-up display name, null when the vendor record has no normalized name. Example: \"Cedar Ridge Mechanical LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.award_count":{"description":"How many contract awards Bidscope has recorded for this vendor in total — a denormalized lifetime counter on the vendor record, not a count of the rows in this feed. 0 for a vendor with no known awards. Example: 37.","anyOf":[{"type":"number"},{"type":"null"}]},"vendors.last_awarded_at":{"type":["string","null"],"format":"date-time","description":"When this vendor was most recently awarded a contract (again lifetime, across all buyers), null when Bidscope has no awards for them. Example: \"2026-05-22T00:00:00.000Z\"."},"vendors.naics_codes.code":{"description":"The vendor's own primary NAICS code — what the vendor normally does, independent of this row's opportunity. Null when no primary code has been determined. Secondary codes are not returned (they are filterable via \"vendors.all_naics_codes.code\"). Example: \"238220\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.set_asides":{"description":"The vendor's socio-economic certifications, consolidated from their raw registrations onto the canonical set-aside types: \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Native-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\". Sorted alphabetically; an empty array when the vendor holds no recognized certification. Example: [\"Service-Disabled Veteran-Owned Business\", \"Small Business\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"opportunity.naics_codes.code":{"description":"The NAICS code of the opportunity the row is about — the awarded contract's code on \"contract\" rows, the followed solicitation's inferred code on \"solicitation\" rows. Null when that side has no classified code. Compare against `vendors.naics_codes.code` to spot vendors working outside their usual line of business. Example: \"541330\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.places.country":{"description":"The country of the vendor's own registered location, null when the vendor has no resolved location. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.places.region":{"description":"The state/province of the vendor's own registered location, null when the vendor has no resolved location (or the location resolved only to a country). Example: \"Texas\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_distance":{"description":"How far the vendor's own location is from your organization's saved location, in METRES (the Bidscope app renders it as miles). Null when your organization has no saved coordinates or the vendor has no located address. Example: 152340 (about 95 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"opportunity.places.country":{"description":"The country of the opportunity's place of performance — the awarded contract's place of performance on \"contract\" rows, the solicitation's inferred place on \"solicitation\" rows. Null when neither side resolved a place. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"opportunity.places.region":{"description":"The state/province of the opportunity's place of performance (see `opportunity.places.country` for how it is sourced), null when unresolved. Note this is where the WORK is, which is frequently not where the vendor is. Example: \"New Mexico\".","anyOf":[{"type":"string"},{"type":"null"}]},"opportunity_distance":{"description":"How far the opportunity's place of performance is from your organization's saved location, in METRES. Null when your organization has no saved coordinates or the opportunity has no located place of performance. Example: 48280 (about 30 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"vendor_similarity_score":{"description":"How similar this VENDOR is to your matching profile, in (0, 1] — 1 is a near-identical capability profile. Derived from the cosine distance between the profile's centroid and the vendor's own capability centroid, calibrated onto a 0–1 match score. Use it to find competitors and lookalike firms. Null when the vendor has no capability inference yet, or when the matching profile has no centroid. Example: 0.82.","anyOf":[{"type":"number"},{"type":"null"}]},"complementary_score":{"description":"How well your profile COMPLEMENTS this vendor on this specific opportunity, in (0, 1] — the teaming/subcontracting signal (the Bidscope app labels it \"Sub Match\"). It scores your profile against the opportunity's smart code that sits FURTHEST OUTSIDE this vendor's own capabilities: a high value means the part of the work this vendor most likely cannot self-perform is squarely in your wheelhouse, so they are a plausible prime to approach. Null when either side lacks an inference or embedded smart codes, when the opportunity carries fewer than two embedded codes (\"furthest outside\" is meaningless with one), or when the matching profile has no centroid. Example: 0.74.","anyOf":[{"type":"number"},{"type":"null"}]},"opportunity_score":{"description":"How similar the OPPORTUNITY itself is to your matching profile, in (0, 1] — the awarded contract's centroid on \"contract\" rows, the solicitation's centroid on \"solicitation\" rows. This is the ordinary \"could we bid this ourselves\" match, and it is deliberately independent of `complementary_score` (work you could prime vs. work you could sub). Null when that side has no inference, or when the matching profile has no centroid. Example: 0.61.","anyOf":[{"type":"number"},{"type":"null"}]},"activity.action":{"description":"The verb — exactly what the vendor did. On \"contract\" rows always \"awarded\". On \"solicitation\" rows one of \"download-documents\" (pulled the bid package), \"placed-bid\" (submitted a bid), \"prospective-bidder\" (registered interest on the portal's bidders list; also the default when a source publishes a follower without a kind) or \"follow\" (followed/watched the solicitation). Example: \"download-documents\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.rfp.id":{"description":"The followed solicitation's Bidscope id; pass it to `opportunities.get`. Set on \"solicitation\" rows, ALWAYS null on \"contract\" rows (award activity is linked to the contract, not the solicitation — resolve the solicitation via `awards.get-solicitations` instead). Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.rfp.title":{"description":"The followed solicitation's title, preferring Bidscope's cleaned-up inferred title over the raw crawled one. Null on \"contract\" rows, and on \"solicitation\" rows where neither title exists. Example: \"Boiler Replacement — Building 12\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.award.id":{"description":"The awarded contract's Bidscope id; pass it to `awards.get`. Set on \"contract\" rows, ALWAYS null on \"solicitation\" rows. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.award.title":{"description":"The awarded contract's title as reported by the awarding source. Null on \"solicitation\" rows, and on \"contract\" rows where the source published no title. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["activity.id","activity.date","activity.type","vendors.id","vendors.name_pretty","vendors.award_count","vendors.last_awarded_at","vendors.naics_codes.code","vendors.set_asides","opportunity.naics_codes.code","vendors.places.country","vendors.places.region","vendor_distance","opportunity.places.country","opportunity.places.region","opportunity_distance","vendor_similarity_score","complementary_score","opportunity_score","activity.action","activity.rfp.id","activity.rfp.title","activity.award.id","activity.award.title"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"The recent feed — a follow row and an award row","description":"The default view: newest activity first, unfiltered. The first row is a solicitation follow (`activity.rfp.*` set, `activity.award.*` null); the second is a contract award (`activity.award.*` set, `activity.rfp.*` null). Note `total` is -1, not a count.","request":{"matchingProfileId":"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9","search":{"orderBy":"activity.date","sort":"desc","pageSize":25,"filters":null},"page":1,"skipCountTotal":true},"response":{"total":-1,"items":[{"activity.id":"d41c8a67-3b95-4e02-8f7a-2c6b91e4d503","activity.date":"2026-07-14T16:05:00.000Z","activity.type":"solicitation","vendors.id":"8ad3f21c-6e07-4b59-9d84-0f5a7c2e6b19","vendors.name_pretty":"Cedar Ridge Mechanical LLC","vendors.award_count":37,"vendors.last_awarded_at":"2026-05-22T00:00:00.000Z","vendors.naics_codes.code":"238220","vendors.set_asides":["Small Business"],"opportunity.naics_codes.code":"238220","vendors.places.country":"United States","vendors.places.region":"Texas","vendor_distance":152340,"opportunity.places.country":"United States","opportunity.places.region":"Texas","opportunity_distance":48280,"vendor_similarity_score":0.82,"complementary_score":0.41,"opportunity_score":0.77,"activity.action":"download-documents","activity.rfp.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","activity.rfp.title":"Boiler Replacement — Building 12","activity.award.id":null,"activity.award.title":null},{"activity.id":"0b7e5d92-14fa-4c31-8b60-9e3d7a1c5f26","activity.date":"2026-07-13T00:00:00.000Z","activity.type":"contract","vendors.id":"5c9e0a34-7d21-4f86-b013-8a4e2c7d9f15","vendors.name_pretty":"Harbor Point Engineering Inc","vendors.award_count":112,"vendors.last_awarded_at":"2026-07-13T00:00:00.000Z","vendors.naics_codes.code":"541330","vendors.set_asides":[],"opportunity.naics_codes.code":"541330","vendors.places.country":"United States","vendors.places.region":"Virginia","vendor_distance":null,"opportunity.places.country":"United States","opportunity.places.region":"New Mexico","opportunity_distance":1284500,"vendor_similarity_score":0.58,"complementary_score":0.69,"opportunity_score":0.63,"activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","activity.award.title":"Facility HVAC Maintenance Services"}]}},{"title":"Teaming prospects — best complementary match first","description":"Primes worth approaching as a subcontractor: contract awards only, `complementary_score` above 55%, restricted to small-business primes, sorted by `complementary_score` descending. A high complementary score with a modest `vendor_similarity_score` is the ideal teaming shape — they win work you do not compete for, but part of that work is yours to sub.","request":{"matchingProfileId":"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9","search":{"orderBy":"complementary_score","sort":"desc","pageSize":10,"filters":{"type":"group","isAnd":true,"filters":[{"type":"filter","column":"activity.type","filter":{"operator":"enum.eq","value":"contract"}},{"type":"filter","column":"complementary_score","filter":{"operator":"number.gt","value":0.55}},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Small Business"}},{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Service-Disabled Veteran-Owned Business"}}]}]},"filterMeta":{"quickFilter":"complementary"}},"page":1,"skipCountTotal":true},"response":{"total":-1,"items":[{"activity.id":"a6d20f88-51c7-4b93-8e14-7f0b3c9d6e25","activity.date":"2026-07-09T00:00:00.000Z","activity.type":"contract","vendors.id":"e37b1c60-9a54-4d28-b7f1-06c8e2a5d934","vendors.name_pretty":"Blue Mesa Constructors LLC","vendors.award_count":24,"vendors.last_awarded_at":"2026-07-09T00:00:00.000Z","vendors.naics_codes.code":"236220","vendors.set_asides":["Service-Disabled Veteran-Owned Business","Small Business"],"opportunity.naics_codes.code":"236220","vendors.places.country":"United States","vendors.places.region":"Arizona","vendor_distance":604000,"opportunity.places.country":"United States","opportunity.places.region":"Arizona","opportunity_distance":591000,"vendor_similarity_score":0.29,"complementary_score":0.88,"opportunity_score":0.34,"activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"7c1a4e90-2b68-4f37-9d05-3a8e6b1c0d42","activity.award.title":"Design-Build — Vehicle Maintenance Facility"},{"activity.id":"12f9b3c7-8e40-4a65-9c2d-5b7e1f0a8d36","activity.date":"2026-07-02T00:00:00.000Z","activity.type":"contract","vendors.id":"9b0d7e15-4c38-42fa-8613-2e5a9c7f0d84","vendors.name_pretty":"Ironwood Site Services Inc","vendors.award_count":8,"vendors.last_awarded_at":"2026-07-02T00:00:00.000Z","vendors.naics_codes.code":"238910","vendors.set_asides":["Small Business"],"opportunity.naics_codes.code":"237310","vendors.places.country":"United States","vendors.places.region":"Nevada","vendor_distance":712000,"opportunity.places.country":"United States","opportunity.places.region":"Nevada","opportunity_distance":698000,"vendor_similarity_score":0.33,"complementary_score":0.61,"opportunity_score":null,"activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"4e8c2a71-0f95-4b63-8a27-1d6b5e9c3f08","activity.award.title":"Airfield Apron Rehabilitation"}]}},{"title":"Who is chasing one specific solicitation","description":"The \"activity.rfp.id\" filter is deliberately two-sided: it matches that solicitation's follow rows AND the award rows of any contract that resulted from it, so one id gives you the whole competitive picture. Here the profile has no centroid yet, so all three scores come back null rather than 0.","request":{"matchingProfileId":"c8e1740b-63a9-4d52-9f07-2b5e8a1c4d63","search":{"orderBy":"activity.date","sort":"desc","pageSize":50,"filters":{"type":"filter","column":"activity.rfp.id","filter":{"operator":"string.eq","value":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30"}}},"page":1},"response":{"total":-1,"items":[{"activity.id":"6a2f80d5-9c17-4e3b-b840-71e5c2a9d0b3","activity.date":"2026-06-28T09:12:00.000Z","activity.type":"solicitation","vendors.id":"2d5b8f04-1a76-4c39-9e08-6b3c7d1e5a92","vendors.name_pretty":"Summit Valley Contractors LLC","vendors.award_count":0,"vendors.last_awarded_at":null,"vendors.naics_codes.code":null,"vendors.set_asides":[],"opportunity.naics_codes.code":"238220","vendors.places.country":"United States","vendors.places.region":"Texas","vendor_distance":null,"opportunity.places.country":"United States","opportunity.places.region":"Texas","opportunity_distance":null,"vendor_similarity_score":null,"complementary_score":null,"opportunity_score":null,"activity.action":"placed-bid","activity.rfp.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","activity.rfp.title":"Boiler Replacement — Building 12","activity.award.id":null,"activity.award.title":null}]}},{"title":"Past the 1,000-row ceiling","description":"Paging is capped at the first 1,000 rows. With `pageSize: 25`, page 41 starts at row 1,000 — the response is empty and `total` is 0 rather than the usual -1.","request":{"matchingProfileId":"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9","search":{"orderBy":"activity.date","sort":"desc","pageSize":25,"filters":null},"page":41},"response":{"total":0,"items":[]}}]},{"version":"2026-08-19","description":"A cross-vendor feed of market activity, scored against one of your matching profiles.\n\nOne row is one thing a vendor did. Either the vendor FOLLOWED a solicitation — downloaded its documents, placed a bid, registered as a prospective bidder, or plain followed it (`activity.type: \"solicitation\"`) — or the vendor WAS AWARDED a contract (`activity.type: \"contract\"`). The two kinds are mutually exclusive, and each nulls the other's columns: award rows carry `activity.award.id` / `activity.award.title` with `activity.rfp.*` null, follow rows carry `activity.rfp.id` / `activity.rfp.title` with `activity.award.*` null. `activity.action` is the verb (\"awarded\" on contract rows; \"download-documents\", \"placed-bid\", \"prospective-bidder\" or \"follow\" on solicitation rows).\n\nEvery row carries three independent match scores, each in (0, 1] and each measured against the centroid of the `matchingProfileId` you pass:\n- `vendor_similarity_score` — how similar the VENDOR is to your profile. High = a competitor or a lookalike firm.\n- `opportunity_score` — how similar the OPPORTUNITY is to your profile. High = work you could plausibly bid yourself.\n- `complementary_score` — how well your profile complements the VENDOR on THIS opportunity. It scores you against the opportunity's smart code furthest outside that vendor's own capabilities, so a high value means the scope they most likely cannot self-perform is exactly what you do. This is the teaming/subcontracting signal: sort by it descending, optionally filtered to `activity.type = \"contract\"`, to surface primes worth approaching as a sub.\n\nA score is null (never 0) when it cannot be computed: the matching profile has no centroid yet (all three go null), the vendor has no capability inference (`vendor_similarity_score`), the opportunity has no inference (`opportunity_score`), or either side lacks embedded smart codes / the opportunity has fewer than two of them (`complementary_score`). Null scores fail any score threshold above 0 and always sort last, in either direction.\n\n`vendor_distance` and `opportunity_distance` are METRES from the request's `location` when supplied, otherwise your organization's saved location — the vendor's own address and the opportunity's place of performance respectively. Both are null when your organization has no saved coordinates or the relevant side has no located place.\n\nOrdering is whatever `search.orderBy` / `search.sort` request, tie-broken by ingestion time (newest first) then row id; the app's default view is `activity.date` descending. Results are capped at the first 1,000 rows — a page starting at or beyond that ceiling comes back empty with `total: 0`. Otherwise `total` is always -1: this feed cannot be counted alongside its sorts, so page until `items` is shorter than `pageSize`.\n\nErrors: 404 when `matchingProfileId` does not exist, 403 when it belongs to another organization, 500 on an unexpected failure (including sorting by the filter-only columns `activity.rfp.id` / `activity.buyer.id`, which have no sortable expression).","plans":["starter","professional","business"],"requestSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"matchingProfileId":{"description":"The matching profile to score this feed against (`matching_profiles.id`). Must belong to your organization — a profile owned by another organization returns 403, an unknown id returns 404. The profile's averaged smart-code centroid is what every row's `vendor_similarity_score`, `opportunity_score` and `complementary_score` is measured against; a profile that has no centroid yet (still processing smart codes) returns the feed with all three scores null. Example: \"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9\".","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"search":{"description":"The feed's query state — the same table state the Bidscope app persists for its saved views.\n\n`orderBy` — the column to sort by. Sortable values: \"activity.date\", \"activity.type\", \"vendors.name_pretty\", \"vendors.award_count\", \"vendors.last_awarded_at\", \"vendors.naics_codes.code\", \"opportunity.naics_codes.code\", \"vendors.places.country\", \"vendors.places.region\", \"vendor_distance\", \"opportunity.places.country\", \"opportunity.places.region\", \"opportunity_distance\", \"vendor_similarity_score\", \"complementary_score\", \"opportunity_score\", \"vendors.id\", \"activity.id\". The schema also accepts the two filter-only columns \"activity.rfp.id\" and \"activity.buyer.id\", but they have no sortable SQL expression — passing either as `orderBy` fails with a 500. Unscored/empty values always sort last regardless of direction.\n\n`sort` — \"asc\" or \"desc\". For the three score columns \"desc\" means best match first.\n\n`pageSize` — rows per page; must be one of 1, 10, 25, 50, 100.\n\n`filters` — a filter tree, or null for the unfiltered feed. A node is either a group (`{ type: \"group\", isAnd, filters: [...] }`) or a leaf (`{ type: \"filter\", column, filter: { operator, value } }`). Operators: string.eq, string.contains, string.ncontains, date.before, date.after, number.gt, number.lt, enum.eq, enum.neq. Filterable columns beyond the sortable list above: \"vendors.set_asides\" (enum.eq/enum.neq against a consolidated set-aside type), \"vendors.all_naics_codes.code\" (the vendor's primary OR any secondary NAICS code), \"activity.rfp.id\" (string.eq; matches BOTH that solicitation's follow rows and its awards' award rows), \"activity.buyer.id\" (string.eq; matches everything under that buyer tier's whole subtree) and \"vendors.id\" (string.eq against the vendor's lead id). Score filters take the displayed 0–1 score, not the raw distance: `{ column: \"complementary_score\", filter: { operator: \"number.gt\", value: 0.55 } }` keeps rows scoring above 55%; unscored (null) rows fail any threshold above 0.\n\n`quickSearch` — accepted for table-state parity but ignored: the activity feed has no free-text search by design.\n\n`filterMeta` — free-form UI metadata carried alongside the view (e.g. id → label maps for the deep-link filters). Ignored by the server; it never affects results.\n\nExample: `{ \"orderBy\": \"activity.date\", \"sort\": \"desc\", \"pageSize\": 25, \"filters\": null }`.","type":"object","properties":{"sort":{"type":"string","enum":["asc","desc"]},"pageSize":{"type":"number"},"filters":{"anyOf":[{"$ref":"#/$defs/__schema0"},{"type":"null"}]},"filterMeta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quickSearch":{"type":"string"},"orderBy":{"type":"string","enum":["activity.date","activity.type","vendors.name_pretty","vendors.award_count","vendors.last_awarded_at","vendors.naics_codes.code","opportunity.naics_codes.code","vendors.places.country","vendors.places.region","vendor_distance","opportunity.places.country","opportunity.places.region","opportunity_distance","vendor_similarity_score","complementary_score","opportunity_score","activity.rfp.id","activity.buyer.id","vendors.id","activity.id"]}},"required":["sort","pageSize","filters","orderBy"],"additionalProperties":false},"page":{"description":"1-based page number, applied against `search.pageSize`. Paging is capped at the first 1,000 rows: once `pageSize * (page - 1)` reaches 1,000 the response is an empty page (`items: []`, `total: 0`). Example: 1.","type":"number","minimum":1},"location":{"description":"Optional point to measure distances from. When supplied it replaces your organization's saved location as the center for the distance column(s) and any distance filter, for this request only. Omit it (or pass null) to use the organization's saved location, which is the previous behaviour. Example: { \"latitude\": 30.267153, \"longitude\": -97.743057 }.","anyOf":[{"type":"object","properties":{"latitude":{"description":"Latitude in decimal degrees. Example: 30.267153.","type":"number","minimum":-90,"maximum":90},"longitude":{"description":"Longitude in decimal degrees. Example: -97.743057.","type":"number","minimum":-180,"maximum":180}},"required":["latitude","longitude"],"additionalProperties":false},{"type":"null"}]},"skipCountTotal":{"description":"Accepted for parity with the other search endpoints and otherwise ignored — this feed can never be counted alongside its sorts, so `total` is always -1. Example: true.","type":"boolean"}},"required":["matchingProfileId","search","page"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"group"},"isAnd":{"type":"boolean"},"filters":{"type":"array","items":{"$ref":"#/$defs/__schema0"}}},"required":["type","isAnd","filters"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"filter"},"column":{"type":"string"},"filter":{"anyOf":[{"type":"object","properties":{"operator":{"type":"string","const":"string.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.contains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"string.ncontains"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.before"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"date.after"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.gt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"number.lt"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.eq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"enum.neq"},"value":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["operator","value"],"additionalProperties":false}]}},"required":["type","column","filter"],"additionalProperties":false}]}}},"responseSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"description":"Always -1 for this endpoint: the activity feed cannot be counted alongside its sorts, so the total is never known — page until `items` comes back shorter than `pageSize`. The one exception is the paging ceiling: a page starting at or beyond row 1,000 returns `total: 0` with an empty `items`. Example: -1.","type":"number"},"items":{"description":"One page of activity rows, in the order requested by `search.orderBy` / `search.sort`, tie-broken by ingestion time (newest first) then row id. Empty when nothing matches, or when the page starts at or beyond the 1,000-row ceiling.","type":"array","items":{"type":"object","properties":{"activity.id":{"description":"The activity row's id (`lead_activity.id`) — unique per row and stable, so it works as a de-duplication key across polls. Example: \"d41c8a67-3b95-4e02-8f7a-2c6b91e4d503\".","type":"string"},"activity.date":{"type":"string","format":"date-time","description":"When the activity happened: the recorded occurrence time for award rows, falling back to when Bidscope ingested the row (follow rows generally carry no separate occurrence time, so this is their ingestion time). This is the column the default feed sorts on. Example: \"2026-07-14T00:00:00.000Z\"."},"activity.type":{"description":"What kind of opportunity the row is about, derived from which side of the row is populated. One of \"solicitation\" (the vendor followed an open solicitation — `activity.rfp.*` is set, `activity.award.*` is null) or \"contract\" (the vendor was awarded a contract — `activity.award.*` is set, `activity.rfp.*` is null). Never null in practice. Example: \"solicitation\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.id":{"description":"The vendor's Bidscope id; pass it to `vendors.get`. Present on every row (the feed is joined to the vendor record). Example: \"8ad3f21c-6e07-4b59-9d84-0f5a7c2e6b19\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.name_pretty":{"description":"The vendor's cleaned-up display name, null when the vendor record has no normalized name. Example: \"Cedar Ridge Mechanical LLC\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.award_count":{"description":"How many contract awards Bidscope has recorded for this vendor in total — a denormalized lifetime counter on the vendor record, not a count of the rows in this feed. 0 for a vendor with no known awards. Example: 37.","anyOf":[{"type":"number"},{"type":"null"}]},"vendors.last_awarded_at":{"type":["string","null"],"format":"date-time","description":"When this vendor was most recently awarded a contract (again lifetime, across all buyers), null when Bidscope has no awards for them. Example: \"2026-05-22T00:00:00.000Z\"."},"vendors.naics_codes.code":{"description":"The vendor's own primary NAICS code — what the vendor normally does, independent of this row's opportunity. Null when no primary code has been determined. Secondary codes are not returned (they are filterable via \"vendors.all_naics_codes.code\"). Example: \"238220\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.set_asides":{"description":"The vendor's socio-economic certifications, consolidated from their raw registrations onto the canonical set-aside types: \"Small Business\", \"Woman-Owned Business\", \"Veteran-Owned Business\", \"Service-Disabled Veteran-Owned Business\", \"Native-Owned Business\", \"Disadvantaged Business\", \"Minority-Owned Business\". Sorted alphabetically; an empty array when the vendor holds no recognized certification. Example: [\"Service-Disabled Veteran-Owned Business\", \"Small Business\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"opportunity.naics_codes.code":{"description":"The NAICS code of the opportunity the row is about — the awarded contract's code on \"contract\" rows, the followed solicitation's inferred code on \"solicitation\" rows. Null when that side has no classified code. Compare against `vendors.naics_codes.code` to spot vendors working outside their usual line of business. Example: \"541330\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.places.country":{"description":"The country of the vendor's own registered location, null when the vendor has no resolved location. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendors.places.region":{"description":"The state/province of the vendor's own registered location, null when the vendor has no resolved location (or the location resolved only to a country). Example: \"Texas\".","anyOf":[{"type":"string"},{"type":"null"}]},"vendor_distance":{"description":"How far the vendor's own location is from the request's `location` when supplied, and otherwise from your organization's saved location, in METRES (the Bidscope app renders it as miles). Null when your organization has no saved coordinates or the vendor has no located address. Example: 152340 (about 95 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"opportunity.places.country":{"description":"The country of the opportunity's place of performance — the awarded contract's place of performance on \"contract\" rows, the solicitation's inferred place on \"solicitation\" rows. Null when neither side resolved a place. Example: \"United States\".","anyOf":[{"type":"string"},{"type":"null"}]},"opportunity.places.region":{"description":"The state/province of the opportunity's place of performance (see `opportunity.places.country` for how it is sourced), null when unresolved. Note this is where the WORK is, which is frequently not where the vendor is. Example: \"New Mexico\".","anyOf":[{"type":"string"},{"type":"null"}]},"opportunity_distance":{"description":"How far the opportunity's place of performance is from the request's `location` when supplied, and otherwise from your organization's saved location, in METRES. Null when your organization has no saved coordinates or the opportunity has no located place of performance. Example: 48280 (about 30 miles).","anyOf":[{"type":"number"},{"type":"null"}]},"vendor_similarity_score":{"description":"How similar this VENDOR is to your matching profile, in (0, 1] — 1 is a near-identical capability profile. Derived from the cosine distance between the profile's centroid and the vendor's own capability centroid, calibrated onto a 0–1 match score. Use it to find competitors and lookalike firms. Null when the vendor has no capability inference yet, or when the matching profile has no centroid. Example: 0.82.","anyOf":[{"type":"number"},{"type":"null"}]},"complementary_score":{"description":"How well your profile COMPLEMENTS this vendor on this specific opportunity, in (0, 1] — the teaming/subcontracting signal (the Bidscope app labels it \"Sub Match\"). It scores your profile against the opportunity's smart code that sits FURTHEST OUTSIDE this vendor's own capabilities: a high value means the part of the work this vendor most likely cannot self-perform is squarely in your wheelhouse, so they are a plausible prime to approach. Null when either side lacks an inference or embedded smart codes, when the opportunity carries fewer than two embedded codes (\"furthest outside\" is meaningless with one), or when the matching profile has no centroid. Example: 0.74.","anyOf":[{"type":"number"},{"type":"null"}]},"opportunity_score":{"description":"How similar the OPPORTUNITY itself is to your matching profile, in (0, 1] — the awarded contract's centroid on \"contract\" rows, the solicitation's centroid on \"solicitation\" rows. This is the ordinary \"could we bid this ourselves\" match, and it is deliberately independent of `complementary_score` (work you could prime vs. work you could sub). Null when that side has no inference, or when the matching profile has no centroid. Example: 0.61.","anyOf":[{"type":"number"},{"type":"null"}]},"activity.action":{"description":"The verb — exactly what the vendor did. On \"contract\" rows always \"awarded\". On \"solicitation\" rows one of \"download-documents\" (pulled the bid package), \"placed-bid\" (submitted a bid), \"prospective-bidder\" (registered interest on the portal's bidders list; also the default when a source publishes a follower without a kind) or \"follow\" (followed/watched the solicitation). Example: \"download-documents\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.rfp.id":{"description":"The followed solicitation's Bidscope id; pass it to `opportunities.get`. Set on \"solicitation\" rows, ALWAYS null on \"contract\" rows (award activity is linked to the contract, not the solicitation — resolve the solicitation via `awards.get-solicitations` instead). Example: \"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.rfp.title":{"description":"The followed solicitation's title, preferring Bidscope's cleaned-up inferred title over the raw crawled one. Null on \"contract\" rows, and on \"solicitation\" rows where neither title exists. Example: \"Boiler Replacement — Building 12\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.award.id":{"description":"The awarded contract's Bidscope id; pass it to `awards.get`. Set on \"contract\" rows, ALWAYS null on \"solicitation\" rows. Example: \"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34\".","anyOf":[{"type":"string"},{"type":"null"}]},"activity.award.title":{"description":"The awarded contract's title as reported by the awarding source. Null on \"solicitation\" rows, and on \"contract\" rows where the source published no title. Example: \"Facility HVAC Maintenance Services\".","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["activity.id","activity.date","activity.type","vendors.id","vendors.name_pretty","vendors.award_count","vendors.last_awarded_at","vendors.naics_codes.code","vendors.set_asides","opportunity.naics_codes.code","vendors.places.country","vendors.places.region","vendor_distance","opportunity.places.country","opportunity.places.region","opportunity_distance","vendor_similarity_score","complementary_score","opportunity_score","activity.action","activity.rfp.id","activity.rfp.title","activity.award.id","activity.award.title"],"additionalProperties":false}}},"required":["total","items"],"additionalProperties":false},"examples":[{"title":"The recent feed — a follow row and an award row","description":"The default view: newest activity first, unfiltered. The first row is a solicitation follow (`activity.rfp.*` set, `activity.award.*` null); the second is a contract award (`activity.award.*` set, `activity.rfp.*` null). Note `total` is -1, not a count.","request":{"matchingProfileId":"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9","search":{"orderBy":"activity.date","sort":"desc","pageSize":25,"filters":null},"page":1,"skipCountTotal":true},"response":{"total":-1,"items":[{"activity.id":"d41c8a67-3b95-4e02-8f7a-2c6b91e4d503","activity.date":"2026-07-14T16:05:00.000Z","activity.type":"solicitation","vendors.id":"8ad3f21c-6e07-4b59-9d84-0f5a7c2e6b19","vendors.name_pretty":"Cedar Ridge Mechanical LLC","vendors.award_count":37,"vendors.last_awarded_at":"2026-05-22T00:00:00.000Z","vendors.naics_codes.code":"238220","vendors.set_asides":["Small Business"],"opportunity.naics_codes.code":"238220","vendors.places.country":"United States","vendors.places.region":"Texas","vendor_distance":152340,"opportunity.places.country":"United States","opportunity.places.region":"Texas","opportunity_distance":48280,"vendor_similarity_score":0.82,"complementary_score":0.41,"opportunity_score":0.77,"activity.action":"download-documents","activity.rfp.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","activity.rfp.title":"Boiler Replacement — Building 12","activity.award.id":null,"activity.award.title":null},{"activity.id":"0b7e5d92-14fa-4c31-8b60-9e3d7a1c5f26","activity.date":"2026-07-13T00:00:00.000Z","activity.type":"contract","vendors.id":"5c9e0a34-7d21-4f86-b013-8a4e2c7d9f15","vendors.name_pretty":"Harbor Point Engineering Inc","vendors.award_count":112,"vendors.last_awarded_at":"2026-07-13T00:00:00.000Z","vendors.naics_codes.code":"541330","vendors.set_asides":[],"opportunity.naics_codes.code":"541330","vendors.places.country":"United States","vendors.places.region":"Virginia","vendor_distance":null,"opportunity.places.country":"United States","opportunity.places.region":"New Mexico","opportunity_distance":1284500,"vendor_similarity_score":0.58,"complementary_score":0.69,"opportunity_score":0.63,"activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"b21f7d90-4e3c-4a68-9f11-7d2c8b5e0a34","activity.award.title":"Facility HVAC Maintenance Services"}]}},{"title":"Teaming prospects — best complementary match first","description":"Primes worth approaching as a subcontractor: contract awards only, `complementary_score` above 55%, restricted to small-business primes, sorted by `complementary_score` descending. A high complementary score with a modest `vendor_similarity_score` is the ideal teaming shape — they win work you do not compete for, but part of that work is yours to sub.","request":{"matchingProfileId":"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9","search":{"orderBy":"complementary_score","sort":"desc","pageSize":10,"filters":{"type":"group","isAnd":true,"filters":[{"type":"filter","column":"activity.type","filter":{"operator":"enum.eq","value":"contract"}},{"type":"filter","column":"complementary_score","filter":{"operator":"number.gt","value":0.55}},{"type":"group","isAnd":false,"filters":[{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Small Business"}},{"type":"filter","column":"vendors.set_asides","filter":{"operator":"enum.eq","value":"Service-Disabled Veteran-Owned Business"}}]}]},"filterMeta":{"quickFilter":"complementary"}},"page":1,"skipCountTotal":true},"response":{"total":-1,"items":[{"activity.id":"a6d20f88-51c7-4b93-8e14-7f0b3c9d6e25","activity.date":"2026-07-09T00:00:00.000Z","activity.type":"contract","vendors.id":"e37b1c60-9a54-4d28-b7f1-06c8e2a5d934","vendors.name_pretty":"Blue Mesa Constructors LLC","vendors.award_count":24,"vendors.last_awarded_at":"2026-07-09T00:00:00.000Z","vendors.naics_codes.code":"236220","vendors.set_asides":["Service-Disabled Veteran-Owned Business","Small Business"],"opportunity.naics_codes.code":"236220","vendors.places.country":"United States","vendors.places.region":"Arizona","vendor_distance":604000,"opportunity.places.country":"United States","opportunity.places.region":"Arizona","opportunity_distance":591000,"vendor_similarity_score":0.29,"complementary_score":0.88,"opportunity_score":0.34,"activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"7c1a4e90-2b68-4f37-9d05-3a8e6b1c0d42","activity.award.title":"Design-Build — Vehicle Maintenance Facility"},{"activity.id":"12f9b3c7-8e40-4a65-9c2d-5b7e1f0a8d36","activity.date":"2026-07-02T00:00:00.000Z","activity.type":"contract","vendors.id":"9b0d7e15-4c38-42fa-8613-2e5a9c7f0d84","vendors.name_pretty":"Ironwood Site Services Inc","vendors.award_count":8,"vendors.last_awarded_at":"2026-07-02T00:00:00.000Z","vendors.naics_codes.code":"238910","vendors.set_asides":["Small Business"],"opportunity.naics_codes.code":"237310","vendors.places.country":"United States","vendors.places.region":"Nevada","vendor_distance":712000,"opportunity.places.country":"United States","opportunity.places.region":"Nevada","opportunity_distance":698000,"vendor_similarity_score":0.33,"complementary_score":0.61,"opportunity_score":null,"activity.action":"awarded","activity.rfp.id":null,"activity.rfp.title":null,"activity.award.id":"4e8c2a71-0f95-4b63-8a27-1d6b5e9c3f08","activity.award.title":"Airfield Apron Rehabilitation"}]}},{"title":"Who is chasing one specific solicitation","description":"The \"activity.rfp.id\" filter is deliberately two-sided: it matches that solicitation's follow rows AND the award rows of any contract that resulted from it, so one id gives you the whole competitive picture. Here the profile has no centroid yet, so all three scores come back null rather than 0.","request":{"matchingProfileId":"c8e1740b-63a9-4d52-9f07-2b5e8a1c4d63","search":{"orderBy":"activity.date","sort":"desc","pageSize":50,"filters":{"type":"filter","column":"activity.rfp.id","filter":{"operator":"string.eq","value":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30"}}},"page":1},"response":{"total":-1,"items":[{"activity.id":"6a2f80d5-9c17-4e3b-b840-71e5c2a9d0b3","activity.date":"2026-06-28T09:12:00.000Z","activity.type":"solicitation","vendors.id":"2d5b8f04-1a76-4c39-9e08-6b3c7d1e5a92","vendors.name_pretty":"Summit Valley Contractors LLC","vendors.award_count":0,"vendors.last_awarded_at":null,"vendors.naics_codes.code":null,"vendors.set_asides":[],"opportunity.naics_codes.code":"238220","vendors.places.country":"United States","vendors.places.region":"Texas","vendor_distance":null,"opportunity.places.country":"United States","opportunity.places.region":"Texas","opportunity_distance":null,"vendor_similarity_score":null,"complementary_score":null,"opportunity_score":null,"activity.action":"placed-bid","activity.rfp.id":"3f8a1c42-9b7e-4d15-8a02-6c1d5e7f9b30","activity.rfp.title":"Boiler Replacement — Building 12","activity.award.id":null,"activity.award.title":null}]}},{"title":"Past the 1,000-row ceiling","description":"Paging is capped at the first 1,000 rows. With `pageSize: 25`, page 41 starts at row 1,000 — the response is empty and `total` is 0 rather than the usual -1.","request":{"matchingProfileId":"6f2b9d41-08ac-4e3b-9a77-5c1e04b8d2f9","search":{"orderBy":"activity.date","sort":"desc","pageSize":25,"filters":null},"page":41},"response":{"total":0,"items":[]}}]}]}]