openapi: 3.2.0
info:
  title: Search Assistance Listings API
  version: 1.0.0
  description: Search and retrieve Assistance Listings with detailed program information.
servers:
- url: https://api.sam.gov
tags:
- name: Assistance Listings
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'
      tags:
      - Assistance Listings
components:
  schemas:
    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
    AssistanceListingsResponse:
      type: object
      properties:
        totalRecords:
          type: integer
        pageSize:
          type: integer
        pageNumber:
          type: integer
        totalPages:
          type: integer
        assistanceListingsData:
          type: array
          items:
            $ref: '#/components/schemas/AssistanceListing'
    AccountIdentification:
      type: object
      properties:
        code:
          type: string
        description:
          type: string
    RangeAndAverageAssistance:
      type: object
      properties:
        fiscalYear:
          type: integer
        minimumAwardAmount:
          type: number
        maximumAwardAmount:
          type: number
        averageAwardAmount:
          type: number
    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'
    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'
    ExternalReference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        URL:
          type: string
          format: uri
        description:
          type: string
    Authorizations:
      type: object
      properties:
        description:
          type: string
        list:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
    DateRangeDescription:
      type: object
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
        description:
          type: string
    CodeNamePair:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
    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'
    ComplianceReport:
      type: object
      properties:
        code:
          type: string
        frequency:
          type: string
        description:
          type: string
    FiscalDescription:
      type: object
      properties:
        fiscalYear:
          type: integer
        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'
    Accomplishments:
      type: object
      properties:
        isApplicable:
          type: boolean
        list:
          type: array
          items:
            $ref: '#/components/schemas/FiscalDescription'
    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'
    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
    ObligationValue:
      type: object
      properties:
        year:
          type: integer
        actual:
          type: number
        estimate:
          type: number
    IntervalDescription:
      type: object
      properties:
        interval:
          type: string
        description:
          type: string
    TypedDescription:
      type: object
      properties:
        types:
          type: array
          items:
            $ref: '#/components/schemas/CodeNamePair'
        description:
          type: string
    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
    FundedProject:
      type: object
      properties:
        fiscalYear:
          type: integer
        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'
    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'
    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