HHS (US Department of Health and Human Services)
HHS (US Department of Health and Human Services) Opportunity v1 - for Grantors API

The Opportunity v1 - for Grantors API from HHS (US Department of Health and Human Services) — 8 operation(s) for opportunity v1 - for grantors.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  description: '

    Back end API for simpler.grants.gov.


    This API is in active development as we build out new functionalities for Simpler.Grants.gov. It is currently stable for everyday use, and will be versioned with advance notice for any breaking changes.


    Learn more in our [API documentation](https://wiki.simpler.grants.gov/product/api).

    See [Release Phases](https://github.com/github/roadmap?tab=readme-ov-file#release-phases) for further details.

    '
  contact:
    name: Simpler Grants.gov
    url: https://simpler.grants.gov/
    email: simpler@grants.gov
  title: Simpler Grants Opportunity v1 - for Grantors API
  version: v0
servers: .
tags:
- name: Opportunity v1 - for Grantors
paths:
  /v1/grantors/opportunities:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityCreateResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Create a new opportunity
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunityCreateRequestSchema'
      security:
      - ApiJwtAuth: &id001 []
      - ApiUserKeyAuth: *id001
  /v1/grantors/opportunities/{opportunity_id}:
    get:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityGetResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Get an editable opportunity for grantors
      security:
      - ApiJwtAuth: &id002 []
      - ApiUserKeyAuth: *id002
    put:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityUpdateResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Opportunity v1 - for Grantors
      summary: Update an existing opportunity
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunityUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id003 []
      - ApiUserKeyAuth: *id003
  /v1/grantors/agencies/{agency_id}/opportunities:
    post:
      parameters:
      - in: path
        name: agency_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityListResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Get paginated list of opportunities by agency
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunityListRequestSchema'
      security:
      - ApiJwtAuth: &id004 []
      - ApiUserKeyAuth: *id004
  /v1/grantors/opportunities/{opportunity_id}/publish:
    post:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityPublishResponseV1Schema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Publish an opportunity
      security:
      - ApiJwtAuth: &id005 []
      - ApiUserKeyAuth: *id005
  /v1/grantors/opportunities/{opportunity_id}/summaries:
    post:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunitySummaryCreateResponseV1Schema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Create a new opportunity summary
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunitySummaryCreateRequestV1Schema'
      security:
      - ApiJwtAuth: &id006 []
      - ApiUserKeyAuth: *id006
  /v1/grantors/opportunities/{opportunity_id}/attachments:
    post:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityUploadAttachmentResponseV1Schema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Upload an attachment to an opportunity
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OpportunityUploadAttachmentRequestV1Schema'
      security:
      - ApiJwtAuth: &id007 []
      - ApiUserKeyAuth: *id007
  /v1/grantors/opportunities/{opportunity_id}/summaries/{opportunity_summary_id}:
    put:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      - in: path
        name: opportunity_summary_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunitySummaryUpdateResponseV1Schema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Update an existing opportunity summary
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunitySummaryUpdateRequestV1Schema'
      security:
      - ApiJwtAuth: &id008 []
      - ApiUserKeyAuth: *id008
  /v1/grantors/opportunities/{opportunity_id}/attachments/{opportunity_attachment_id}:
    delete:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      - in: path
        name: opportunity_attachment_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAttachmentResponseV1Schema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Opportunity v1 - for Grantors
      summary: Delete an attachment from an opportunity
      security:
      - ApiJwtAuth: &id009 []
      - ApiUserKeyAuth: *id009
components:
  schemas:
    OpportunitySummaryCreateRequestV1Schema:
      type: object
      properties:
        summary_description:
          type:
          - string
          - 'null'
          maxLength: 18000
          description: Opportunity summary
          example: This opportunity...
        is_cost_sharing:
          type:
          - boolean
          - 'null'
          description: Whether or not the opportunity has a cost sharing/matching requirement
        post_date:
          type: string
          format: date
          description: The date the opportunity was posted
        close_date:
          type:
          - string
          - 'null'
          format: date
          description: The date the opportunity closes
        close_date_description:
          type:
          - string
          - 'null'
          description: Optional details regarding the close date
          example: Proposals are due earlier than usual.
        archive_date:
          type:
          - string
          - 'null'
          format: date
          description: When the opportunity will be archived (defaults to 30 days after the close date)
        expected_number_of_awards:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 999999999999999
          description: The number of awards the opportunity is expected to award
          example: 10
        estimated_total_program_funding:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 999999999999999
          description: The total program funding of the opportunity in US Dollars
          example: 10000000
        award_floor:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 999999999999999
          description: The minimum amount an opportunity would award
          example: 10000
        award_ceiling:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 999999999999999
          description: The maximum amount an opportunity would award
          example: 100000
        additional_info_url:
          type:
          - string
          - 'null'
          maxLength: 250
          description: A URL to a website that can provide additional information about the opportunity
          example: grants.gov
        additional_info_url_description:
          type:
          - string
          - 'null'
          maxLength: 250
          description: The text to display for the additional_info_url link
          example: Click me for more info
        forecasted_post_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the opportunity is expected to be posted, and transition out of being a forecast
        forecasted_close_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the opportunity is expected to be close once posted.
        forecasted_close_date_description:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Forecasted opportunity only. Optional details regarding the forecasted closed date.
          example: Proposals will probably be due on this date
        forecasted_award_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the grantor plans to award the opportunity.
        forecasted_project_start_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the grantor expects the award recipient should start their project
        fiscal_year:
          type:
          - integer
          - 'null'
          minimum: 1900
          maximum: 2100
          description: Forecasted opportunity only. The fiscal year the project is expected to be funded and launched
          example: 2026
        funding_categories:
          type: array
          minItems: 1
          description: Categories of funding for this opportunity
          example:
          - education
          - health
          items:
            enum:
            - recovery_act
            - agriculture
            - arts
            - business_and_commerce
            - community_development
            - consumer_protection
            - disaster_prevention_and_relief
            - education
            - employment_labor_and_training
            - energy
            - environment
            - food_and_nutrition
            - health
            - housing
            - humanities
            - infrastructure_investment_and_jobs_act
            - information_and_statistics
            - income_security_and_social_services
            - law_justice_and_legal_services
            - natural_resources
            - opportunity_zone_benefits
            - regional_development
            - science_technology_and_other_research_and_development
            - transportation
            - affordable_care_act
            - other
            - energy_infrastructure_and_critical_mineral_and_materials
            - recreation_and_tourism
            type:
            - string
        funding_category_description:
          type:
          - string
          - 'null'
          maxLength: 2500
          description: Additional information about the funding category
          example: Economic Support
        funding_instruments:
          type: array
          minItems: 1
          description: Types of funding instruments used for this opportunity
          example:
          - cooperative_agreement
          - grant
          items:
            enum:
            - cooperative_agreement
            - grant
            - procurement_contract
            - other
            type:
            - string
        applicant_types:
          type: array
          minItems: 1
          description: Types of applicants eligible for this opportunity
          example:
          - state_governments
          - county_governments
          items:
            enum:
            - state_governments
            - county_governments
            - city_or_township_governments
            - special_district_governments
            - independent_school_districts
            - public_and_state_institutions_of_higher_education
            - private_institutions_of_higher_education
            - federally_recognized_native_american_tribal_governments
            - other_native_american_tribal_organizations
            - public_and_indian_housing_authorities
            - nonprofits_non_higher_education_with_501c3
            - nonprofits_non_higher_education_without_501c3
            - individuals
            - for_profit_organizations_other_than_small_businesses
            - small_businesses
            - other
            - unrestricted
            type:
            - string
        applicant_eligibility_description:
          type:
          - string
          - 'null'
          maxLength: 4000
          description: Additional information about the types of applicants that are eligible
          example: All types of domestic applicants are eligible to apply
        agency_contact_description:
          type:
          - string
          - 'null'
          maxLength: 1000
          description: Information regarding contacting the agency who owns the opportunity
          example: For more information, reach out to Jane Smith at agency US-ABC
        agency_email_address:
          type:
          - string
          - 'null'
          maxLength: 130
          description: The contact email of the agency who owns the opportunity
          example: fake_email@grants.gov
        agency_email_address_description:
          type:
          - string
          - 'null'
          maxLength: 108
          description: The text for the link to the agency email address
          example: Click me to email the agency
        is_forecast:
          type: boolean
          description: Whether the opportunity is forecasted
          example: false
      required:
      - agency_contact_description
      - agency_email_address
      - agency_email_address_description
      - applicant_types
      - award_ceiling
      - award_floor
      - funding_categories
      - funding_instruments
      - is_cost_sharing
      - is_forecast
      - post_date
      - summary_description
    FormAlphaSchema:
      type: object
      properties:
        form_id:
          type: string
          format: uuid
          description: The primary key ID of the form
          example: 123e4567-e89b-12d3-a456-426614174000
        form_name:
          type: string
          description: The name of the form
          example: ABC Project Form
        short_form_name:
          type: string
          description: The short name of the form used for making files
          example: abc_project
        form_version:
          type: string
          description: The version of the form
          example: '1.0'
        agency_code:
          type: string
          description: The agency code for the form
          example: SGG
        omb_number:
          type:
          - string
          - 'null'
          description: The OMB number for the form
          example: 4040-0001
        legacy_form_id:
          type:
          - integer
          - 'null'
          description: The legacy form ID
          example: 123
        form_json_schema:
          type: object
          description: The JSON Schema representation of the form
          example:
            type: object
            title: Test form for testing
            properties:
              Title:
                title: Title
                type: string
                minLength: 1
                maxLength: 60
              Description:
                title: Description for application
                type: string
                minLength: 0
                maxLength: 15
              ApplicationNumber:
                title: Application number
                type: number
                minLength: 1
                maxLength: 120
              Date:
                title: 'Date of application '
                type: string
                format: date
          additionalProperties: {}
        form_ui_schema:
          description: The UI Schema of the form for front-end rendering
          example:
          - type: field
            definition: /properties/Title
          - type: field
            definition: /properties/Description
          - type: field
            definition: /properties/ApplicationNumber
          - type: field
            definition: /properties/Date
        form_instruction:
          description: The instruction file for the form, if available
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/FormInstructionSchema'
          - type: 'null'
        form_rule_schema:
          type:
          - object
          - 'null'
          description: The rule schema for the form
          additionalProperties: {}
        json_to_xml_schema:
          type:
          - object
          - 'null'
          description: The JSON to XML schema mapping configuration for the form
          additionalProperties: {}
        form_type:
          description: The type of the form
          example:
          - SF424
          enum:
          - SF424
          - SF424A
          - SF424B
          - SF424D
          - SFLLL
          - ProjectNarrativeAttachment
          - BudgetNarrativeAttachment
          - OtherNarrativeAttachment
          - ProjectAbstractSummary
          - ProjectAbstract
          - CD511
          - SupplementaryNEHCoverSheet
          - GGLobbyingForm
          - EPAForm4700-4
          - EPAKeyContacts
          - AttachmentForm
          - ProjectPerformanceSiteLocation
          type:
          - string
          - 'null'
          - 'null'
        sgg_version:
          type:
          - string
          - 'null'
          description: The SGG version of the form
          example: '1.0'
        is_deprecated:
          type:
          - boolean
          - 'null'
          description: Whether the form is deprecated
          example: false
        created_at:
          type: string
          format: date-time
          description: The timestamp when the form was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the form was last updated
    CompetitionFormAlphaSchema:
      type: object
      properties:
        is_required:
          type: boolean
          description: Whether the form is required for all applications to the competition
        form:
          description: The form template information for this competition
          type:
          - object
          $ref: '#/components/schemas/FormAlphaSchema'
    OpportunityListFilterSchema:
      type: object
      properties:
        award_recommendation_ready:
          description: Filter for opportunities ready for award recommendations. Returns only non-draft Simpler Grants opportunities with application submissions and no existing award recommendations.
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationReadySchema'
    FormInstructionSchema:
      type: object
      properties:
        form_instruction_id:
          type: string
          format: uuid
          description: The UUID of the form instruction
          example: 123e4567-e89b-12d3-a456-426614174000
        file_name:
          type: string
          description: The name of the form instruction file
          example: instructions.pdf
        download_path:
          type: string
          description: The download URL for the form instruction file
        created_at:
          type: string
          format: date-time
          description: The timestamp when the form instruction was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the form instruction was last updated
    OpportunityCreateRequestSchema:
      type: object
      properties:
        opportunity_number:
          type: string
          maxLength: 40
          description: The funding opportunity number (must be unique)
          example: ABC-2026-001
        opportunity_title:
          type: string
          maxLength: 255
          description: The title of the opportunity
          example: Research Grant for Climate Innovation
        agency_id:
          type: string
          format: uuid
          description: The UUID of the agency that will own this opportunity
          example: 123e4567-e89b-12d3-a456-426614174000
        category:
          description: The opportunity category
          enum:
          - discretionary
          - mandatory
          - continuation
          - earmark
          - other
          type:
          - string
        category_explanation:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Explanation of the category (required when category is 'other')
          example: Competitive research grant
        assistance_listing_number:
          type: string
          maxLength: 6
          description: The Assistance Listing Number
          example: 12.ABC
      required:
      - agency_id
      - assistance_listing_number
      - category
      - opportunity_number
      - opportunity_title
    AwardRecommendationReadySchema:
      type: object
      properties:
        one_of:
          type:
          - array
          - 'null'
          items:
            type: boolean
            example: true
    ValidationIssueSchema:
      type: object
      properties:
        type:
          type: string
          description: The type of error
          example: invalid
        message:
          type: string
          description: The message to return
          example: Not a valid string.
        field:
          type: string
          description: The field that failed
          example: summary.summary_description
        value:
          type: string
          description: The value that failed
          example: invalid string
    OpportunityAttachmentV1Schema:
      type: object
      properties:
        download_path:
          type: string
          description: The file's download path
        file_size_bytes:
          type: integer
          description: The size of the file in bytes
          example: 1024
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        opportunity_attachment_id:
          type: string
          format: uuid
          description: The unique ID of the attachment
          example: 123e4567-e89b-12d3-a456-426614174000
        mime_type:
          type: string
          description: The MIME type of the attachment
          example: application/pdf
        file_name:
          type: string
          description: The name of the attachment file
          example: my_NOFO.pdf
    

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hhs/refs/heads/main/openapi/hhs-opportunity-v1-for-grantors-api-openapi.yml
HHS (US Department of Health and Human Services) Opportunity v1 - for Grantors API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
