HHS (US Department of Health and Human Services) Organization v1 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 Organization v1 API
  version: v0
servers: .
tags:
- name: Organization v1
paths:
  /v1/organizations/{organization_id}:
    get:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationGetResponseSchema'
          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:
      - Organization v1
      summary: Get organization information by ID
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/users:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationUsersResponseSchema'
          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:
      - Organization v1
      summary: Get paginated list of users in an organization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUsersListRequestSchema'
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/roles/list:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationListRolesResponseSchema'
          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:
      - Organization v1
      summary: List organization roles
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/invitations:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCreateInvitationResponseSchema'
          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
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Organization v1
      summary: Create an invitation for a new organization member
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationCreateInvitationRequestSchema'
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/legacy-users:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyUsersListResponseSchema'
          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
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Organization v1
      summary: List legacy users that can be invited to the organization.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegacyUsersListRequestSchema'
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/invitations/list:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitationListResponseSchema'
          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
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Organization v1
      summary: List organization invitations with filtering
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInvitationListRequestSchema'
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/legacy-users/ignore:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationIgnoreLegacyUserResponseSchema'
          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
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Organization v1
      summary: Organization Ignore Legacy User
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationIgnoreLegacyUserRequestSchema'
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/saved-opportunities:
    post:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSaveOpportunityResponseSchema'
          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:
      - Organization v1
      summary: Save an opportunity for an organization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationSaveOpportunityRequestSchema'
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/users/{user_id}:
    put:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationUpdateUserRolesResponseSchema'
          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:
      - Organization v1
      summary: Update roles for an organization user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUpdateUserRolesRequestSchema'
      security:
      - ApiJwtAuth: []
    delete:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRemoveUserResponseSchema'
          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:
      - Organization v1
      summary: Remove a user from an organization
      security:
      - ApiJwtAuth: []
  /v1/organizations/{organization_id}/saved-opportunities/{opportunity_id}:
    delete:
      parameters:
      - in: path
        name: organization_id
        schema:
          type: string
        required: true
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDeleteSavedOpportunityResponseSchema'
          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:
      - Organization v1
      summary: Delete a saved opportunity for an organization
      security:
      - ApiJwtAuth: []
