openapi: 3.0.3
info:
  title: Assistance Listings Search API
  version: 1.0.0
  description: Search and retrieve Assistance Listings with detailed program information.

servers:
  - url: https://api.sam.gov

paths:
  /assistance-listings/v1/search:
    get:
      summary: Search Assistance Listings
      operationId: searchAssistanceListings
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
        - name: pageNumber
          in: query
          schema:
            type: integer
            default: 1
        - name: status
          in: query
          schema:
            type: string
            enum: [Active, Inactive, All]
            default: Active
        - name: assistanceListingId
          in: query
          schema:
            type: string
        - name: publishedDateFrom
          in: query
          schema:
            type: string
            format: date-time
        - name: publishedDateTo
          in: query
          schema:
            type: string
            format: date-time
        - name: assistanceTypes
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: beneficiaryTypes
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: applicantTypes
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: organizationCodes
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: organizationLevel
          in: query
          schema:
            type: array
            items:
              type: string
              enum: [Department, Agency, Office]
            default: [Department]
        - name: coreBasedStatisticalDelineations
          in: query
          schema:
            type: string
            enum: [Y, N]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistanceListingsResponse'

components:
  schemas:

    AssistanceListingsResponse:
      type: object
      properties:
        totalRecords:
          type: integer
        pageSize:
          type: integer
        pageNumber:
          type: integer
        totalPages:
          type: integer
        assistanceListingsData:
          type: array
          items:
            $ref: '#/components/schemas/AssistanceListing'

    AssistanceListing:
      type: object
      properties:
        version:
          type: string
        status:
          type: string
          enum: [ Active, Inactive ]
        fiscalYear:
          type: integer
        publishedDate:
          type: string
          format: date-time
        assistanceListingId:
          type: string
        title:
          type: string
        popularLongName:
          type: string
        popularShortName:
          type: string
        relatedFederalAssistance:
          type: array
          items:
            type: string
        federalOrganization:
          $ref: '#/components/schemas/FederalOrganization'
        programWebPage:
          type: string
          format: uri
        overview:
          $ref: '#/components/schemas/Overview'
        authorizations:
          $ref: '#/components/schemas/Authorizations'
        financialInformation:
          $ref: '#/components/schemas/FinancialInformation'
        criteriaForApplying:
          $ref: '#/components/schemas/CriteriaForApplying'
        assistanceApplication:
          $ref: '#/components/schemas/AssistanceApplication'
        compliance:
          $ref: '#/components/schemas/Compliance'
        contacts:
          $ref: '#/components/schemas/Contacts'

    FederalOrganization:
      type: object
      properties:
        department:
          type: string
        agency:
          type: string
        office:
          type: string

    Overview:
      type: object
      properties:
        objective:
          type: string
        assistanceListingDescription:
          type: string
        fundedProjectsList:
          type: object
          properties:
            isApplicable:
              type: boolean
            list:
              type: array
              items:
                $ref: '#/components/schemas/FundedProject'
        functionalCodes:
          type: array
          items:
            $ref: '#/components/schemas/CodeNamePair'
        missionSubCategories:
          type: object
          properties:
            Primary:
              $ref: '#/components/schemas/CodeNamePair'
            Other:
              type: array
              items:
                $ref: '#/components/schemas/CodeNamePair'
        subjectTerms:
          type: array
          items:
            $ref: '#/components/schemas/CodeNamePair'

    FundedProject:
      type: object
      properties:
        fiscalYear:
          type: integer
        description:
          type: string

    CodeNamePair:
      type: object
      properties:
        code:
          type: string
        name:
          type: string

    Authorizations:
      type: object
      properties:
        description:
          type: string
        list:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'

    Authorization:
      type: object
      properties:
        parentAuthorizationId:
          type: string
          format: uuid
        authorizationTypes:
          type: object
          properties:
            act:
              type: boolean
            executiveOrder:
              type: boolean
            publicLaw:
              type: boolean
            statute:
              type: boolean
            USC:
              type: boolean
        act:
          $ref: '#/components/schemas/LegalReference'
        executiveOrder:
          $ref: '#/components/schemas/LegalReference'
        publicLaw:
          type: object
          properties:
            congressCode:
              type: string
            number:
              type: string
            description:
              type: string
        statute:
          type: object
          properties:
            volume:
              type: string
            page:
              type: string
            description:
              type: string
        USC:
          type: object
          properties:
            title:
              type: string
            section:
              type: string
            description:
              type: string

    LegalReference:
      type: object
      properties:
        title:
          type: string
        part:
          type: string
        section:
          type: string
        description:
          type: string

    FinancialInformation:
      type: object
      properties:
        isFundedCurrentFY:
          type: boolean
        additionalInformation:
          type: string
        obligations:
          type: array
          items:
            $ref: '#/components/schemas/Obligation'
        rangeAndAverageAssistance:
          type: array
          items:
            $ref: '#/components/schemas/RangeAndAverageAssistance'
        accomplishments:
          $ref: '#/components/schemas/Accomplishments'
        accountsIdentificationList:
          type: array
          items:
            $ref: '#/components/schemas/AccountIdentification'

    Obligation:
      type: object
      properties:
        isRecoveryAct:
          type: boolean
        assistanceType:
          $ref: '#/components/schemas/CodeNamePair'
        awardAmountBasis:
          type: array
          items:
            $ref: '#/components/schemas/CodeNamePair'
        awardRecipientBasis:
          type: array
          items:
            $ref: '#/components/schemas/CodeNamePair'
        values:
          type: array
          items:
            $ref: '#/components/schemas/ObligationValue'

    ObligationValue:
      type: object
      properties:
        year:
          type: integer
        actual:
          type: number
        estimate:
          type: number

    RangeAndAverageAssistance:
      type: object
      properties:
        fiscalYear:
          type: integer
        minimumAwardAmount:
          type: number
        maximumAwardAmount:
          type: number
        averageAwardAmount:
          type: number

    Accomplishments:
      type: object
      properties:
        isApplicable:
          type: boolean
        list:
          type: array
          items:
            $ref: '#/components/schemas/FiscalDescription'

    FiscalDescription:
      type: object
      properties:
        fiscalYear:
          type: integer
        description:
          type: string

    AccountIdentification:
      type: object
      properties:
        code:
          type: string
        description:
          type: string

    CriteriaForApplying:
      type: object
      properties:
        documentation:
          type: object
          properties:
            isApplicable:
              type: boolean
            description:
              type: array
              items:
                type: string
        applicant:
          $ref: '#/components/schemas/TypedDescription'
        beneficiary:
          type: object
          properties:
            isSameAsApplicant:
              type: boolean
            types:
              type: array
              items:
                $ref: '#/components/schemas/CodeNamePair'
            description:
              type: string
        assistanceUsage:
          $ref: '#/components/schemas/TypedDescription'
        assistanceRestriction:
          $ref: '#/components/schemas/TypedDescription'

    TypedDescription:
      type: object
      properties:
        types:
          type: array
          items:
            $ref: '#/components/schemas/CodeNamePair'
        description:
          type: string

    AssistanceApplication:
      type: object
      properties:
        deadlines:
          type: object
          properties:
            value:
              type: string
            list:
              type: array
              items:
                $ref: '#/components/schemas/DateRangeDescription'
            description:
              type: string
        preApplicationCoordination:
          type: object
          properties:
            environmentalImpact:
              type: object
              properties:
                reports:
                  type: array
                  items:
                    type: object
                    properties:
                      reportCode:
                        type: string
                      isSelected:
                        type: boolean
            description:
              type: string
        applicationProcedure:
          type: object
          properties:
            opportunityPostedLocation:
              type: string
            opportunityPostedURL:
              type: string
              format: uri
            location:
              type: string
            URL:
              type: string
              format: uri
            description:
              type: string
        selectionCriteria:
          type: object
          properties:
            isApplicable:
              type: boolean
            description:
              type: string
        awardProcedure:
          type: object
          properties:
            description:
              type: string
        payments:
          type: object
          properties:
            list:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
        approval:
          $ref: '#/components/schemas/IntervalDescription'
        appeal:
          $ref: '#/components/schemas/IntervalDescription'
        renewal:
          $ref: '#/components/schemas/IntervalDescription'

    DateRangeDescription:
      type: object
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
        description:
          type: string

    Payment:
      type: object
      properties:
        fundingDate:
          type: string
          format: date
        type:
          type: string
        frequency:
          type: string
        frequencyDescription:
          type: string
        spendingPeriodType:
          type: string
        spendingPeriod:
          type: integer
        spendingPeriodDescription:
          type: string

    IntervalDescription:
      type: object
      properties:
        interval:
          type: string
        description:
          type: string

    Compliance:
      type: object
      properties:
        CFR200Requirements:
          type: object
          properties:
            questions:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  isSelected:
                    type: boolean
            description:
              type: string
        reports:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceReport'
        audit:
          type: object
          properties:
            isApplicable:
              type: boolean
            frequency:
              type: string
            description:
              type: string
        records:
          type: object
          properties:
            retentionPeriodType:
              type: string
            retentionPeriod:
              type: integer
            description:
              type: string
        documents:
          type: object
          properties:
            isApplicable:
              type: boolean
            description:
              type: string
        additionalRequirements:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        guidelinesAndInformation:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        formulaAndMatching:
          type: object
          properties:
            isApplicable:
              type: boolean
            types:
              type: object
              properties:
                formula:
                  type: boolean
                matching:
                  type: boolean
                moe:
                  type: boolean
            formula:
              $ref: '#/components/schemas/LegalReference'
            matching:
              type: object
              properties:
                requirementFlag:
                  type: string
                percent:
                  type: string
                description:
                  type: string
            moe:
              type: object
              properties:
                description:
                  type: string

    ComplianceReport:
      type: object
      properties:
        code:
          type: string
        frequency:
          type: string
        description:
          type: string

    ExternalReference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        URL:
          type: string
          format: uri
        description:
          type: string

    Contacts:
      type: object
      properties:
        local:
          type: object
          properties:
            flag:
              type: string
            officeLocationURL:
              type: string
              format: uri
            description:
              type: string
        headquarters:
          type: array
          items:
            $ref: '#/components/schemas/HeadquartersContact'

    HeadquartersContact:
      type: object
      properties:
        contactId:
          type: string
          format: uuid
        title:
          type: string
        fullName:
          type: string
        email:
          type: string
        phone:
          type: string
        fax:
          type: string
        streetAddress:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
        subdivisionCode:
          type: string
        subdivisionName:
          type: string
