openapi: 3.1.0
info:
  title: ATTOM Property API
  description: |
    ATTOM Property API delivers comprehensive property intelligence for more than
    160 million U.S. properties. Resources include property characteristics, ownership
    and mortgage records, assessed value and tax history, sales history, AVM valuations
    (current and historical), rental AVM, home equity, school assignments, transportation
    noise scoring, pre-foreclosure status, and building permits. Most resources are
    offered in both `snapshot` and `detail` packages and accept any of: AttomID,
    address (single string), address1 + address2, or geographic radius / bounding-box
    parameters.
  version: v1.0.0
  contact:
    name: ATTOM Data Customer Care
    email: datacustomercare@attomdata.com
    url: https://api.developer.attomdata.com/
  license:
    name: ATTOM Data Terms of Use
    url: https://www.attomdata.com/terms-of-use/
servers:
  - url: https://api.gateway.attomdata.com/propertyapi/v1.0.0
    description: ATTOM Property API Production Gateway
security:
  - ApiKeyAuth: []
tags:
  - name: Property
    description: Property characteristics, ownership, mortgage, and address resolution.
  - name: Assessment
    description: Assessed value, tax liability, and assessment history.
  - name: AVM
    description: Automated Valuation Model — current AVM, AVM history, and rental AVM.
  - name: Sale
    description: Sales transactions, sales history, and comparable sales.
  - name: All Events
    description: Combined assessment, AVM, and sales-transaction events.
  - name: Building Permits
    description: Building permit records associated with a property.
  - name: School
    description: School assignments and attendance-zone associations.
  - name: Home Equity
    description: Estimated home equity calculations.
  - name: Pre-Foreclosure
    description: Pre-foreclosure status and notice records.
  - name: Sales Trends
    description: Aggregated sales trends for a geography.
