HHS (US Department of Health and Human Services) Award Recommendation Alpha API

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 Award Recommendation Alpha API
  version: v0
servers: .
tags:
- name: Award Recommendation Alpha
paths:
  /alpha/award-recommendations:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationGetResponseSchema'
          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
      tags:
      - Award Recommendation Alpha
      summary: Create Award Recommendation
      description: Create a new award recommendation for an opportunity, linking application submissions and audit data.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationCreateRequestSchema'
      security:
      - ApiJwtAuth: &id001 []
      - ApiUserKeyAuth: *id001
  /alpha/award-recommendations/list:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationListResponseSchema'
          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
      tags:
      - Award Recommendation Alpha
      summary: List Award Recommendations
      description: Get paginated list of award recommendations filtered by agency.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationListRequestSchema'
      security:
      - ApiJwtAuth: &id002 []
      - ApiUserKeyAuth: *id002
  /alpha/award-recommendations/{award_recommendation_id}:
    get:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationGetResponseSchema'
          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
      tags:
      - Award Recommendation Alpha
      summary: Get Award Recommendation
      description: Retrieve an award recommendation by ID, including opportunity details, attachments, and reviews.
      security:
      - ApiJwtAuth: &id003 []
      - ApiUserKeyAuth: *id003
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationGetResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: Update Award Recommendation
      description: Update an existing award recommendation with new values for fields.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id004 []
      - ApiUserKeyAuth: *id004
  /alpha/award-recommendations/{award_recommendation_id}/risks:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: Create Award Recommendation Risk
      description: Create a risk for an award recommendation, linking it to application submissions.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationRiskRequestSchema'
      security:
      - ApiJwtAuth: &id005 []
      - ApiUserKeyAuth: *id005
  /alpha/award-recommendations/{award_recommendation_id}/risks/list:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskListResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: List Award Recommendation Risks
      description: Get paginated list of risks for an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationRiskListRequestSchema'
      security:
      - ApiJwtAuth: &id006 []
      - ApiUserKeyAuth: *id006
  /alpha/award-recommendations/{award_recommendation_id}/audit_history:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationAuditResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: List Award Recommendation Audit History
      description: Get paginated audit history for an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationAuditRequestSchema'
      security:
      - ApiJwtAuth: &id007 []
      - ApiUserKeyAuth: *id007
  /alpha/award-recommendations/{award_recommendation_id}/submissions/list:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationSubmissionListResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: List Award Recommendation Submissions
      description: Get paginated list of application submissions for an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationSubmissionListRequestSchema'
      security:
      - ApiJwtAuth: &id008 []
      - ApiUserKeyAuth: *id008
  /alpha/award-recommendations/{award_recommendation_id}/submission-details:
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationSubmissionDetailsBatchUpdateResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: Batch Update Award Recommendation Submission Details
      description: Update multiple submission details for an award recommendation in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationSubmissionDetailsBatchUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id009 []
      - ApiUserKeyAuth: *id009
  /alpha/award-recommendations/{award_recommendation_id}/risks/{award_recommendation_risk_id}:
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_risk_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: Update Award Recommendation Risk
      description: Update a risk on an award recommendation, including linked application submissions.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationRiskRequestSchema'
      security:
      - ApiJwtAuth: &id010 []
      - ApiUserKeyAuth: *id010
    delete:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_risk_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskDeleteResponseSchema'
          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
      tags:
      - Award Recommendation Alpha
      summary: Delete Award Recommendation Risk
      description: Soft delete a risk for an award recommendation.
      security:
      - ApiJwtAuth: &id011 []
      - ApiUserKeyAuth: *id011
  /alpha/award-recommendations/{award_recommendation_id}/reviews/{award_recommendation_review_id}:
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_review_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationReviewUpdateResponseSchema'
          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:
      - Award Recommendation Alpha
      summary: Update Award Recommendation Review
      description: Update a review on an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationReviewUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id012 []
      - ApiUserKeyAuth: *id012
  /alpha/award-recommendations/{award_recommendation_id}/attachments/{award_recommendation_attachment_id}:
    delete:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_attachment_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationAttachmentDeleteResponseSchema'
          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
      tags:
      - Award Recommendation Alpha
      summary: Delete Award Recommendation Attachment
      description: Soft delete an attachment for an award recommendation.
      security:
      - ApiJwtAuth: &id013 []
      - ApiUserKeyAuth: *id013
