# List awards Source: https://docs.govly.com/api-reference/enterprise/awards/list GET /api/enterprise/awards Retrieve federal contract awards with filtering by date range, unique key, or recipient ## Request At least one filter is required: `start_date`, `unique_keys[]`, or `recipient_ueis[]`. ### Date Range Filtering Start date for filtering awards by last modified date (ISO 8601 format, e.g., "2024-01-15"). Required unless filtering by `unique_keys[]` or `recipient_ueis[]`. End date for filtering awards by last modified date (ISO 8601 format). Defaults to 7 days after `start_date` if not provided. Maximum date range is 7 days. ### Identifier Filtering Array of award unique keys (e.g., FPDS PIID) to retrieve. Maximum 100 values. When provided, `start_date` is not required. Array of recipient UEIs to filter by. Maximum 100 values. When provided, `start_date` is not required. ### Pagination Number of results per page. Maximum: 100. Base64-encoded cursor for pagination. Use the `nextCursor` value from the previous response to get the next page of results. ## Response Returns an array of award objects with pagination metadata. Array of award objects Unique identifier for the award Unique identifier key for the award (e.g., FPDS PIID) External identifier for the award Title of the award Description of the award AI-generated summary of the award Award category (e.g., "contract", "grant") Govly web URL for viewing the award URL to the original government source ISO 8601 date when the award was made ISO 8601 date when the award was last modified ISO 8601 timestamp when the record was created in Govly ISO 8601 timestamp when the record was last updated in Govly ISO 8601 date of the related solicitation ISO 8601 date when the period of performance begins ISO 8601 date when the period of performance ends ISO 8601 date of the potential end date including options Total award amount in USD Maximum potential value of the award in USD Amount obligated in USD Amount paid in USD Payment structure type (e.g., "Fixed Price", "Cost Reimbursement") Type of acquisition Category of acquisition Extent of competition (e.g., "Full and Open Competition", "Not Competed") NAICS code for the award Product Service Code (PSC) Number of bids received for the award Set-aside information for the award Set-aside code Set-aside name (e.g., "Small Business Set-Aside") Unique key of the parent award (for modifications) External identifier of the parent award External ID of the related solicitation Unique key of the award recipient (UEI) Unique key of the recipient's parent organization CAGE code of the recipient Information about the award recipient Unique identifier for the recipient (UEI) Recipient organization name CAGE code Recipient address Street address line 1 Street address line 2 Street address line 3 City State or region Postal code Country AI-enriched headquarters address AI-enriched website URL Information about the buying organization Organization ID Organization name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Information about the buying office Office ID Office name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Information about the funding organization Organization ID Organization name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Information about the funding office Office ID Office name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Place of manufacture designation Location where the work is performed City State or region Postal code Country County Congressional district code Pagination metadata Base64-encoded cursor for the next page of results. Will be `null` if there are no more results. Number of results per page Start date used for filtering (ISO 8601 format) End date used for filtering (ISO 8601 format) ## Error Responses | Status Code | Condition | | - | - | | 401 | Invalid or missing API key | | 422 | Invalid parameters (see error message for details) | Common validation errors: * "At least one filter is required: start\_date, unique\_keys, or recipient\_ueis" * "Date range cannot exceed 7 days" * "unique\_keys cannot exceed 100 values" * "recipient\_ueis cannot exceed 100 values" * "Invalid start\_date format" * "Invalid end\_date format" ## Example Requests ### Filter by date range ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards?start_date=2024-01-15&end_date=2024-01-20" \ -H "X-API-KEY: your_api_key" ``` ### Filter by unique keys ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards?unique_keys[]=PIID123&unique_keys[]=PIID456" \ -H "X-API-KEY: your_api_key" ``` ### Filter by recipient UEIs ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards?recipient_ueis[]=ABC123DEF456" \ -H "X-API-KEY: your_api_key" ``` ### Paginate through results ```bash theme={null} # First request curl "https://app.govly.com/api/enterprise/awards?start_date=2024-01-15&page_size=50" \ -H "X-API-KEY: your_api_key" # Subsequent requests using cursor from previous response curl "https://app.govly.com/api/enterprise/awards?start_date=2024-01-15&page_size=50&cursor=eyJsYXN0X21vZGlmaWVkX2RhdGUiOiIyMDI0LTAxLTE2IiwiaWQiOjEyMzQ1fQ==" \ -H "X-API-KEY: your_api_key" ``` # List Saved Searches Source: https://docs.govly.com/api-reference/enterprise/awards/saved_searches/list GET /api/enterprise/awards/saved_searches Returns a paginated list of saved award searches for your organization ## Request Page number for pagination Number of results per page ## Response Array of saved search objects Unique identifier for the saved search Name of the saved search Whether the saved search is currently active Email of the user who created the saved search ISO 8601 timestamp when the saved search was created ISO 8601 timestamp when the saved search was last updated Search criteria configuration containing the filters and parameters used for this saved search Pagination metadata Current page number Number of results per page Total number of saved searches Total number of pages available ## Example Request ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards/saved_searches?page=1&per=25" \ -H "X-API-KEY: your_api_key" ``` # Execute a search on a saved search Source: https://docs.govly.com/api-reference/enterprise/awards/saved_searches/search GET /api/enterprise/awards/saved_searches/{id}/search Search awards using a saved search query ## Request ID of the saved search to execute Number of results per page (max: 100) Page number for pagination Which field to use for sorting. Must be one of: `relevance`, `period_of_performance_start_date`, `last_modified_date`, or `awarded_date`. Default: `relevance` Sort direction for results (`asc` or `desc`) Start date for filtering results (ISO 8601 format). Default: uses saved search relative date range or 1 day ago End date for filtering results (ISO 8601 format). Default: uses saved search relative date range or current date Which date field to use for date range filtering. Must be one of: `period_of_performance_start_date`, `last_modified_date`, or `awarded_date`. Default: `period_of_performance_start_date` ## Response Array of award objects matching the search criteria Unique identifier for the award Unique identifier key for the award (e.g., FPDS PIID) External identifier for the award Title of the award Description of the award AI-generated summary of the award Award category (e.g., "contract", "grant") Govly web URL for viewing the award URL to the original government source ISO 8601 date when the award was made ISO 8601 date when the award was last modified ISO 8601 timestamp when the record was created in Govly ISO 8601 timestamp when the record was last updated in Govly ISO 8601 date of the related solicitation ISO 8601 date when the period of performance begins ISO 8601 date when the period of performance ends ISO 8601 date of the potential end date including options Total award amount in USD Maximum potential value of the award in USD Amount obligated in USD Amount paid in USD Payment structure type (e.g., "Fixed Price", "Cost Reimbursement") Type of acquisition Category of acquisition Extent of competition (e.g., "Full and Open Competition", "Not Competed") NAICS code for the award Product Service Code (PSC) Number of bids received for the award Set-aside information for the award Set-aside code Set-aside name (e.g., "Small Business Set-Aside") Unique key of the parent award (for modifications) External identifier of the parent award External ID of the related solicitation Unique key of the award recipient (UEI) Unique key of the recipient's parent organization CAGE code of the recipient Information about the award recipient Unique identifier for the recipient (UEI) Recipient organization name CAGE code Recipient address Street address line 1 Street address line 2 Street address line 3 City State or region Postal code Country AI-enriched headquarters address AI-enriched website URL Information about the buying organization Organization ID Organization name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Information about the buying office Office ID Office name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Information about the funding organization Organization ID Organization name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Information about the funding office Office ID Office name Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy AI-enriched organization website AI-enriched headquarters address Place of manufacture designation Location where the work is performed City State or region Postal code Country County Congressional district code Object containing highlighted text snippets from fields that matched the saved search criteria Array of text snippets from the field containing highlighted matches. The field name will be the name of the field that contained matches (e.g., `title`, `description`, etc.) Pagination metadata Current page number Number of items per page Total number of items Total number of pages ## Example Requests ### Basic search execution ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards/saved_searches/abc123/search" \ -H "X-API-KEY: your_api_key" ``` ### With date range override ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards/saved_searches/abc123/search?start_date=2024-01-01&end_date=2024-01-31" \ -H "X-API-KEY: your_api_key" ``` ### With sorting and pagination ```bash theme={null} curl "https://app.govly.com/api/enterprise/awards/saved_searches/abc123/search?sort=awarded_date&sort_direction=desc&per=25&page=2" \ -H "X-API-KEY: your_api_key" ``` # Errors Source: https://docs.govly.com/api-reference/enterprise/errors Understanding Enterprise API error responses # Error Handling The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key. ## Common Error Codes | Status Code | Description | | - | - | | 401 | Authentication error - Invalid or missing API key | | 429 | Rate limit exceeded | | 503 | Service temporarily unavailable | ## HTTPS Only The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources. # List opportunities by ID Source: https://docs.govly.com/api-reference/enterprise/opportunities/list GET /api/enterprise/opportunities Retrieve detailed information about specific opportunities by their IDs ## Request Array of opportunity IDs to retrieve ## Response Returns an array of opportunity objects with detailed information about each opportunity. Unique identifier for the opportunity Original title from the solicitation Unique identifier key for the opportunity External reference number (e.g., solicitation number) Govly web URL for viewing the opportunity Direct API URL for retrieving this opportunity URL to the original government source ISO 8601 timestamp of when the opportunity was posted ISO 8601 timestamp of the last modification ISO 8601 timestamp of the response deadline ISO 8601 timestamp of the deadline for submitting questions about the opportunity. Returns null when not available from the source data. ISO 8601 timestamp of when the opportunity was last processed by AI Type of record (e.g., "solicitation", "forecast", "award") Jurisdiction name (e.g., "United States", "California") Jurisdiction ISO code (e.g., "US", "US-CA") Contract vehicle being used for the opportunity NAICS (North American Industry Classification System) codes for the opportunity. Only the most specific codes are returned (e.g., 6-digit codes are preferred over sector-level codes). Empty array if none. AI-generated descriptive title AI-generated summary of the opportunity AI-generated short summary (3-6 sentences) that is concise and to the point while preserving key details like OEMs, products, quantities, and part numbers Minimum estimated value of the opportunity in USD Maximum estimated value of the opportunity in USD Description of the performance period for the opportunity Structured breakdown of products and services mentioned in the opportunity Array of product line items Name of the product vendor Product name Quantity requested Product description Product part number Array of service line items Name of the service provider Service name Quantity of services Service description Service part number Array of primary product names mentioned in the opportunity Array of primary vendor information Vendor name Vendor website URL Array of competing product names identified in the opportunity Array of competing vendor information Vendor name Vendor website URL Full opportunity description from the latest source Reason for the most recent modification Product category tags associated with the opportunity Major end item from the data source context Warning labels for the opportunity. Possible values: `"Brand Name or Equal"`, `"Clearance Likely Required"`, `"Clearance Possibly Required"`. Empty array if none. Primary contact name Primary contact email address Primary contact phone number Primary location address Information about the buying organization Buyer organization ID Name of the buying organization Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy Array of documents attached to the opportunity SHA-256 checksum of the file Original filename Secure URL when the attachment is available for download Array of source records for this opportunity Unique identifier for the source Type of notice (e.g., "presolicitation", "solicitation", "award") Type of record Unique digest for the source content URL to the original source ISO 8601 timestamp when the source was created in Govly ISO 8601 timestamp when the source was posted ISO 8601 timestamp if a no-bid decision was recorded Whether the source includes a justification document Whether the source is associated with an event Reason for the modification if this is an amendment Array of checksums for attachments associated with this source URL to the raw email if this source came from email (only visible to source owner) Provider-specific context data (only visible to source owner) Additional context from the data source Checksum of the email message if applicable Original notice type from the source Set-aside information from the source ## Example Request ```bash theme={null} curl "https://api.govly.com/api/enterprise/opportunities?ids[]=13887036" ``` # List saved search matches Source: https://docs.govly.com/api-reference/enterprise/opportunities/saved_search_matches/list GET /api/enterprise/opportunities/saved_search_matches Retrieve opportunities that match your saved searches Retrieve opportunities that match your saved searches. Results are paginated and can be filtered by date range, follower email, and saved search IDs. ## Query Parameters ISO 8601 timestamp to start searching from. Only returns matches created after this date. ISO 8601 timestamp to search until. Only returns matches created before this date. Filter results to specific saved searches. Multiple IDs can be provided to get matches from multiple saved searches. Filter matches to only show opportunities from saved searches followed by this email address. Cursor for pagination. Use the `next_cursor` value from the meta object in the response to get the next page. Number of results per page (max 100) ## Response Array of opportunities with their saved search matches Unique identifier for the opportunity Original title from the solicitation Unique identifier key for the opportunity External reference number (e.g., solicitation number) Govly web URL for viewing the opportunity Direct API URL for retrieving this opportunity URL to the original government source ISO 8601 timestamp of when the opportunity was posted ISO 8601 timestamp of the last modification ISO 8601 timestamp of the response deadline ISO 8601 timestamp of the deadline for submitting questions about the opportunity. Returns null when not available from the source data. ISO 8601 timestamp of when the opportunity was last processed by AI Type of record (e.g., "solicitation", "forecast", "award") Jurisdiction name (e.g., "United States", "California") Jurisdiction ISO code (e.g., "US", "US-CA") Contract vehicle being used for the opportunity NAICS (North American Industry Classification System) codes for the opportunity. Only the most specific codes are returned (e.g., 6-digit codes are preferred over sector-level codes). Empty array if none. AI-generated descriptive title AI-generated summary of the opportunity AI-generated short summary (3-6 sentences) that is concise and to the point while preserving key details like OEMs, products, quantities, and part numbers Minimum estimated value of the opportunity in USD Maximum estimated value of the opportunity in USD Description of the performance period for the opportunity Structured breakdown of products and services mentioned in the opportunity Array of product line items Name of the product vendor Product name Quantity requested Product description Product part number Array of service line items Name of the service provider Service name Quantity of services Service description Service part number Array of primary product names mentioned in the opportunity Array of primary vendor information Vendor name Vendor website URL Array of competing product names identified in the opportunity Array of competing vendor information Vendor name Vendor website URL Full opportunity description from the latest source Reason for the most recent modification Product category tags associated with the opportunity Major end item from the data source context Warning labels for the opportunity. Possible values: `"Brand Name or Equal"`, `"Clearance Likely Required"`, `"Clearance Possibly Required"`. Empty array if none. Primary contact name Primary contact email address Primary contact phone number Primary location address Information about the buying organization Buyer organization ID Name of the buying organization Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy Array of documents attached to the opportunity SHA-256 checksum of the file Original filename Secure URL when the attachment is available for download Array of source records for this opportunity Unique identifier for the source Type of notice (e.g., "presolicitation", "solicitation", "award") Type of record Unique digest for the source content URL to the original source ISO 8601 timestamp when the source was created in Govly ISO 8601 timestamp when the source was posted ISO 8601 timestamp if a no-bid decision was recorded Whether the source includes a justification document Whether the source is associated with an event Reason for the modification if this is an amendment Array of checksums for attachments associated with this source URL to the raw email if this source came from email (only visible to source owner) Provider-specific context data (only visible to source owner) Additional context from the data source Checksum of the email message if applicable Original notice type from the source Set-aside information from the source Array of matches between this opportunity and saved searches Unique identifier for the match List of email addresses for users following this saved search Name of the saved search that generated this match ID of the saved search that generated this match Highlighted text from the opportunity that matched the saved search criteria ISO 8601 timestamp when the match was created Pagination metadata Cursor to get the next page of results. Will be null if there are no more results. NOTE: We use cursor pagination instead of page numbers for this endpoint to specifically support large datasets and guarantee consistent pagination over time since matches are immutable. # List Saved Searches Source: https://docs.govly.com/api-reference/enterprise/opportunities/saved_searches/list GET /api/enterprise/opportunities/saved_searches Returns a paginated list of saved opportunity searches for your organization ## Request Page number for pagination Number of results per page ## Response Array of saved search objects Unique identifier for the saved search Whether the saved search is currently active ISO 8601 timestamp when the saved search was created Email of the user who created the saved search ISO 8601 timestamp when the saved search last found a matching opportunity Number of opportunities matching the saved search Name of the saved search Search criteria configuration Field to sort results by List of contract vehicle feeds to search Search query string List of opportunity statuses to include List of buyer IDs to filter by Types of records to include Direction to sort results (`asc` or `desc`) List of opportunity IDs to exclude Field to use for date filtering Whether to match buyers by ID Whether to include sub-organizations of matched buyers Whether to include AI-predicted opportunities Type of search to perform Configuration for field-specific search options ISO 8601 timestamp when the saved search was last updated Pagination metadata Current page number Number of results per page Total number of saved searches Total number of pages available # Execute a search on a saved search Source: https://docs.govly.com/api-reference/enterprise/opportunities/saved_searches/search GET /api/enterprise/opportunities/saved_searches/{id}/search Search opportunities using a saved search query ## Request ID of the saved search to execute Number of results per page (max: 100) Page number for pagination Which date field to use for sorting. Must be one of: 'relevance', 'posted\_at', 'modified\_at' or 'respond\_by'. Default: falls back to saved search date range parameter Sort direction for results ('asc' or 'desc', default: falls back to saved search sort direction) Start date for filtering results (ISO 8601 format, default: 1 day ago) End date for filtering results (ISO 8601 format, default: current date) Which date field to use for date range filtering. Must be one of: 'posted\_at', 'modified\_at', or 'respond\_by'. Default: falls back to saved search date range parameter ## Response Array of opportunity objects matching the search criteria Unique identifier for the opportunity Original title from the solicitation Unique identifier key for the opportunity External reference number (e.g., solicitation number) Govly web URL for viewing the opportunity Direct API URL for retrieving this opportunity URL to the original government source ISO 8601 timestamp of when the opportunity was posted ISO 8601 timestamp of the last modification ISO 8601 timestamp of the response deadline ISO 8601 timestamp of the deadline for submitting questions about the opportunity. Returns null when not available from the source data. ISO 8601 timestamp of when the opportunity was last processed by AI Type of record (e.g., "solicitation", "forecast", "award") Jurisdiction name (e.g., "United States", "California") Jurisdiction ISO code (e.g., "US", "US-CA") Contract vehicle being used for the opportunity NAICS (North American Industry Classification System) codes for the opportunity. Only the most specific codes are returned (e.g., 6-digit codes are preferred over sector-level codes). Empty array if none. AI-generated descriptive title AI-generated summary of the opportunity AI-generated short summary (3-6 sentences) that is concise and to the point while preserving key details like OEMs, products, quantities, and part numbers Minimum estimated value of the opportunity in USD Maximum estimated value of the opportunity in USD Description of the performance period for the opportunity Structured breakdown of products and services mentioned in the opportunity Array of product line items Name of the product vendor Product name Quantity requested Product description Product part number Array of service line items Name of the service provider Service name Quantity of services Service description Service part number Array of primary product names mentioned in the opportunity Array of primary vendor information Vendor name Vendor website URL Array of competing product names identified in the opportunity Array of competing vendor information Vendor name Vendor website URL Full opportunity description from the latest source Reason for the most recent modification Product category tags associated with the opportunity Major end item from the data source context Warning labels for the opportunity. Possible values: `"Brand Name or Equal"`, `"Clearance Likely Required"`, `"Clearance Possibly Required"`. Empty array if none. Primary contact name Primary contact email address Primary contact phone number Primary location address Information about the buying organization Buyer organization ID Name of the buying organization Array of organization names from highest to lowest level Array of organization IDs corresponding to the hierarchy Array of documents attached to the opportunity SHA-256 checksum of the file Original filename Secure URL when the attachment is available for download Array of source records for this opportunity Unique identifier for the source Type of notice (e.g., "presolicitation", "solicitation", "award") Type of record Unique digest for the source content URL to the original source ISO 8601 timestamp when the source was created in Govly ISO 8601 timestamp when the source was posted ISO 8601 timestamp if a no-bid decision was recorded Whether the source includes a justification document Whether the source is associated with an event Reason for the modification if this is an amendment Array of checksums for attachments associated with this source URL to the raw email if this source came from email (only visible to source owner) Provider-specific context data (only visible to source owner) Additional context from the data source Checksum of the email message if applicable Original notice type from the source Set-aside information from the source Object containing highlighted text snippets from fields that matched the saved search criteria Array of text snippets from the field containing highlighted matches. The field name will be the name of the field that contained matches (e.g., 'title', 'description', etc.) Pagination metadata Current page number Number of items per page Total number of items Total number of pages # Rate Limits Source: https://docs.govly.com/api-reference/enterprise/rate-limits Understanding API rate limits and usage restrictions # Rate and Usage Limits API access rate limits apply at a per-API key basis in unit time. The limit is 300 requests per minute. Also, depending on your plan, you may have usage limits. If you exceed either limit, your request will return an HTTP 429 Too Many Requests status code. ## Rate Limit Headers Each API response returns the following set of headers to help you identify your use status: | Header | Description | | - | - | | `X-RateLimit-Limit` | The maximum number of requests that the consumer is permitted to make per minute. | | `X-RateLimit-Remaining` | The number of requests remaining in the current rate limit window. | | `X-RateLimit-Reset` | The time at which the current rate limit window resets in UTC epoch seconds. | ## Tools API and MCP The Tools API (`/api/tools/v1`) applies a second limit of 70 requests per minute per user for each resource, so awards, opportunities, workspaces, and the other resource families each have their own counter. Exceeding it returns HTTP 429 with the standard Tools API error envelope, `code: rate_limited`, and a `Retry-After` header. Which additional limit applies depends on how you send your key: | Key sent as | Additional limit | Headers on responses | | - | - | - | | `X-API-KEY` header | The 300 requests per minute per key limit above | `X-RateLimit-*` on every response, including a Tools API 429. They describe the per-key limit, not the per-user one. | | `Authorization: Bearer` header | None from the per-key limit | `Retry-After` on a Tools API 429 only | Requests sent without `X-API-KEY` also count toward a limit of 200 requests per minute per IP address, shared by every caller behind that address, which returns HTTP 503. MCP connections (`/api/mcp`) are limited to 70 requests per minute per user when authenticated with a personal or agent API key, and 60 requests per minute per connection when authorized through OAuth. Either limit returns HTTP 429 with a `Retry-After` header. ## Service Availability Outside the per-IP limit above, an HTTP 503 response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes. If the outage persists or you receive any other form of an HTTP 5XX error, contact [support@govly.com](mailto:support@govly.com). # Webhooks Overview Source: https://docs.govly.com/api-reference/enterprise/webhooks/overview Learn about Govly Enterprise webhooks # Webhooks Overview Webhooks are a way for Govly to notify your applications of events that happen in your Govly account. The webhooks are sent as HTTP POST requests to a URL that you specify. You can configure webhooks from Govly's API integration dashboard. ## Payload Format Webhooks from Govly will include a JSON payload that is dependent on the event type. However, all payloads will have the following shape by default: ```json theme={null} { "event": "EVENT_TYPE.ACTION", "payload": { // Event-specific data } } ``` ## Custom Payload Templates You can create custom templates for your webhook payloads. This allows you to customize the data so that it better fits your destination. Here is an example of a custom template for a webhook based Slack integration: ```json theme={null} { "event": "OPP_WORKSPACE.INTEND_TO_BID", "text": "[SEWP RFQ 123](https://govly.com/opportunities/123) has been marked as Intend to Bid." } ``` ## Headers By default, webhooks from Govly will be sent with the following headers: | Header | Description | | - | - | | `Govly-Webhook-Signature` | SHA2 hex digest of your Webhook Signature Key and the JSON payload | | `User-Agent` | `govly-webhooks/1.0` | | `Content-Type` | `application/json` | ## Retries and Stop Mechanisms Each webhook event will be retried 10 times with an exponential backoff. After a given webhook has 100 failed consecutive deliveries, it will be automatically disabled to prevent your server from being overwhelmed. You can view the payload and response status for webhook events in the Govly UI. You can also resend a webhook event directly from the UI. # Search awards Source: https://docs.govly.com/api-reference/tools-v1/awards/search-awards /openapi/tools-v1.yaml post /api/tools/v1/awards/search Search awarded government contracts with the constrained public parameter set shared by MCP search_awards. Searches all time unless dateRange is given. searchType defaults to the authenticated user's market focus (fed or sled); sled and international require the matching organization subscription. # Show an award Source: https://docs.govly.com/api-reference/tools-v1/awards/show-an-award /openapi/tools-v1.yaml get /api/tools/v1/awards/{id} Show a single awarded contract with transactions, sub-awards, related opportunities, program links, line items, places, classification codes, and contacts. The path parameter accepts either identifier shape: an all-digit value is treated as the Govly award database id; anything else is treated as the award uniqueKey (such as CONT_AWD_... or CONT_IDV_...). # Search contacts Source: https://docs.govly.com/api-reference/tools-v1/contacts/search-contacts /openapi/tools-v1.yaml post /api/tools/v1/contacts/search Search government points of contact with the constrained public parameter set shared by MCP search_contacts. Email and phone are never returned in search results; use show_contact for a single contact. jurisdictionLevel defaults to federal. # Show a contact Source: https://docs.govly.com/api-reference/tools-v1/contacts/show-a-contact /openapi/tools-v1.yaml get /api/tools/v1/contacts/{id} Show a single government point of contact by Govly contact id, with titles and associated buyers, vendors, and contract vehicles. Email and phone are included for paid callers. # Get a temporary original-file download Source: https://docs.govly.com/api-reference/tools-v1/documents/get-a-temporary-original-file-download /openapi/tools-v1.yaml get /api/tools/v1/documents/download Returns a fresh presigned URL for the authorized original file. The URL expires at data.expiresAt. This operation is separate from document_read so reading representations never downloads the full file implicitly. # Read bounded document content Source: https://docs.govly.com/api-reference/tools-v1/documents/read-bounded-document-content /openapi/tools-v1.yaml get /api/tools/v1/documents/read Reads a bounded portion of an authorized document without creating an analysis or enqueueing extraction work. Start a read with documentType and id. Continue when meta.hasMore is true by sending only meta.nextCursor and, optionally, maxChars. Cursors are opaque, source-bound, and re-authorized on every request. Opportunity document IDs are OppAttachment.id values returned as opportunity attachment id; access is derived from any associated opportunity/source path visible to the caller rather than from a client-supplied opportunity ID. Use positioned_text only when data.availableRepresentations advertises it. PDF page ranges are supported with pageStart and pageEnd. Processing and representation_unavailable are successful structured states. Failed or unavailable extraction returns the standard 422 error envelope, inaccessible records return the standard 404 error envelope, and invalid parameters return the standard 422 error envelope. # Follow a Govly entity Source: https://docs.govly.com/api-reference/tools-v1/follows/follow-a-govly-entity /openapi/tools-v1.yaml post /api/tools/v1/follows Follow, track, or subscribe to changes for a Govly entity. For opportunities, awards, or contacts, this creates or reuses the entity's default workspace and follows that workspace for the authenticated user. # Unfollow a Govly entity Source: https://docs.govly.com/api-reference/tools-v1/follows/unfollow-a-govly-entity /openapi/tools-v1.yaml delete /api/tools/v1/follows Stops following an opportunity, award, or contact for the authenticated user. Whether anything is cleared is decided entirely by the caller's follow on the entity's default workspace. When that follow is in the following state, it is cleared along with the caller's follows on every other workspace for the same entity, not only the default one returned in the response, and a subsequent follow restores the default workspace alone. When there is no default workspace for the entity, or the caller's follow on it is in any other state, nothing is cleared anywhere and meta.noOp is true — including when the caller holds an active follow on a non-default workspace, which this operation cannot clear. Idempotent: the call succeeds without writing anything and reports meta.noOp true with a null workspace and membership whenever there is no follow to clear. Only follows in the following state are cleared — a follow in any other state (considered, assigned, invited, disinterested, or already unfollowed) is left unchanged and also reports meta.noOp true, so meta.noOp true does not by itself mean the user has no workspace membership for the entity. A 404 means the target is not currently visible to the caller and does not imply that no follow exists; a follow on a target that has left the caller's visibility cannot be cleared through this operation. This applies to contacts, which are resolvable only while active, and to opportunities, whose visibility depends on the caller's access; awards are resolved without a visibility filter, so a 404 for an award means it does not exist. Unfollowing emits no event, activity, or webhook. The notifications parameter is not accepted here and is ignored if sent. # Accept an inbox item Source: https://docs.govly.com/api-reference/tools-v1/inbox/accept-an-inbox-item /openapi/tools-v1.yaml post /api/tools/v1/inbox_items/{id}/accept Follow an underlying opportunity or award and create or reuse its default workspace. Signal acceptance is unsupported and returns 422. Opportunity and award accepts are final and cannot be reversed with restore. The response meta reports the resulting workspaceId and finality. # Decline (reject) an inbox item as a bad fit Source: https://docs.govly.com/api-reference/tools-v1/inbox/decline-reject-an-inbox-item-as-a-bad-fit /openapi/tools-v1.yaml post /api/tools/v1/inbox_items/{id}/decline Mark the item a bad fit, optionally with a reason that feeds the organization's matching-exclusions memory. Reversible with restore. # Dismiss an inbox item Source: https://docs.govly.com/api-reference/tools-v1/inbox/dismiss-an-inbox-item /openapi/tools-v1.yaml post /api/tools/v1/inbox_items/{id}/dismiss Dismiss the item with an optional written explanation retained for future analysis. Written feedback does not currently change matching and is not returned in API responses. Restoring the item withdraws its written feedback. # List inbox items Source: https://docs.govly.com/api-reference/tools-v1/inbox/list-inbox-items /openapi/tools-v1.yaml get /api/tools/v1/inbox_items List the authenticated user's active inbox items (Govly AI matches and saved-search matches), newest first. Continue while meta.nextCursor is non-null. A page may contain fewer than perPage records, or no records, while a continuation cursor is present; do not infer completion from page size. # List saved Inbox views Source: https://docs.govly.com/api-reference/tools-v1/inbox/list-saved-inbox-views /openapi/tools-v1.yaml get /api/tools/v1/inbox_views List the authenticated user's saved Inbox views and default selection. Views belong to the current organization membership. Unavailable views remain listed with available false and cannot be used for search. Pass an available view's id, or the built-in team_view, as inboxViewId to search_inbox_items. This endpoint does not modify views or defaults. # Restore a dismissed or declined inbox item Source: https://docs.govly.com/api-reference/tools-v1/inbox/restore-a-dismissed-or-declined-inbox-item /openapi/tools-v1.yaml post /api/tools/v1/inbox_items/{id}/restore Return a dismissed or bad-fit item to the active inbox. Only dismissed or bad-fit items can be restored — an accepted item cannot. # Search inbox items Source: https://docs.govly.com/api-reference/tools-v1/inbox/search-inbox-items /openapi/tools-v1.yaml post /api/tools/v1/inbox_items/search Full-text search and filter the authenticated user's inbox items. Returns matchable-type aggregation counts. Use inboxStatus all for pending Inbox items, followed for followed Opportunities, or archived for dismissed items. Without an inboxStatus or state filter, active items include actioned items. Discover saved views through list_inbox_views, then pass inboxViewId. A view applies its saved filters, ordering and relative time window; only cursor and perPage may accompany inboxViewId. The user's default view is not applied implicitly. Continue with the returned cursor to retain the same relative time window across pages. A missing view or one owned by another user returns 404. # Show an inbox item Source: https://docs.govly.com/api-reference/tools-v1/inbox/show-an-inbox-item /openapi/tools-v1.yaml get /api/tools/v1/inbox_items/{id} # Fetch opportunities by ID Source: https://docs.govly.com/api-reference/tools-v1/opportunities/fetch-opportunities-by-id /openapi/tools-v1.yaml get /api/tools/v1/opportunities # Mark an opportunity not interested Source: https://docs.govly.com/api-reference/tools-v1/opportunities/mark-an-opportunity-not-interested /openapi/tools-v1.yaml post /api/tools/v1/opportunities/{opportunityId}/not_interested Marks the opportunity not interested / dismissed for the authenticated user. Sets a team-visible disinterested status on the user's workspace follow, unfollows the user, and dismisses the user's matching inbox items. # Search opportunities Source: https://docs.govly.com/api-reference/tools-v1/opportunities/search-opportunities /openapi/tools-v1.yaml post /api/tools/v1/opportunities/search Search opportunities with the constrained public parameter set shared by MCP search_opportunities. Defaults to open opportunities and excludes prediction records from search results. Searches all dates unless a date bound is supplied, orders by newest modified date unless sort is supplied, and returns stored opportunity dates. Repeat the same filters with each cursor. Unresolved buyers or unsupported type filters fail with 400 rather than returning a broader search. # Show an opportunity Source: https://docs.govly.com/api-reference/tools-v1/opportunities/show-an-opportunity /openapi/tools-v1.yaml get /api/tools/v1/opportunities/{id} # Undo a not-interested mark Source: https://docs.govly.com/api-reference/tools-v1/opportunities/undo-a-not-interested-mark /openapi/tools-v1.yaml delete /api/tools/v1/opportunities/{opportunityId}/not_interested Removes a previous not-interested mark for the authenticated user and restores matching dismissed inbox items. The user returns to a neutral (not following) state. # Enumerate every Place of a category within a jurisdiction Source: https://docs.govly.com/api-reference/tools-v1/places/enumerate-every-place-of-a-category-within-a-jurisdiction /openapi/tools-v1.yaml post /api/tools/v1/places/list Enumerate every canonical Govly Place of a category within a jurisdiction — every county in California, every school district in Texas. At least one of categories or isoCodes is required. Without sort, ordering is stable but arbitrary, not alphabetical — page until meta.nextCursor is null for the whole set, and sort client-side when presenting a list. With sort population and sortDirection desc (largest first, default) or asc (smallest first), the N most or least populous places are the first N: request perPage N (following nextCursor only if meta.perPage is smaller than N). Places without a population sort last either way; population exists only for states, counties, and municipalities, and a population sort on any other category returns 400. Use /api/tools/v1/places/search instead to look up a place by name. # Resolve place names to canonical Place ids Source: https://docs.govly.com/api-reference/tools-v1/places/resolve-place-names-to-canonical-place-ids /openapi/tools-v1.yaml post /api/tools/v1/places/search Resolve a place name to canonical Govly Place ids — counties, municipalities, states, ZIP codes, school districts, military installations, and countries. Results are relevance-ranked with records-bearing places first. Paging walks the matches for a query, not a category — use /api/tools/v1/places/list to enumerate a jurisdiction. Place ids are market-agnostic, but opportunity and award searches are market-scoped, so a returned id may not be searchable under the caller's subscription. # List accessible product catalogs Source: https://docs.govly.com/api-reference/tools-v1/product-catalogs/list-accessible-product-catalogs /openapi/tools-v1.yaml get /api/tools/v1/product_catalogs List the government contract price lists (product catalogs) available to the caller — public catalogs plus any owned by the caller's organization. Returns catalog metadata only, no pricing. Not paginated; the catalog set is small. Use the returned ids and groups to filter search_product_catalog. # Search product catalog items Source: https://docs.govly.com/api-reference/tools-v1/product-catalogs/search-product-catalog-items /openapi/tools-v1.yaml post /api/tools/v1/product_catalogs/search Search line items across government contract price lists for negotiated pricing, part numbers, and availability, with the constrained public parameter set shared by MCP search_product_catalog. query is a fuzzy search over item descriptions, manufacturers, and part numbers; productCatalogIds, group, category, manufacturer, and priceRange are exact filters AND-combined with query. productCatalogIds is always intersected with the catalogs the caller may access, so inaccessible ids drop out rather than erroring. Results are relevance-ordered; there is no sort control. # Check quote submission requirements Source: https://docs.govly.com/api-reference/tools-v1/quote-submissions/check-quote-submission-requirements /openapi/tools-v1.yaml get /api/tools/v1/quote/submissions/requirements Returns destination-specific quote submission requirements and blocking reasons for the authenticated actor and workspace. # List quote submissions for a workspace Source: https://docs.govly.com/api-reference/tools-v1/quote-submissions/list-quote-submissions-for-a-workspace /openapi/tools-v1.yaml get /api/tools/v1/quote/submissions # Show quote submission status Source: https://docs.govly.com/api-reference/tools-v1/quote-submissions/show-quote-submission-status /openapi/tools-v1.yaml get /api/tools/v1/quote/submissions/{id} Poll this endpoint after create_quote_submission until meta.terminal is true. Completed submissions include confirmation details when the portal returns them; failed submissions include failureReason when available. # Submit a quote Source: https://docs.govly.com/api-reference/tools-v1/quote-submissions/submit-a-quote /openapi/tools-v1.yaml post /api/tools/v1/quote/submissions Submit a quote to the destination for an opportunity workspace. Upload each file to the workspace attachments endpoint first, then describe the destination-specific package in files. Call get_quote_submission_requirements for the supported roles, fields, and modes. The response returns a submission ID that can be polled with show_quote_submission. # Create an award saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/create-an-award-saved-search /openapi/tools-v1.yaml post /api/tools/v1/awards/saved_searches Saves a set of award search criteria as a replayable search. Award saved searches do not send notifications — run one any time with the results endpoint. The date window is stored as relative day offsets and defaults to the last year. The market the search is created under is stored and bounds every replay, so set searchType explicitly when scoping to a state or local place. Stored filters can be changed but not removed. # Create an opportunity saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/create-an-opportunity-saved-search /openapi/tools-v1.yaml post /api/tools/v1/opportunities/saved_searches Saves a set of opportunity search criteria. Opportunity saved searches percolate, so the stored filters also drive match notifications. The market the search is created under is stored with it and bounds every later match, so set searchType explicitly when scoping to a state or local place. Stored filters can be changed but not removed. # Execute an award saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/execute-an-award-saved-search /openapi/tools-v1.yaml get /api/tools/v1/awards/saved_searches/{savedSearchId}/results Runs the saved search live against the award index rather than reading a cached match list, so results reflect the index at call time. The saved search's own relative date window is applied; meta.dateRange reports the absolute window actually searched. # List award saved searches Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/list-award-saved-searches /openapi/tools-v1.yaml get /api/tools/v1/awards/saved_searches # List cached opportunity results for a saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/list-cached-opportunity-results-for-a-saved-search /openapi/tools-v1.yaml get /api/tools/v1/opportunities/saved_searches/{savedSearchId}/results Returns cached saved-search matches, excluding prediction records. # List opportunity saved searches Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/list-opportunity-saved-searches /openapi/tools-v1.yaml get /api/tools/v1/opportunities/saved_searches Latest match previews exclude prediction records. # Show an award saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/show-an-award-saved-search /openapi/tools-v1.yaml get /api/tools/v1/awards/saved_searches/{id} # Show an opportunity saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/show-an-opportunity-saved-search /openapi/tools-v1.yaml get /api/tools/v1/opportunities/saved_searches/{id} # Update an award saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/update-an-award-saved-search /openapi/tools-v1.yaml patch /api/tools/v1/awards/saved_searches/{id} Merges the supplied criteria into the stored ones. Only supplied keys change; omitted keys are left as they are, and there is no way to remove a stored filter — recreate the saved search to clear one. Award saved searches do not send notifications. # Update an opportunity saved search Source: https://docs.govly.com/api-reference/tools-v1/saved-searches/update-an-opportunity-saved-search /openapi/tools-v1.yaml patch /api/tools/v1/opportunities/saved_searches/{id} Merges the supplied criteria into the stored ones. Only supplied keys change; omitted keys are left as they are, and there is no way to remove a stored filter — recreate the saved search to clear one. # Share an opportunity, award, or contact by email Source: https://docs.govly.com/api-reference/tools-v1/shares/share-an-opportunity-award-or-contact-by-email /openapi/tools-v1.yaml post /api/tools/v1/shares Send an opportunity, award, or contact to one or more recipients by email. Delivery is queued immediately and is at-least-once, so a transient failure may redeliver to recipients who already received the message. Recipients can be any email address, including people outside your organization who do not have a Govly account. An address with no Govly account may also receive a separate invitation to join Govly, so a single request can send more than the share itself. The identifier form depends on the type. Opportunities take the numeric Govly ID. Awards may be addressed by numeric ID or by uniqueKey; the uniqueKey returned from award search is accepted directly. Sharing an opportunity sends one email per recipient rather than one email addressed to everyone. Award and contact shares send a single email when no teams are named; naming any team in email_recipient_groups gives their remaining recipients one email each as well. A share may send at most 20 emails per request: each team is one email, and each recipient outside a named team is one more. An ungrouped award or contact share is a single send and is not limited by that count. A second limit applies to addresses rather than emails: a request may name at most 20 recipients outside a named team, which is what bounds an ungrouped award or contact share. A third limit spans requests: across every share surface, a user may send at most 300 messages per day to addresses outside their organization, counting the join-Govly invitations those shares trigger. A request that would cross that limit is refused with a 422 and sends nothing. # Search signals Source: https://docs.govly.com/api-reference/tools-v1/signals/search-signals /openapi/tools-v1.yaml post /api/tools/v1/signals/search Search clustered procurement and market signals (news, hearings, laws, events, analysis, policy, regulatory actions, and public meetings) with the constrained public parameter set shared by MCP search_signals. query is a fuzzy, semantic search; contentTypes, categories, and dateRange are exact filters AND-combined with query. categories is a hard filter on curated slugs and only matches tagged clusters. meta.aggregations returns facet counts on the first page only. # Show a signal cluster Source: https://docs.govly.com/api-reference/tools-v1/signals/show-a-signal-cluster /openapi/tools-v1.yaml get /api/tools/v1/signals/{id} # List workspace attachments Source: https://docs.govly.com/api-reference/tools-v1/workspace-attachments/list-workspace-attachments /openapi/tools-v1.yaml get /api/tools/v1/workspaces/{workspaceId}/attachments # Upload workspace attachments Source: https://docs.govly.com/api-reference/tools-v1/workspace-attachments/upload-workspace-attachments /openapi/tools-v1.yaml post /api/tools/v1/workspaces/{workspaceId}/attachments # Post a Markdown comment to a workspace Source: https://docs.govly.com/api-reference/tools-v1/workspace-comments/post-a-markdown-comment-to-a-workspace /openapi/tools-v1.yaml post /api/tools/v1/workspaces/{workspaceId}/comments # Add a user or team member to a workspace Source: https://docs.govly.com/api-reference/tools-v1/workspace-members/add-a-user-or-team-member-to-a-workspace /openapi/tools-v1.yaml post /api/tools/v1/workspaces/{workspaceId}/members Adds a member, reactivates a previously removed one, or updates an existing active member's notifications. Provide exactly one of userId or teamId; both are resolved within the calling user's own organization, so a member from another organization returns 404. state accepts only "following" — remove a member with DELETE on this path rather than by writing an inactive state. # Remove a user or team member from a workspace Source: https://docs.govly.com/api-reference/tools-v1/workspace-members/remove-a-user-or-team-member-from-a-workspace /openapi/tools-v1.yaml delete /api/tools/v1/workspaces/{workspaceId}/members Removes a member from the workspace. Idempotent: removing a member who is absent or already removed succeeds with data null and meta.noOp true rather than 404, and never reports whether an id exists. Users may always remove themselves, unless their only membership is through a team. Removing anyone else requires belonging to the workspace's own organization; a denial is 401. Unlike the add operation, removal reaches members from other organizations and members whose user account has been archived; neither can be added back by a caller from this workspace's organization, only by someone from that member's own organization. Removal ends the membership and mutes notifications, but on a private workspace it does not by itself revoke that person's access. Note also that updatedAt on the returned membership is not advanced by a removal, so it cannot be used to detect one; read state instead. # Create a workspace Source: https://docs.govly.com/api-reference/tools-v1/workspaces/create-a-workspace /openapi/tools-v1.yaml post /api/tools/v1/workspaces # List workspaces associated with an entity Source: https://docs.govly.com/api-reference/tools-v1/workspaces/list-workspaces-associated-with-an-entity /openapi/tools-v1.yaml get /api/tools/v1/workspaces # Search active workspaces Source: https://docs.govly.com/api-reference/tools-v1/workspaces/search-active-workspaces /openapi/tools-v1.yaml post /api/tools/v1/workspaces/search Searches the authenticated organization's Active Work with exact totals and opaque cursor pagination. The default scope is current, open workspaces with an opportunity primary focus or no primary focus. Explicit participants narrow organization participation and never grant access. A user participant ID of me selects the authenticated user without embedding their organization-user ID. A workspace without a primary focus is represented by includeWithoutPrimaryFocus; primaryFocusTypes never uses a standalone sentinel. # Show a workspace Source: https://docs.govly.com/api-reference/tools-v1/workspaces/show-a-workspace /openapi/tools-v1.yaml get /api/tools/v1/workspaces/{id} # Update a workspace Source: https://docs.govly.com/api-reference/tools-v1/workspaces/update-a-workspace /openapi/tools-v1.yaml patch /api/tools/v1/workspaces/{id} # List Contract Vehicles Source: https://docs.govly.com/api-reference/v3/contract-vehicles/list GET /api/v3/contract_vehicles This endpoint returns a list of all available contract vehicles. ## Response Array of contract vehicle objects Unique identifier for the contract vehicle Display name of the contract vehicle URL-friendly identifier List of available tags for this contract vehicle This endpoint is part of the legacy v3 API and will be deprecated in the future. Please migrate to the new enterprise API endpoints. # Filter Opportunities Source: https://docs.govly.com/api-reference/v3/opportunities/filter POST /api/v3/opportunities/filter This endpoint filters searchable opportunities. By default, it returns a maximum of 10,000 results in pages of 500. ## Request Body Can be one of: "posted\_at" (default), "modified\_at", or "respond\_by" An array of ISO 8601 formatted strings: \[startTime, endTime] List of contract vehicle IDs to filter by Page number for pagination (default: 1) Results per page Can be one of: "posted" (default), "modified", or "expires" Can be one of: "asc" or "desc" (default) This endpoint is part of the legacy v3 API and will be deprecated in the future. Please migrate to the new enterprise API endpoints. # Get Opportunity Source: https://docs.govly.com/api-reference/v3/opportunities/get GET /api/v3/opportunities/{id} Retrieve a specific opportunity by ID # Get Opportunity ## Path Parameters The ID of the opportunity to retrieve. This can be found in the opportunity URL. For example, given the URL `https://www.govly.com/app/opportunities/8180377`, the ID would be `8180377`. ## Response The unique identifier for the opportunity The display name of the opportunity The full description of the opportunity Name of the contract vehicle ID of the contract vehicle URL-friendly identifier for the contract vehicle Details about the customer organization Place of performance and related locations for the opportunity. Fields with no value are returned as `null`. Deprecated — always `null`. Coordinates are available via the Enterprise API. Deprecated — always `null`. Migrate to the Enterprise API endpoints. Array of attachment objects associated with the opportunity ## Example Request ```bash theme={null} curl --location 'https://app.govly.com/api/v3/opportunities/8180377' \ --header 'X-API-KEY: your-api-key' ``` ```bash Request theme={null} curl --location 'https://app.govly.com/api/v3/opportunities/8180377' \ --header 'X-API-KEY: your-api-key' ``` ```json Response theme={null} { "id": "8180377", "displayName": "SEWP V #94039043", "contractVehicle": { "contractName": "SEWP V", "id": "1", "slug": "sewp-v" }, "description": "The Office of Information & Technology (OIT)...", "customer": { "name": "Department of Veterans Affairs", "id": "3375" }, "locations": [ { "city": "Eatontown", "country": "United States", "countryCode": "US", "postalCode": "07724" } ] } ``` # Create Workspace Source: https://docs.govly.com/api-reference/v3/workspaces/create POST /api/v3/opportunity_workspaces This endpoint creates a new workspace for an opportunity. ## Request Body ID of the opportunity to create a workspace for Display name for the workspace This endpoint is part of the legacy v3 API and will be deprecated in the future. Please migrate to the new enterprise API endpoints. # Get Workspace Source: https://docs.govly.com/api-reference/v3/workspaces/get GET /api/v3/opportunity_workspaces/{id} Retrieve a specific opportunity workspace by ID # Get Workspace ## Path Parameters The ID of the workspace to retrieve. This can be found in the workspace URL. For example, given the URL `https://www.govly.com/app/opportunities/8180377/workspaces/822609`, the ID would be `822609`. ## Response The unique identifier for the workspace The display name of the workspace Current stage of the workspace (e.g., "Qualifying", "Quoted") Array of activity objects showing workspace history Array of comment objects associated with the workspace Array of follow objects showing who is following the workspace The full opportunity object associated with this workspace ## Example Request ```bash theme={null} curl --location 'https://app.govly.com/api/v3/opportunity_workspaces/822609' \ --header 'X-API-KEY: your-api-key' ``` ```bash Request theme={null} curl --location 'https://app.govly.com/api/v3/opportunity_workspaces/822609' \ --header 'X-API-KEY: your-api-key' ``` ```json Response theme={null} { "id": "822609", "displayName": "Govly Workspace", "stage": "Quoted", "activities": [ { "createdAt": "2023-05-31T18:50:40.563512Z", "id": "313488", "message": "nick@govly.com posted a new comment" } ], "comments": [ { "author": "nick@govly.com", "body": "This is a workspace comment.", "createdAt": "2023-05-31T18:50:40.529547Z", "id": "67088" } ], "follows": [ { "follower": { "id": 986, "email": "nick@govly.com" }, "state": "following" } ] } ``` # Update Workspace Source: https://docs.govly.com/api-reference/v3/workspaces/update PATCH /api/v3/opportunity_workspaces/{id} This endpoint updates an existing workspace. ## Path Parameters ID of the workspace to update ## Request Body New stage for the workspace New display name for the workspace This endpoint is part of the legacy v3 API and will be deprecated in the future. Please migrate to the new enterprise API endpoints. # Email Integration Source: https://docs.govly.com/enterprise/email-integration Set up email forwarding for opportunity and award tracking Govly provides enterprise customers with dedicated email addresses for automatic processing of opportunities and awards. This allows you to forward or redirect procurement emails to Govly for automated processing. ## Standard Integration Each organization is provided with a dedicated email address in the format: ``` [organization]@inbound.govly.com ``` Emails forwarded to this address are processed automatically, and relevant content can be added as opportunities or awards in your Govly account. ## Secure Enclave Managed Service For organizations whose managed-ingestion requirements align with Govly's C3PAO-assessed Secure Enclave environment, Govly can provide an organization-specific Secure Enclave email address: ``` [organization]@secure.govly.com ``` Messages sent to this address are processed through a customer-specific Secure Enclave ingestion workflow. Govly personnel provision and maintain the workflow and provide operational support when changes or intervention are needed; customers do not self-provision or administer the underlying service. ## Setting Up Email Forwarding 1. Identify the procurement email addresses you want to forward 2. Set up forwarding rules in your email system to your Govly email address 3. (Optional) Set up filters to only forward relevant procurement emails 4. Monitor your Govly dashboard to confirm emails are being processed as expected ## Best Practices * Test the integration with a few sample emails before setting up full forwarding * Use email filters to avoid forwarding irrelevant emails * Regularly review the processing status in your Govly dashboard * Contact support if you notice any emails not being processed correctly ## Supported Email Types * Opportunity announcements * Award notifications * Bid status updates * Contract modifications * Other procurement-related communications # HubSpot Integration Source: https://docs.govly.com/enterprise/integrations/hubspot Sync Govly opportunities to HubSpot as deals ## What it does The HubSpot integration syncs Govly opportunities to HubSpot as deals. When you push an opportunity from Govly, it creates a deal in your default HubSpot pipeline with Govly-specific fields. If the opportunity is later updated in Govly, the corresponding deal in HubSpot is updated automatically. ## How it works Govly connects to your HubSpot account via OAuth. When you first connect, Govly creates a custom property group called "Govly Opportunity Details" in your HubSpot account. This group contains fields for tracking Govly-specific data on each deal. When you push an opportunity, Govly maps its data to HubSpot deal fields. Native deal properties are set directly, while Govly-specific fields are populated as custom properties in the Govly Opportunity Details group. ## Fields synced to HubSpot ### Native Deal Properties * **Deal Name** (AI-generated title, or original title, or solicitation number) * **Description** (AI summary or source description) * **Close Date** (response deadline) ### Custom Properties (Govly Opportunity Details) | Field | Description | | - | - | | Govly Opp ID | Internal Govly opportunity identifier | | Govly Link | Direct link to the opportunity in Govly | | Solicitation Number | Official solicitation/contract number | | Buyer Name | Contracting agency or organization | | Buyer ID | Govly buyer identifier | | Buyer Hierarchy | Full organizational hierarchy of the buyer | | Posted Date | When the opportunity was posted | | Response Deadline | Due date for proposal submission | | Q\&A Deadline | Deadline for submitting questions | | Modified Date | Last modification date | | Cancelled Date | Cancellation date (if applicable) | | AI Estimated Value (Min) | AI-generated minimum contract value estimate | | AI Estimated Value (Max) | AI-generated maximum contract value estimate | | Contract Vehicle | Associated contract vehicle | | Feed | Source feed for the opportunity | | Jurisdiction | Geographic or administrative jurisdiction | | Set-Aside | Small business set-aside code | | Notice Types | Types of notices (solicitation, award, etc.) | | Public Link | Link to the original source | | Contacts | Point of contact information | | Locations | Place of performance locations | | Partners | Teaming partners associated with the opportunity | | Labels | Organization-specific labels | | Tags | User-applied tags | ## How to use it ### Connecting your account 1. Click **Connect HubSpot** above 2. Authorize Govly when redirected to HubSpot 3. Once authorized, the connection is active and ready to use ### Pushing opportunities to HubSpot 1. From the opportunities page, click the HubSpot button on any opportunity 2. The opportunity will be created as a deal in your default HubSpot pipeline 3. Changes to the opportunity in Govly will automatically update the deal ### Viewing Govly fields in HubSpot Govly custom properties are attached to each deal record automatically. To view them: 1. Open any deal in HubSpot 2. Select **View All Properties** under Actions 3. Look for the **Govly Opportunity Details** property group to see the custom properties added to your deal To make Govly fields visible on your deal view by default: 1. Open any deal in HubSpot 2. Edit any card in the deal view 3. Add one or more custom properties from the **Govly Opportunity Details** property group 4. Save your changes — the fields will appear on all deals using that view # MCP Overview Source: https://docs.govly.com/enterprise/integrations/mcp Connect AI assistants to Govly through the Model Context Protocol Govly's hosted Model Context Protocol (MCP) server lets supported AI assistants use Govly data and tools on your behalf. Connections use your Govly identity and can only access the data and actions available to you in the web app. A connection can also run as an **agent account** — a non-human identity in your organization — so a scheduled or long-running integration does not depend on an employee's account. See [MCP for developers](/enterprise/integrations/mcp/developers). ## What you can do Connected assistants can: * **Search and read opportunities** — keyword and boolean search with status, NAICS, and date filters, plus full opportunity pages with sources and attachments. * **Search and read awarded contracts** — federal, SLED, and international award history with recipient, buyer, funder, and amount filters, plus full award pages with transactions, sub-awards, and line items. * **Work with workspaces** — create workspaces, add members, post comments, follow or unfollow opportunities, awards, and contacts, and list attachments. * **Use saved searches** — list your opportunity saved searches and their cached matches. * **Read and download documents** — inspect bounded existing representations, continue long reads, and request original files only when needed. MCP requires a paid Govly seat, but Enterprise API access is not required to connect. Some tools apply daily limits or smaller page sizes without Enterprise API access, and SLED or international data requires the matching organization subscription. The same operations are also available through the Tools API Reference. ## MCP server URL Use this URL when a client asks for Govly's remote MCP server: ```text theme={null} https://app.govly.com/api/mcp ``` ## Choose a connection guide * [Connect Govly to Claude](/enterprise/integrations/mcp/claude) — install Govly from Claude's connector directory and authorize with your Govly account. * [MCP for developers](/enterprise/integrations/mcp/developers) — connect an API, command-line tool, or other MCP client with OAuth or a personal API key. ## Read and download documents Use `document_read` with the canonical `documentType` and `id` returned by tools such as `show_opportunity` and `show_workspace`. The initial response reports the representations already available for that document. Request `positioned_text` only when it is advertised and layout or geometry matters; reads never create missing analysis or enqueue extraction work. Document reads are bounded. When `meta.hasMore` is true, continue by calling `document_read` with only `meta.nextCursor` and, optionally, `maxChars`. Treat the cursor as opaque. Use `document_download` when you need the authorized original file. Opportunity responses may omit embedded attachment URLs; the download tool re-authorizes access and returns a fresh URL with its expiration time. ## Using MCP across multiple Govly organizations Connections are scoped to one Govly organization. An OAuth connection uses the organization you were viewing when you authorized it; switching organizations in Govly later does not change the connection. Personal API keys are also tied to the organization where they were created. To use MCP with another organization, create a separate connection while viewing that organization or create a personal API key from that organization. ## Manage connections * Manage OAuth connections under **Govly Settings → API → Connected Apps**. * Manage personal API keys under **Govly Settings → API → API Keys**. * Manage agent accounts and their keys under **Govly Settings → API → Agent Accounts**. Revoking an OAuth grant immediately invalidates that connection. For setup-specific troubleshooting, use the relevant connection guide above. Still stuck? Email **[support@govly.com](mailto:support@govly.com)** with the client you're using and any error messages you're seeing. # Connect to Claude Source: https://docs.govly.com/enterprise/integrations/mcp/claude Install Govly from Claude's connector directory Connect Claude to Govly to research opportunities, review your organization's data, and use available Govly tools without leaving your conversation. Govly is available in Claude's connector directory, so you do not need to enter an MCP server URL. ## Before you start You need: * A Govly account with a paid seat. Enterprise API access is not required. * A Claude account or workspace that allows connectors. * Permission to sign in to Govly and authorize the connection. You do not need to create an API key, enter OAuth client credentials, or edit `claude_desktop_config.json`. On Claude Team and Enterprise plans, an Owner or Primary Owner must first go to **Organization settings → Connectors → Browse connectors**, select **Govly**, and choose **Add to your team**. Each member then connects and authorizes their own Govly account. ## Connect to Claude Open Claude and select **Customize → Connectors**. Select the **+** button next to Connectors, then select **Browse connectors**. Select **Connectors** in the directory, search for `Govly`, and open the Govly connector. Select **Connect** or **Install** to begin setup. In a Team or Enterprise workspace, Govly must first be enabled by an Owner or Primary Owner. Sign in to Govly if prompted. Review the authorization request and select **Allow**. Start a Claude conversation, select the **+** button, open **Connectors**, and enable Govly. For more information about Claude workspace permissions and connector behavior, see Anthropic's [connector guide](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities). ## Try the connection Start a conversation with a request such as: * “Search Govly for open cybersecurity opportunities with response deadlines in the next 30 days.” * “Show my Govly workspaces and summarize the next action for each one.” Claude can only access Govly data and actions available to the Govly user who authorized the connection. Claude may ask for approval before using tools that take actions in Govly. ## Disconnect Claude To disconnect Govly in Claude, go to **Customize → Connectors**, open Govly, and disconnect or remove the connector. To revoke Claude's access from Govly, go to **Govly Settings → API → Connected Apps**, find the Claude connection, and select **Revoke**. Claude must be authorized again before it can reconnect. # MCP for Developers Source: https://docs.govly.com/enterprise/integrations/mcp/developers Connect APIs and developer tools to Govly MCP Use this guide to connect an AI provider API, command-line tool, or other MCP client to Govly. To use Govly in the hosted Claude app, follow [Connect to Claude](/enterprise/integrations/mcp/claude) instead. ## Before you start You need: * A Govly account with a paid seat. Enterprise API access is not required to connect. * A client that supports remote HTTP MCP servers. * A Govly API key if your client only accepts a static bearer token — either a personal key or an agent account key, depending on who is driving the connection. Use Govly's remote MCP server URL: ```text theme={null} https://app.govly.com/api/mcp ``` ## Choose an authentication method Start with one question: **is this connection an integration, or is it you?** | You are connecting… | Use | Why | | - | - | - | | Yourself, in a client that supports OAuth | **OAuth** | Actions are attributed to you and the connection is revocable in one place. | | Yourself, in a client that only takes a bearer token | **Personal API key** | Still your identity — just no OAuth flow available. | | An integration that runs on a schedule or outlives whoever set it up | **Agent account key** | The integration owns its own identity instead of borrowing a person's. | The deciding question for that last row: **if the person who set this up left tomorrow, should it keep running?** If yes, use an agent account. A personal key stops working when that person is deactivated, which takes the integration down with them. ### Connect with OAuth In your client, add a remote MCP server named `Govly` with the URL `https://app.govly.com/api/mcp`. Follow the browser prompt and sign in to your existing Govly account. Govly's OAuth flow does not create new users. Review the authorization request and approve the connection. Ask the client to list its Govly tools or try a small request such as, “What workspaces do I have in Govly?” Clients that support OAuth discovery do not require a separate OAuth client ID or client secret. Manage OAuth connections under **Govly Settings → API → Connected Apps**. ## Connect with a personal API key A personal API key lets an external client access Govly as you. Store it in a secret manager or environment variable, never commit it to source control, and revoke it immediately if it is exposed. ### Create a personal API key In Govly, go to **Settings → API → API Keys**. Under **Personal API Keys**, select **New key** and name it after the client that will use it. Copy the `gk_...` token into a secret manager or environment variable. The token stays visible on this page, so treat access to your API settings as access to the key itself. You can keep up to two active personal keys at a time. Personal keys are tied to a specific user and must not be shared across users or systems. ### Configure your client Most MCP clients accept a configuration block like this: ```json theme={null} { "mcpServers": { "govly": { "url": "https://app.govly.com/api/mcp", "headers": { "Authorization": "Bearer gk_" } } } } ``` The exact configuration format and location vary by client. Use your client's secure secret or authorization-token setting when available instead of saving the key directly in a configuration file. ### Connect through an AI provider API When an AI provider API supports remote MCP servers: 1. Add a remote MCP server named `govly`. 2. Use `https://app.govly.com/api/mcp` as the server URL. 3. Use your personal Govly API key as the server authorization token. 4. Require approval for tool calls while you test the integration. 5. Start with a low-risk request, such as listing Govly tools or running one opportunity search. Provider request formats differ, so use the provider's current remote MCP documentation for exact field names and approval settings. ### Verify the connection Send a JSON-RPC `tools/list` request with your personal key: ```bash theme={null} curl -X POST https://app.govly.com/api/mcp \ -H "Authorization: Bearer gk_" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` A successful response lists the Govly tools available to your account, including `search_opportunities`, `search_awards`, `search_contacts`, `search_places`, `list_places`, `document_read`, `document_download`, `search_workspaces`, and `list_workspaces`. Use `search_workspaces` to discover the organization's Active Work; use `list_workspaces` when you already know an exact associated entity type and ID. ## Connect with an agent account key An **agent account** is a non-human identity in your organization. It holds its own API keys, so a durable integration does not depend on an employee's account and does not share an organization-wide credential that belongs to nobody. Agent accounts are not people. They have no mailbox, cannot sign in, do not receive notifications or digests, and cannot be shared with or @-mentioned. They act only through their API keys. An organization admin goes to **Settings → API → Agent Accounts** and creates an agent, naming it after the integration it will run. Select **New key** on that agent, then copy the `gk_...` token. Put it in a secret manager or environment variable, never in source control. The token stays visible on the Agent Accounts page, so anyone who can administer your organization's API settings can read it. Revoke a key if you suspect it has been exposed — revocation is immediate and permanent. Use the same configuration as a personal key, with the agent's token as the bearer value. Each organization can hold up to five active agent accounts, and each agent can hold two keys so a key can be replaced without downtime. Agent accounts cannot use OAuth, because they cannot sign in. That also means they cannot be used with the Govly connector in the hosted Claude app, which authorizes through a browser sign-in. Use an agent key from a client that accepts a bearer token — a command-line tool, an AI provider API, or your own scheduled job. ### Developing against an agent account Use the agent's key while you build the integration, not your own. You will be testing with the identity that will actually run in production, so permission and subscription differences surface during development rather than after deploy. ### Deciding what to build on MCP is worth its complexity when a model needs to choose which tools to call. If your code already knows which calls to make — fetch new matches, filter by NAICS, write to your CRM — the [Tools API](/api-reference/tools-v1) is simpler, cheaper, and easier to test. An agent account key works on either surface. ## Multiple Govly organizations OAuth connections, personal API keys, and agent accounts are all scoped to the Govly organization where they were authorized or created. To connect another organization, authorize a separate OAuth connection while viewing that organization, or create a separate key from it. ## Manage keys Key-based connections do not appear under **Connected Apps**. * Personal keys — **Govly Settings → API → API Keys**. * Agent account keys — **Govly Settings → API → Agent Accounts**, on the agent that owns them. After rotating a key, update every client that used the previous value. Revoking a key is permanent; issue a new one rather than expecting to restore it. Archiving an agent revokes its keys and stops it authenticating immediately, while leaving its past activity attributed to it. ## Troubleshooting | Issue | What to check | | - | - | | `401 Unauthorized` | Confirm the key is correct, active, and sent as a bearer token. If it belongs to an agent, confirm the agent has not been archived. | | `401 Grant has been revoked` | Reconnect through your client's OAuth flow. | | `403 Paid Govly seat required` | An agent inherits its organization's subscription rather than holding a seat, so check the organization's plan. | | A tool you expected is missing | Some tools require Enterprise API access or another Govly subscription. Contact your Govly administrator if you believe you should have access. | | The connection is missing from Connected Apps | Key-based connections are managed under API Keys or Agent Accounts instead. | | An agent key fails in the hosted Claude app | That connector authorizes through browser sign-in, which agents cannot do. Use a client that accepts a bearer token. | Still stuck? Email **[support@govly.com](mailto:support@govly.com)** with the client you're using and any error messages you're seeing. # Salesforce Integration Source: https://docs.govly.com/enterprise/integrations/sfdc Sync Govly opportunities to Salesforce as custom Govly Opportunity objects ## What it does The Salesforce integration syncs Govly opportunities to Salesforce as custom Govly Opportunity objects. When you push an opportunity from Govly, it creates a Govly Opportunity record in your Salesforce org with fields containing the opportunity data. If the opportunity is later updated in Govly, the corresponding Govly Opportunity record in Salesforce is updated automatically. Unlike HubSpot where Govly creates deals directly, Salesforce uses a custom Govly Opportunity object. This gives you full control over how Govly data flows into your native Salesforce Opportunities through Salesforce's workflow automation tools. ## How it works Govly connects to your Salesforce org via OAuth, and the Govly companion app — a managed package you install in Salesforce — provides a custom Govly Opportunity object. This object contains fields for tracking Govly-specific data including solicitation details, buyer information, timing dates, AI-generated summaries, and links back to Govly. When you push an opportunity, Govly maps its data to the Govly Opportunity object fields. ## Fields synced to Salesforce ### Govly Opportunity Object Fields | Field | Description | | - | - | | Name | Solicitation number + title | | Govly Opp ID | Internal Govly opportunity identifier | | Govly Link | Direct link to the opportunity in Govly | | Solicitation Number | Official solicitation/contract number | | Title | Original opportunity title | | Description | AI summary or source description | | AI Title | AI-generated title | | AI Summary | AI-generated summary | | AI Estimated Value (Min) | AI-generated minimum contract value estimate | | AI Estimated Value (Max) | AI-generated maximum contract value estimate | | Buyer Name | Contracting agency or organization | | Buyer ID | Govly buyer identifier | | Buyer Hierarchy | Full organizational hierarchy of the buyer | | Posted Date | When the opportunity was posted | | Response Deadline | Due date for proposal submission | | Q\&A Deadline | Deadline for submitting questions | | Modified Date | Last modification date | | Cancelled Date | Cancellation date (if applicable) | | Contract Vehicle | Associated contract vehicle | | Feed | Source feed for the opportunity | | Jurisdiction | Geographic or administrative jurisdiction | | Set-Aside | Small business set-aside code | | Notice Types | Types of notices (solicitation, award, etc.) | | Public Link | Link to the original source | | Contacts | Point of contact information | | Locations | Place of performance locations | | Partners | Teaming partners associated with the opportunity | | Labels | Organization-specific labels | | Tags | User-applied tags | | Submitted By (Name) | Name of the Govly user who first pushed the opportunity to Salesforce | | Submitted By (Email) | Email of the Govly user who first pushed the opportunity to Salesforce | ## How to use it ### Connecting your account 1. Make sure the Govly companion app is installed in your Salesforce org — a Salesforce admin can [install it here](https://login.salesforce.com/packaging/installPackage.apexp?p0=04taj000000TkIp) 2. Click **Connect Salesforce** above 3. Authorize Govly when redirected to Salesforce 4. Once authorized, the connection is active and ready to use ### Pushing opportunities to Salesforce 1. From the opportunities page, click the Salesforce button on any opportunity 2. The opportunity will be created as a Govly Opportunity record in Salesforce 3. Changes to the opportunity in Govly will automatically update the record ### Viewing Govly data in Salesforce Govly Opportunity records are stored as a custom object. To view them: 1. In Salesforce, navigate to the App Launcher 2. Search for "Govly Opportunities" or find it in your object list 3. Click to view all synced Govly Opportunity records ### Syncing to native Salesforce Opportunities Since Govly creates custom Govly Opportunity objects rather than native Opportunities, you can use Salesforce automation to sync data to your existing pipeline: 1. Create a Flow or Process Builder workflow in Salesforce 2. Configure a trigger for when a Govly Opportunity is created or updated 3. Map the Govly Opportunity fields to your native Opportunity fields 4. Set any default values (stage, owner, record type) as needed This approach lets you control which Govly opportunities enter your pipeline and how they're categorized within your existing Salesforce setup. ## Troubleshooting * **Missing or out-of-date fields?** Make sure your Salesforce admin has installed the latest Govly companion app: [install it here](https://login.salesforce.com/packaging/installPackage.apexp?p0=04taj000000TkIp). * **Don't see a field on a record?** New fields aren't added to your page layout automatically — add them under Setup → Object Manager → Govly Opportunity → Page Layouts (and any list views) to surface them. # Single Sign-On (SSO) Source: https://docs.govly.com/enterprise/integrations/sso Govly supports SAML 2.0-based Single Sign-On, allowing your team to authenticate using your organization's identity provider ## Supported Identity Providers Govly SSO works with any SAML 2.0 compliant identity provider, including: * Okta * Azure Active Directory * Google Workspace * OneLogin * Ping Identity ## Getting Started To configure SSO for your organization, contact [support@govly.com](mailto:support@govly.com) and our team will guide you through the setup process. # Overview Source: https://docs.govly.com/enterprise/security An overview of Govly’s approach to safeguarding data and supporting privacy requirements. Govly treats privacy and security as core parts of operating the platform. This page summarizes our approach to safeguarding data and supporting privacy requirements. ## Security Program Govly maintains a security and privacy program covering access management, secure development, vulnerability management, incident response, vendor management, and workforce training. Govly has completed a SOC 2 Type I examination and is preparing to enter a SOC 2 Type II observation period in August 2026. Contact [support@govly.com](mailto:support@govly.com) for current independent assessment reports and their scope. ## The Data in Scope Govly processes public procurement data and customer-provided account and workflow content needed to deliver the service. Customers control the users and content in their organizations. Govly does not sell or rent customer-provided information. ## Infrastructure Govly uses AWS-hosted infrastructure in United States regions. Safeguards include network segmentation, access controls, multi-factor authentication for administrative access, patching, vulnerability scanning, logging, and threat detection. AWS compliance programs apply to AWS services and do not by themselves certify Govly. ## Network and Data Encryption Govly uses TLS for data in transit and encryption at rest for production data. ## Product Security Administrators manage user access for their Govly organization. Govly also supports [SAML-based single sign-on](/enterprise/integrations/sso). Govly separately identifies and manages [restricted opportunity attachments](/enterprise/security/restricted-opportunity-attachments), including customer-configurable access controls and automatic retention for eligible files. # Opportunity Attachment Handling Source: https://docs.govly.com/enterprise/security/restricted-opportunity-attachments How Govly handles opportunity attachments with document-control markings Govly Commercial, our core multi-tenant product, receives solicitation-level opportunity attachments from public procurement sources and customer-provided workflows. Some documents retain control or distribution markings even when they have been published openly. Govly handles observed markings, where an attachment was found, file access, and retention as separate questions. ## What the Tags Mean Govly may show the following tags on an opportunity attachment: * **Sensitive Markings Detected** means automated review found one or more document-control signals, such as a page banner, designation block, distribution statement, or export-control warning. The tag's tooltip explains the observed signals. * **Content Restricted** means Govly applies additional file-handling controls to the attachment in Commercial. * **Public Source** means Govly obtained the marked attachment from a publicly accessible procurement feed. Under Govly's current Commercial handling rules, that source does not trigger the **Content Restricted** tag. The detection tag records observed signals. It does not change file access by itself; access is affected only when the attachment also has a **Content Restricted** tag. Commercial determines the **Content Restricted** tag from both the markings found by Govly's automated detection system and the source where Govly obtained the file. A public-feed source or recognized Distribution Statement A language does not trigger the tag. Distribution Statement C alone also does not trigger it, but another detected marking may. Other detected markings on attachments available only through non-public feeds result in the **Content Restricted** tag. ## File Access in Commercial Restricted attachments remain listed so users can see the filename, associated opportunity, and available marking information. Whether the file itself can be opened depends on Govly's access controls and whether Commercial received or still retains the file. * Free organizations cannot view or download restricted attachment files. * A paid organization's administrator can enable **Block restricted opportunity attachments** under **Settings → Security**. * Govly can apply restricted attachment blocking across all Commercial organizations. * Restricted files are not included in external attachment-sharing workflows, even when paid in-product access remains available. * A file removed through the retention process, or never sent to Commercial, remains metadata-only regardless of access settings. A paid organization can access a retained restricted file only while neither its organization control nor the Commercial-wide control is enabled. The Commercial-wide setting takes precedence over an organization's setting. Controls that disable all opportunity attachment downloads or email attachments remain separate and can be used for a broader policy. ## Summaries and Search Govly has a Commercial-wide control that prevents restricted attachment text from being newly extracted or added to summaries and search records. Opportunity summaries and search records are not generated separately for each organization's settings, so this control is applied consistently across Commercial rather than configured per organization. File access and summary/search processing are separate controls. Blocking a download does not by itself remove historical summary or search content, and changing summary/search processing does not by itself determine whether a user may open a retained file. ## File Retention Govly reviews non-public attachments tagged **Content Restricted** on a recurring schedule. Each linked opportunity contributes its response deadline, or its posting date when no response deadline is available. The latest of those dates controls, and the file becomes eligible for removal three months later. If any linked opportunity has neither date, Govly does not schedule the file for removal. Before removing a file, Govly checks the current opportunity dates, whether it has since appeared on a public feed, its current restricted status, and whether the file still exists. A file is not removed if it has become public, is no longer restricted, lacks a reliable qualifying date, or otherwise no longer qualifies. When removal proceeds, Govly removes the stored original attachment, text previously extracted from the file, and the attachment summary. The attachment record and source filename remain visible so users can understand what was associated with the opportunity. If the same file later appears through a source that qualifies for normal Commercial processing under Govly's current handling rules, Govly reassesses it and can restore normal processing subject to the current access controls. ## How Secure Enclave Fits In [Secure Enclave](/enterprise/security/secure-enclave) is a separate Govly-operated managed-ingestion service for customers whose requirements align with that environment. It is not an automatic destination for files blocked in Commercial. For configured Secure Enclave workflows, Commercial can receive the opportunity and attachment details without receiving the file. Users can still see that an attachment exists, but Commercial provides no file link. Govly works with each customer to provision and maintain these workflows. Customers evaluating Secure Enclave managed services should contact [support@govly.com](mailto:support@govly.com) to discuss source systems, workflow requirements, and available compliance documentation. ## Available Controls | Control | Scope | Effect | | - | - | - | | Block restricted opportunity attachments | Organization | An organization administrator prevents members from viewing or downloading restricted files. | | Commercial-wide restricted attachment access | Govly Commercial | Govly makes restricted files unavailable for viewing and downloading across Commercial. | | Keep restricted content out of summaries and search | Govly Commercial | Govly prevents restricted attachment text from being newly extracted or added to summaries and search records. | | Recurring file retention review | Govly Commercial | Govly periodically reviews non-public restricted files and removes those that remain eligible once three months have passed since their latest qualifying opportunity date. | | Secure Enclave managed ingestion | Customer workflow | Govly operates a separate managed-ingestion workflow and can send attachment details, rather than the file, into Commercial. | ## Planned Commercial Access Update Govly currently targets **December 1, 2026**, to make **Content Restricted** files unavailable for viewing and downloading across Commercial. Organizations will not need to change their own settings for this update to apply. Before the change, Govly will notify affected customers and work with them on appropriate source-portal or Secure Enclave workflows. The planned date may change as Govly completes its customer impact review and rollout preparation. Questions about an attachment or your organization's settings can be directed to [support@govly.com](mailto:support@govly.com). # Secure Enclave Source: https://docs.govly.com/enterprise/security/secure-enclave C3PAO-assessed CMMC Level 2 managed ingestion services Govly's Secure Enclave was independently assessed by an authorized C3PAO and achieved CMMC Level 2 certification for its assessed environment. It supports managed ingestion services for enterprise customers. These are Govly-operated services rather than self-service cloud offerings. Govly personnel provision and maintain customer-specific ingestion workflows and provide operational support when changes or intervention are needed. For configured workflows, Commercial can receive opportunity and attachment metadata without receiving a restricted file. See [Restricted Opportunity Attachments](/enterprise/security/restricted-opportunity-attachments) for how that metadata-only presentation relates to Commercial access and retention controls. ## Managed Services ### Secure Email Ingestion Process procurement emails through an organization-specific Secure Enclave address: ```text theme={null} [organization]@secure.govly.com ``` See [Email Integration](/enterprise/email-integration) for workflow details. ### Web Automation Govly can provide managed monitoring for supported procurement portals. See [Web Automation](/enterprise/web-automation) for setup details. ## Getting Access If your organization's requirements align with the assessed Secure Enclave environment: 1. Contact [support@govly.com](mailto:support@govly.com) to discuss your requirements 2. Request access to our Secure Enclave managed services 3. Review the available compliance documentation with Govly ## Compliance Documentation Contact [support@govly.com](mailto:support@govly.com) to discuss available Secure Enclave compliance documentation. # SOC 2 Source: https://docs.govly.com/enterprise/security/soc2 Information about Govly’s SOC 2 program and available documentation Govly has completed a SOC 2 Type I examination and is preparing to enter a SOC 2 Type II observation period in August 2026. ## Scope and Documentation The report type, audit period, trust services criteria, and system scope are defined in the applicable report. Customers and prospective customers may request available documentation. Access may require a nondisclosure agreement. ## Requesting Documentation Contact [support@govly.com](mailto:support@govly.com) with your organization name and contact information. Govly will confirm the documentation currently available and any required next steps. ## Questions For questions about Govly’s SOC 2 program, contact [support@govly.com](mailto:support@govly.com). # Web Automation Source: https://docs.govly.com/enterprise/web-automation Managed procurement portal monitoring through Govly Secure Enclave Govly provides managed monitoring of supported procurement portals. Secure Enclave web automation is available for organizations whose requirements align with Govly's C3PAO-assessed Secure Enclave environment. ## Overview Our web automation service can monitor various procurement portals and automatically: * Track new opportunities * Monitor changes to existing opportunities * Capture award information * Download relevant attachments ## Secure Enclave Managed Service Secure Enclave web automation is delivered as a Govly-operated managed service. Govly personnel provision and maintain each customer-specific workflow and provide operational support when changes or intervention are needed. Govly works with each customer to define supported portals, credentials, monitoring parameters, and delivery requirements; customers do not self-provision or administer the underlying service. ## Setup Process 1. Contact your Govly representative to initiate setup 2. Provide necessary portal credentials and access requirements 3. Define monitoring parameters and requirements 4. Review and approve the automation configuration 5. Monitor results in your Govly dashboard ## Security Considerations * Define account access and monitoring scope with your Govly representative * Review collected results and report unexpected behavior to support ## Support For questions about web automation setup or to initiate the process, please: * Contact your Govly representative * Email [support@govly.com](mailto:support@govly.com) * Schedule a consultation through your account dashboard # Introduction Source: https://docs.govly.com/getting-started/introduction Govly specializes in ingesting, parsing, and analyzing government contracting data. These docs will help you set up data ingestion pipelines, configure integrations with your existing systems, and implement webhooks for real-time notifications. While our enterprise API is currently only available to customers, we are actively expanding our public API endpoints to help more developers analyze government contracting data. ## Quick Links * [API Documentation](/api-reference/enterprise) * [API Rate Limits](/api-reference/enterprise/rate-limits) * [Email Ingestion Pipeline](/enterprise/email-integration) * [Procurement Portal Automation](/enterprise/web-automation) * [Webhook Overview](/api-reference/enterprise/webhooks/overview) ## Security & Compliance Govly offers managed ingestion services through its Secure Enclave, which was independently assessed by an authorized C3PAO and achieved CMMC Level 2 certification for its assessed environment. Govly personnel provision and maintain customer-specific workflows and provide operational support when changes or intervention are needed. See [Secure Enclave](/enterprise/security/secure-enclave) or contact [support@govly.com](mailto:support@govly.com) to discuss your requirements and available compliance documentation. ## Support If you have a specific API need or question, please reach out to [support@govly.com](mailto:support@govly.com). # Webhook Events Source: https://docs.govly.com/webhooks/events Available webhook events # Webhook Events Events are named with the format `RESOURCE_TYPE.EVENT`. The `RESOURCE_TYPE` corresponds to the shape of the payload. For example, `FOLLOWED_OPP.MODIFIED` will have a payload that mimics the `/v3/opportunities/{{id}}` endpoint. ## Available Events The following webhook events are available to subscribe to: ### Workspace Events * `OPP_WORKSPACE.FOLLOWED` - Sent when a user follows a workspace * `OPP_WORKSPACE.STATUS_CHANGED` - Sent when a workspace's status changes #### `OPP_WORKSPACE.STATUS_CHANGED` All organizations have default statuses (Qualifying, Intend to Bid, Quoted, Submitted, Awarded, Not Awarded, No Bid) and can define custom statuses. `STATUS_CHANGED` fires for all status transitions. The payload includes the current and previous status, so consumers know exactly what changed. `displayStatus` is the status name (e.g., "Qualifying" or a custom name like "Proposal Drafting"). Each status belongs to a stable `statusCategory` (`triage`, `planned`, `in_progress`, `completed`, `canceled`). **Example payload:** ```json theme={null} { "event": "OPP_WORKSPACE.STATUS_CHANGED", "payload": { "id": "workspace-uuid", "createdAt": "2026-02-10T10:30:00Z", "updatedAt": "2026-02-18T14:22:00Z", "displayName": "Workspace Name", "archivedAt": null, "commentsCount": 3, "private": false, "createdByOrganization": "Acme Corp", "url": "https://app.govly.com/opportunities/{opp_id}/workspaces/{workspace_id}", "statusCategory": "in_progress", "displayStatus": "Proposal Drafting", "statusId": "status-uuid", "previousStatusCategory": "triage", "previousDisplayStatus": "Qualifying", "previousStatusId": "status-uuid", "comments": [], "follows": [], "opportunity": { "..." : "full opportunity object" }, "activities": [] } } ``` **Status fields:** | Field | Type | Description | | - | - | - | | `statusCategory` | string | The stable category the status belongs to. One of: `triage`, `planned`, `in_progress`, `completed`, `canceled` | | `displayStatus` | string | The status name (e.g., a default like "Qualifying" or a custom name like "Proposal Drafting") | | `statusId` | string or null | ID of the status | | `previousStatusCategory` | string | The status category before this change | | `previousDisplayStatus` | string | The display status before this change | | `previousStatusId` | string or null | ID of the previous status | ### Opportunity Events Events handled by Govly's opportunity processing pipeline in real time: * `FOLLOWED_OPP.MODIFIED` - Sent when modifications hit Govly * `FOLLOWED_OPP.ENRICHED` - Sent when Govly finishes LLM summarization # Webhook Security Source: https://docs.govly.com/webhooks/security Learn how to secure your webhooks # Webhook Security Webhook requests sent from Govly are signed with your Webhook Signature Key which can be found on the API integration dashboard. ## Signature Verification Each request will include the `Govly-Webhook-Signature` header which is a SHA2 hex digest of the webhook checksum, signed with your secret key. To verify the signature, you can join your secret key and the webhook checksum on a period. Then, compare the result to `Govly-Webhook-Signature` to confirm the request is from Govly. ## Example Implementation Here's an example of how you might verify a Govly webhook's authenticity in Ruby: ```ruby theme={null} webhook_signature = webhook_request.headers["Govly-Webhook-Signature"] webhook_checksum = webhook_request.headers["Govly-Webhook-Event-Checksum"] webhook_signature_key = ENV["GOVLY_WEBHOOK_SIGNATURE_KEY"] valid_signature = Digest::SHA2.hexdigest("#{webhook_signature_key}.#{webhook_checksum}") valid = webhook_signature == valid_signature ``` ## Alternative Authentication Alternatively, you can use the custom headers option described in the Header section of the webhook documentation when creating a webhook to include a private credential of your choice to authenticate the request.