components:
  schemas:
    OrganizationInvitationListRequestSchema:
      type: object
      properties:
        filters:
          description: Filters to apply to the invitation list
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/OrganizationInvitationFilterSchema'
          - type: 'null'
        pagination:
          description: 'Pagination parameters for organization invitation list (default sort: invitee_email ascending)'
          type:
          - object
          $ref: '#/components/schemas/OrganizationInvitationListPaginationSchema'
    OrganizationUserSchema:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: User unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        email:
          type:
          - string
          - 'null'
          description: User email from login.gov
          example: user@example.com
        roles:
          type: array
          description: User roles in this organization
          items:
            type:
            - object
            $ref: '#/components/schemas/RoleSchema1'
        first_name:
          type:
          - string
          - 'null'
          description: User first name
          example: John
        last_name:
          type:
          - string
          - 'null'
          description: User last name
          example: Smith
        is_ebiz_poc:
          type: boolean
          description: Whether the user is the EBiz POC (Electronic Business Point of Contact) for the organization in SAM.gov
          example: false
    OrganizationSaveOpportunityResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: No data returned
          example: {}
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    OrganizationInvitationDataSchema:
      type: object
      properties:
        organization_invitation_id:
          type: string
          format: uuid
          description: Invitation unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        invitee_email:
          type: string
          description: Email address of the invitee
          example: user@example.com
        status:
          type: string
          description: Current status of the invitation
          example: pending
        created_at:
          type: string
          format: date-time
          description: When the invitation was created
          example: '2024-01-08T10:30:00Z'
        expires_at:
          type: string
          format: date-time
          description: When the invitation expires
          example: '2024-01-15T10:30:00Z'
        accepted_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the invitation was accepted
          example: '2024-01-10T14:20:00Z'
        rejected_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the invitation was rejected
          example: null
        inviter_user:
          description: Information about the user who sent the invitation
          type:
          - object
          $ref: '#/components/schemas/InviterDataSchema'
        invitee_user:
          description: Information about the invited user (null if not registered)
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/InviteeDataSchema'
          - type: 'null'
        roles:
          type: array
          description: Roles that will be assigned when invitation is accepted
          items:
            type:
            - object
            $ref: '#/components/schemas/RoleSchema1'
    OrganizationUsersResponseSchema:
      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: List of organization members
          items:
            type:
            - object
            $ref: '#/components/schemas/OrganizationUserSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    InviterDataSchema:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: Inviter user unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        email:
          type: string
          description: Inviter email address
          example: admin@org.com
        first_name:
          type:
          - string
          - 'null'
          description: Inviter first name
          example: John
        last_name:
          type:
          - string
          - 'null'
          description: Inviter last name
          example: Doe
    InviteeDataSchema:
      type: object
      properties:
        user_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Invitee user unique identifier (null if not registered)
          example: 123e4567-e89b-12d3-a456-426614174000
        email:
          type:
          - string
          - 'null'
          description: Invitee email address
          example: user@example.com
        first_name:
          type:
          - string
          - 'null'
          description: Invitee first name
          example: Jane
        last_name:
          type:
          - string
          - 'null'
          description: Invitee last name
          example: Smith
    InvitationStatusFilterSchema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            example: pending
            enum:
            - accepted
            - rejected
            - expired
            - pending
            type:
            - string
    OrganizationUsersPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: email
            sort_direction: ascending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderOrganizationUsersPaginationSchema'
        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
    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
    OrganizationCreateInvitationResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: Created invitation information
          type:
          - object
          $ref: '#/components/schemas/OrganizationInvitationResponseSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    RoleSchema1:
      type: object
      properties:
        role_id:
          type: string
          format: uuid
          description: Role unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        role_name:
          type: string
          description: Role name
          example: Organization Admin
        privileges:
          type: array
          description: List of privileges for this role
          example:
          - - manage_org_members
          items:
            enum:
            - manage_org_members
            - manage_org_admin_members
            - view_org_membership
            - start_application
            - list_application
            - view_application
            - modify_application
            - submit_application
            - update_form
            - manage_agency_members
            - get_submitted_applications
            - legacy_agency_viewer
            - legacy_agency_grant_retriever
            - legacy_agency_assigner
            - manage_internal_roles
            - manage_competition
            - read_test_user_token
            - view_opportunity
            - create_opportunity
            - update_opportunity
            - publish_opportunity
            - internal_workflow_access
            - view_org_saved_opportunities
            - modify_org_saved_opportunities
            - internal_workflow_event_send
            - view_award_recommendation
            - create_award_recommendation
            - update_award_recommendation
            - submit_award_recommendation
            - program_officer_approval
            - budget_officer_approval
            - internal_s3_scan
            type:
            - string
    OrganizationGetResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: Organization information
          type:
          - object
          $ref: '#/components/schemas/OrganizationDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    OrganizationCreateInvitationRequestSchema:
      type: object
      properties:
        invitee_email:
          type: string
          description: Email address of the user to invite
          example: user@example.com
        role_ids:
          type: array
          minItems: 1
          description: List of role IDs to assign to the invited user
          example:
          - 123e4567-e89b-12d3-a456-426614174000
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
      required:
      - invitee_email
      - role_ids
    OrganizationUsersListRequestSchema:
      type: object
      properties:
        pagination:
          description: 'Pagination parameters for organization users list (default page size: 10, default sort: email ascending)'
          type:
          - object
          $ref: '#/components/schemas/OrganizationUsersPaginationSchema'
      required:
      - pagination
    OrganizationInvitationListPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: invitee_email
            sort_direction: ascending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderOrganizationInvitationListPaginationSchema'
        page_size:
          type: integer
          default: 25
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          default: 1
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
    OrganizationIgnoreLegacyUserResponseSchema:
      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
    PaginationInfoSchema:
      type: object
      properties:
        page_offset:
          type: integer
          description: The page number that was fetched
          example: 1
        page_size:
          type: integer
          description: The size of the page fetched
          example: 25
        total_records:
          type: integer
          description: The total number of records fetchable
          example: 42
        total_pages:
          type: integer
          description: The total number of pages that can be fetched
          example: 2
        sort_order:
          type: array
          description: The sort order passed in originally
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderSchema'
    OrganizationUpdateUserRolesRequestSchema:
      type: object
      properties:
        role_ids:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
    OrganizationRemoveUserResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: No data returned on successful removal
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    SortOrderOrganizationInvitationListPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - invitee_email
          - created_at
          - responded_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
    OrganizationIgnoreLegacyUserRequestSchema:
      type: object
      properties:
        email:
          type: string
          description: Email address of the legacy user to ignore
      required:
      - email
    LegacyUsersListResponseSchema:
      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: List of legacy users
          items:
            type:
            - object
            $ref: '#/components/schemas/LegacyUserDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    OrganizationDataSchema:
      type: object
      properties:
        organization_id:
          type: string
          format: uuid
          description: Organization unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        sam_gov_entity:
          description: SAM.gov entity information
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/SamGovEntityResponseSchema'
          - type: 'null'
    OrganizationInvitationFilterSchema:
      type: object
      properties:
        status:
          description: Filter invitations by status
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/InvitationStatusFilterSchema'
          - type: 'null'
    LegacyUserStatusFilterSchema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hhs/refs/heads/main/openapi/hhs-organization-v1-api-openapi.yml