components:
  schemas:
    SimpleUserSchema:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: ID of the user
          example: 123e4567-e89b-12d3-a456-426614174000
        email:
          type: string
          description: Email address of the user
          example: example@example.com
        first_name:
          type:
          - string
          - 'null'
          description: Users first name
          example: John
        last_name:
          type:
          - string
          - 'null'
          description: Users last name
          example: Smith
    AwardRecSubmissionTypeFilterSchema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - recommended_for_funding
            - recommended_without_funding
            - not_recommended
            type:
            - string
    AwardRecSubmissionPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: application_submission_number
            sort_direction: ascending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderAwardRecSubmissionPaginationSchema'
        page_size:
          type: integer
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
      required:
      - page_offset
      - page_size
    SortOrderAwardRecommendationListPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - created_at
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
      required:
      - order_by
      - sort_direction
    AwardRecommendationRiskListResponseSchema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: The list of award recommendation risks
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationRiskResponseDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationReviewSchema:
      type: object
      properties:
        award_recommendation_review_id:
          type: string
          format: uuid
          description: The review's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_review_type:
          description: The type of the review
          enum:
          - merit_review
          - application_budget_review
          - programmatic_review
          - business_and_risk_review
          type:
          - string
        is_reviewed:
          type: boolean
          description: Whether the review has been completed
    AwardRecommendationRiskDeleteResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          example: null
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationAttachmentDeleteResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          example: null
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationSubmissionDetailSchema:
      type: object
      properties:
        recommended_amount:
          type:
          - number
          - 'null'
          description: The recommended funding amount
          example: '200000.00'
        scoring_comment:
          type:
          - string
          - 'null'
          description: Comments from the scoring process
        general_comment:
          type:
          - string
          - 'null'
          description: General comments about the submission
        award_recommendation_type:
          description: The recommendation type for this submission
          enum:
          - recommended_for_funding
          - recommended_without_funding
          - not_recommended
          type:
          - string
          - 'null'
          - 'null'
        has_exception:
          type: boolean
          description: Whether the submission has an exception
        exception_detail:
          type:
          - string
          - 'null'
          description: Details about the exception, if any
    AwardRecommendationBaseSchema:
      type: object
      properties:
        award_recommendation_id:
          type: string
          format: uuid
          description: The award recommendation's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_number:
          type: string
          description: The generated award recommendation number
          example: AR-26-0001
        award_recommendation_status:
          description: The status of the award recommendation
          enum:
          - draft
          - in_review
          - approved
          type:
          - string
        award_selection_method:
          description: The method used to select the award
          enum:
          - merit_review_ranking_only
          - merit_review_ranking_with_other_factors
          - formula
          - single_source
          - sole_source
          - other
          type:
          - string
          - 'null'
          - 'null'
        additional_info:
          type:
          - string
          - 'null'
          description: Additional info about the opportunity
          example: Program office requests expedited processing due to deadline in September.
        selection_method_detail:
          type:
          - string
          - 'null'
          description: Additional detail about the selection method
          example: Selection factors included technical merit, past performance, and cost.
        funding_strategy:
          type:
          - string
          - 'null'
          description: Funding strategy for award recommendations
          example: Full funding for top 10 applications, partial funding for next 15 based on available budget.
        other_key_information:
          type:
          - string
          - 'null'
          description: Other key information
          example: This opportunity aligns with the agency's rural access initiative and requires interagency coordination.
        review_workflow_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The workflow ID for the review process
          example: 123e4567-e89b-12d3-a456-426614174000
        opportunity:
          description: The associated opportunity
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationOpportunitySchema'
        award_recommendation_reviews:
          type: array
          description: Reviews associated with the award recommendation
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationReviewSchema'
    AwardRecommendationSubmissionDetailUpdateSchema:
      type: object
      properties:
        recommended_amount:
          type:
          - number
          - 'null'
          description: The recommended funding amount
          example: '200000.00'
        scoring_comment:
          type:
          - string
          - 'null'
          description: Comments from the scoring process
          example: Strong technical approach with clear methodology. Budget well-justified and aligned with project goals.
        general_comment:
          type:
          - string
          - 'null'
          description: General comments about the submission
          example: Applicant has demonstrated successful implementation of similar projects in the past. Team qualifications exceed requirements.
        award_recommendation_type:
          description: The recommendation type for this submission
          enum:
          - recommended_for_funding
          - recommended_without_funding
          - not_recommended
          type:
          - string
          - 'null'
          - 'null'
        has_exception:
          type: boolean
          description: Whether the submission has an exception
        exception_detail:
          type:
          - string
          - 'null'
          description: Details about the exception, if any
          example: Budget exceeds guidelines by 12%. Recommend partial funding with revised scope focusing on core deliverables.
    AwardRecommendationApplicationSchema:
      type: object
      properties:
        application_id:
          type: string
          format: uuid
          description: The application ID
          example: 123e4567-e89b-12d3-a456-426614174000
        competition_id:
          type: string
          format: uuid
          description: The competition ID
          example: 123e4567-e89b-12d3-a456-426614174000
        organization:
          description: The organization that submitted the application
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationOrganizationSchema'
          - type: 'null'
    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
    AwardRecommendationAuditAttachmentSchema:
      type: object
      properties:
        award_recommendation_attachment_id:
          type: string
          format: uuid
          description: The attachment's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        file_name:
          type: string
          description: The file name of the attachment
          example: my_example.pdf
        award_recommendation_attachment_type:
          description: The type of the attachment
          enum:
          - standard_terms
          - standard_conditions
          - program_terms
          - program_conditions
          - other
          type:
          - string
        is_deleted:
          

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hhs/refs/heads/main/openapi/hhs-award-recommendation-alpha-api-openapi.yml