paths:
  /property/address:
    get:
      summary: Search Properties By Address
      description: Search properties matching a postal address.
      operationId: searchPropertyAddress
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AddressQuery'
        - $ref: '#/components/parameters/Address1Query'
        - $ref: '#/components/parameters/Address2Query'
        - $ref: '#/components/parameters/PageQuery'
        - $ref: '#/components/parameters/PageSizeQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyListResponse' }
        '400': { $ref: '#/components/responses/ErrorResponse' }
        '401': { $ref: '#/components/responses/ErrorResponse' }
        '429': { $ref: '#/components/responses/ErrorResponse' }
  /property/snapshot:
    get:
      summary: Get Property Snapshot
      description: Return a summary snapshot of property attributes for the matched property.
      operationId: getPropertySnapshot
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
        - $ref: '#/components/parameters/Address1Query'
        - $ref: '#/components/parameters/Address2Query'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
        '400': { $ref: '#/components/responses/ErrorResponse' }
  /property/detail:
    get:
      summary: Get Property Detail
      description: Return a detailed property record including building, lot, area, and identifier blocks.
      operationId: getPropertyDetail
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
        - $ref: '#/components/parameters/Address1Query'
        - $ref: '#/components/parameters/Address2Query'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/detailwithschools:
    get:
      summary: Get Property Detail With Schools
      description: Property detail plus assigned schools and school district attributes.
      operationId: getPropertyDetailWithSchools
      tags: [Property, School]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/detailmortgage:
    get:
      summary: Get Property Detail With Mortgage
      description: Property detail enriched with current and historical mortgage records.
      operationId: getPropertyDetailMortgage
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/detailowner:
    get:
      summary: Get Property Detail With Owner
      description: Property detail enriched with owner identity, mailing address, and ownership classification.
      operationId: getPropertyDetailOwner
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/detailmortgageowner:
    get:
      summary: Get Property Detail With Mortgage And Owner
      description: Property detail enriched with both mortgage and owner records.
      operationId: getPropertyDetailMortgageOwner
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/basicprofile:
    get:
      summary: Get Property Basic Profile
      description: Compact property profile (characteristics, last sale, assessed value).
      operationId: getPropertyBasicProfile
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/basichistory:
    get:
      summary: Get Property Basic History
      description: Compact history of sales and assessment events for a property.
      operationId: getPropertyBasicHistory
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/expandedprofile:
    get:
      summary: Get Property Expanded Profile
      description: Full expanded property record including characteristics, owner, mortgage, and last sale.
      operationId: getPropertyExpandedProfile
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/expandedhistory:
    get:
      summary: Get Property Expanded History
      description: Full historical events for a property (sales, assessments, AVMs).
      operationId: getPropertyExpandedHistory
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/buildingpermits:
    get:
      summary: Get Property Building Permits
      description: Building permit records associated with a property.
      operationId: getPropertyBuildingPermits
      tags: [Building Permits]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /property/id:
    get:
      summary: Search By Property ID
      description: Look up properties by AttomID or other ATTOM-issued identifiers with optional search/sort filters.
      operationId: searchPropertyId
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/PageQuery'
        - $ref: '#/components/parameters/PageSizeQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyListResponse' }
  /transportationnoise:
    get:
      summary: Get Transportation Noise Score
      description: Return road, air, and rail transportation-noise scores for a property.
      operationId: getTransportationNoise
      tags: [Property]
      parameters:
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /enumerations/detail:
    get:
      summary: Get Enumeration Detail
      description: Return ATTOM enumeration metadata (property-use codes, tax-status codes, etc.).
      operationId: getEnumerationsDetail
      tags: [Property]
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /assessment/snapshot:
    get:
      summary: Get Assessment Snapshot
      description: Compact assessed-value record for a property.
      operationId: getAssessmentSnapshot
      tags: [Assessment]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AssessmentResponse' }
  /assessment/detail:
    get:
      summary: Get Assessment Detail
      description: Full assessed-value record including tax amount, tax year, market value, and exemption flags.
      operationId: getAssessmentDetail
      tags: [Assessment]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AssessmentResponse' }
  /assessmenthistory/detail:
    get:
      summary: Get Assessment History Detail
      description: Multi-year history of assessed values and tax amounts for a property.
      operationId: getAssessmentHistoryDetail
      tags: [Assessment]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AssessmentResponse' }
  /attomavm/detail:
    get:
      summary: Get ATTOM AVM Detail
      description: Return ATTOM Automated Valuation Model (AVM) value, confidence score, and value range.
      operationId: getAttomAvmDetail
      tags: [AVM]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AvmResponse' }
  /avm/snapshot:
    get:
      summary: Get AVM Snapshot
      description: Compact AVM record for a property.
      operationId: getAvmSnapshot
      tags: [AVM]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AvmResponse' }
  /avm/detail:
    get:
      summary: Get AVM Detail
      description: Detailed AVM record with confidence band and as-of date.
      operationId: getAvmDetail
      tags: [AVM]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AvmResponse' }
  /avmhistory/detail:
    get:
      summary: Get AVM History
      description: Historical AVM valuations for a property across multiple as-of dates.
      operationId: getAvmHistoryDetail
      tags: [AVM]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AvmResponse' }
  /valuation/rentalavm:
    get:
      summary: Get Rental AVM
      description: Estimated monthly rent for a property using ATTOM's rental AVM model.
      operationId: getRentalAvm
      tags: [AVM]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AvmResponse' }
  /valuation/homeequity:
    get:
      summary: Get Home Equity Estimate
      description: Estimated home equity (AVM minus open loan balances).
      operationId: getHomeEquity
      tags: [Home Equity]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/AvmResponse' }
  /sale/snapshot:
    get:
      summary: Get Sale Snapshot
      description: Most-recent sale event for a property (compact).
      operationId: getSaleSnapshot
      tags: [Sale]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/SaleResponse' }
  /sale/detail:
    get:
      summary: Get Sale Detail
      description: Most-recent sale event with full transaction, deed, and recording attributes.
      operationId: getSaleDetail
      tags: [Sale]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/SaleResponse' }
  /saleshistory/snapshot:
    get:
      summary: Get Sales History Snapshot
      description: Compact list of historical sale events for a property.
      operationId: getSalesHistorySnapshot
      tags: [Sale]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/SaleResponse' }
  /saleshistory/detail:
    get:
      summary: Get Sales History Detail
      description: Detailed list of historical sale events for a property.
      operationId: getSalesHistoryDetail
      tags: [Sale]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/SaleResponse' }
  /salescomparables/address/{street}/{citystatezip}:
    get:
      summary: Get Sales Comparables
      description: Return comparable sales (comps) for a subject property by street and city/state/ZIP.
      operationId: getSalesComparables
      tags: [Sale]
      parameters:
        - name: street
          in: path
          required: true
          description: Street component of the subject address.
          schema:
            type: string
        - name: citystatezip
          in: path
          required: true
          description: City, state, and ZIP component of the subject address.
          schema:
            type: string
      responses:
        '200': { $ref: '#/components/responses/SaleResponse' }
  /transaction/salestrend:
    get:
      summary: Get Sales Trend
      description: Average and median sales prices for the past two years for the requested geography.
      operationId: getSalesTrend
      tags: [Sales Trends]
      parameters:
        - name: geoIdV4
          in: query
          required: true
          description: ATTOM v4 geography identifier (state, county, CBSA, ZIP, neighborhood).
          schema:
            type: string
        - name: interval
          in: query
          required: false
          description: Time interval ("Yearly", "Monthly").
          schema:
            type: string
            enum: [Yearly, Monthly]
            default: Yearly
      responses:
        '200': { $ref: '#/components/responses/SaleResponse' }
  /allevents/snapshot:
    get:
      summary: Get All Events Snapshot
      description: Combined snapshot of assessment, AVM, and sales events for a property.
      operationId: getAllEventsSnapshot
      tags: [All Events]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
        - $ref: '#/components/parameters/Address1Query'
        - $ref: '#/components/parameters/Address2Query'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /allevents/detail:
    get:
      summary: Get All Events Detail
      description: Combined detail of assessment, AVM, and sales events for a property.
      operationId: getAllEventsDetail
      tags: [All Events]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
        - $ref: '#/components/parameters/Address1Query'
        - $ref: '#/components/parameters/Address2Query'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /preforeclosure/details:
    get:
      summary: Get Pre-Foreclosure Details
      description: Pre-foreclosure status, notice date, and lender for a property.
      operationId: getPreforeclosureDetails
      tags: [Pre-Foreclosure]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
  /school/snapshot:
    get:
      summary: Get School Snapshot
      description: Schools and school-district attributes associated with a property.
      operationId: getSchoolSnapshot
      tags: [School]
      parameters:
        - $ref: '#/components/parameters/AttomIDQuery'
        - $ref: '#/components/parameters/AddressQuery'
      responses:
        '200': { $ref: '#/components/responses/PropertyResponse' }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: |
        ATTOM-issued API key. Obtain a free 30-day trial key at
        https://api.developer.attomdata.com/signup. Pass the key in the `apikey`
        request header on every call.
  parameters:
    AttomIDQuery:
      name: AttomID
      in: query
      required: false
      description: ATTOM property identifier.
      schema:
        type: string
      example: '145423726'
    AddressQuery:
      name: address
      in: query
      required: false
      description: Full street address as a single string.
      schema:
        type: string
      example: 4529 Winona Court, Denver, CO 80212
    Address1Query:
      name: address1
      in: query
      required: false
      description: Street component of the property address.
      schema:
        type: string
      example: 4529 Winona Court
    Address2Query:
      name: address2
      in: query
      required: false
      description: City, state, and ZIP component of the property address.
      schema:
        type: string
      example: Denver, CO 80212
    PageQuery:
      name: page
      in: query
      required: false
      description: Page number for paginated result sets.
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSizeQuery:
      name: pagesize
      in: query
      required: false
      description: Records per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  schemas:
    Status:
      type: object
      description: ATTOM standard response status block.
      properties:
        version:
          type: string
        code:
          type: integer
        msg:
          type: string
        total:
          type: integer
        page:
          type: integer
        pagesize:
          type: integer
    Address:
      type: object
      properties:
        country:
          type: string
        countrySubd:
          type: string
        line1:
          type: string
        line2:
          type: string
        locality:
          type: string
        matchCode:
          type: string
        oneLine:
          type: string
        postal1:
          type: string
        postal2:
          type: string
        postal3:
          type: string
    Location:
      type: object
      properties:
        accuracy:
          type: string
        latitude:
          type: string
        longitude:
          type: string
        distance:
          type: number
        geoid:
          type: string
        geoIdV4:
          type: object
    Identifier:
      type: object
      properties:
        Id:
          type: integer
        fips:
          type: string
        apn:
          type: string
        attomId:
          type: integer
    Lot:
      type: object
      properties:
        lotnum:
          type: string
        lotsize1:
          type: number
        lotsize2:
          type: number
        zoningType:
          type: string
    Building:
      type: object
      properties:
        size:
          type: object
          properties:
            bldgsize:
              type: integer
            grosssize:
              type: integer
            livingsize:
              type: integer
            universalsize:
              type: integer
        rooms:
          type: object
          properties:
            bathstotal:
              type: number
            beds:
              type: integer
            roomsTotal:
              type: integer
        construction:
          type: object
          properties:
            condition:
              type: string
            constructionType:
              type: string
            wallType:
              type: string
            roofCover:
              type: string
        summary:
          type: object
          properties:
            yearbuilteffective:
              type: integer
            yearbuilt:
              type: integer
    Summary:
      type: object
      properties:
        absenteeInd:
          type: string
        propclass:
          type: string
        propsubtype:
          type: string
        proptype:
          type: string
        yearbuilt:
          type: integer
        propLandUse:
          type: string
    Owner:
      type: object
      properties:
        corporateindicator:
          type: string
        owner1:
          type: object
          properties:
            firstnameandmi:
              type: string
            lastname:
              type: string
        owner2:
          type: object
          properties:
            firstnameandmi:
              type: string
            lastname:
              type: string
        mailingaddressoneline:
          type: string
    Mortgage:
      type: object
      properties:
        FirstConcurrent:
          type: object
          properties:
            amount:
              type: integer
            date:
              type: string
            lender:
              type: object
              properties:
                fullName:
                  type: string
            interestRate:
              type: number
            term:
              type: string
            trustDeedDocumentNumber:
              type: string
    Vintage:
      type: object
      properties:
        lastModified:
          type: string
        pubDate:
          type: string
    Property:
      type: object
      properties:
        identifier:
          $ref: '#/components/schemas/Identifier'
        lot:
          $ref: '#/components/schemas/Lot'
        area:
          type: object
        address:
          $ref: '#/components/schemas/Address'
        location:
          $ref: '#/components/schemas/Location'
        summary:
          $ref: '#/components/schemas/Summary'
        building:
          $ref: '#/components/schemas/Building'
        owner:
          $ref: '#/components/schemas/Owner'
        mortgage:
          $ref: '#/components/schemas/Mortgage'
        vintage:
          $ref: '#/components/schemas/Vintage'
    Assessment:
      type: object
      properties:
        appraised:
          type: object
          properties:
            apprimprvalue:
              type: integer
            apprlandvalue:
              type: integer
            apprttlvalue:
              type: integer
        assessed:
          type: object
          properties:
            assdimprvalue:
              type: integer
            assdlandvalue:
              type: integer
            assdttlvalue:
              type: integer
        market:
          type: object
          properties:
            mktimprvalue:
              type: integer
            mktlandvalue:
              type: integer
            mktttlvalue:
              type: integer
        tax:
          type: object
          properties:
            taxamt:
              type: number
            taxpereszidx:
              type: number
            taxyear:
              type: integer
        owner:
          $ref: '#/components/schemas/Owner'
    AVM:
      type: object
      properties:
        amount:
          type: object
          properties:
            scr:
              type: integer
            value:
              type: integer
            high:
              type: integer
            low:
              type: integer
            valueRange:
              type: integer
            confidence:
              type: string
        eventDate:
          type: string
        AVMModel:
          type: object
          properties:
            FSDscore:
              type: integer
    Sale:
      type: object
      properties:
        amount:
          type: object
          properties:
            saleamt:
              type: integer
            salecode:
              type: string
            saledisclosuretype:
              type: integer
            saledocnum:
              type: string
            saledocType:
              type: string
            saletranstype:
              type: string
        calculation:
          type: object
          properties:
            pricepersizeunit:
              type: number
        salesearchdate:
          type: string
        saleTransDate:
          type: string
    PropertyEnvelope:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        property:
          type: array
          items:
            $ref: '#/components/schemas/Property'
    PropertyListEnvelope:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        property:
          type: array
          items:
            $ref: '#/components/schemas/Property'
    AssessmentEnvelope:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        property:
          type: array
          items:
            type: object
            properties:
              identifier:
                $ref: '#/components/schemas/Identifier'
              address:
                $ref: '#/components/schemas/Address'
              assessment:
                $ref: '#/components/schemas/Assessment'
    AvmEnvelope:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        property:
          type: array
          items:
            type: object
            properties:
              identifier:
                $ref: '#/components/schemas/Identifier'
              address:
                $ref: '#/components/schemas/Address'
              avm:
                $ref: '#/components/schemas/AVM'
    SaleEnvelope:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        property:
          type: array
          items:
            type: object
            properties:
              identifier:
                $ref: '#/components/schemas/Identifier'
              address:
                $ref: '#/components/schemas/Address'
              sale:
                $ref: '#/components/schemas/Sale'
    Error:
      type: object
      properties:
        Response:
          type: object
          properties:
            status:
              $ref: '#/components/schemas/Status'
  responses:
    PropertyResponse:
      description: Property record envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PropertyEnvelope'
    PropertyListResponse:
      description: Paginated list of property records.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PropertyListEnvelope'
    AssessmentResponse:
      description: Assessment envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AssessmentEnvelope'
    AvmResponse:
      description: AVM envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvmEnvelope'
    SaleResponse:
      description: Sale envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SaleEnvelope'
    ErrorResponse:
      description: ATTOM error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'