openapi: 3.0.3
info:
  title: Estated Property Data API
  version: '4.0'
  description: >-
    The Estated Property Data API (v4) returns assessor, parcel, structure,
    valuation, owner, deed, and boundary data for U.S. residential and
    commercial properties. Lookups can be performed using a split address
    (street_address + city + state), parsed address components, a single
    combined address string, or a FIPS code + APN pair. Each successful
    response returns a Property object containing metadata, address, parcel,
    structure, taxes, assessments, market_assessments, valuation, owner,
    deeds, and boundary sections. Estated was acquired by ATTOM Data in 2020
    and the underlying platform is being migrated to ATTOM infrastructure;
    existing tokens continue to work but documentation will be deprecated
    during 2026.
  contact:
    name: ATTOM Data (Estated)
    url: https://www.attomdata.com/contact-us/
  license:
    name: Commercial
    url: https://www.attomdata.com/terms-of-use/
servers:
  - url: https://apis.estated.com
    description: Production API endpoint
security:
  - tokenQuery: []
paths:
  /v4/property:
    get:
      operationId: getProperty
      summary: Get Property
      description: >-
        Retrieve a Property object for a U.S. address. Use the `combined_address`
        parameter for a single-string lookup, the parsed `street_number` /
        `street_name` / `street_suffix` family for tightly-parsed lookups, the
        `street_address` + `city` + `state` family for split lookups, or
        `fips` + `apn` for parcel-number lookups. All requests are HTTP GET.
      tags:
        - Property
      parameters:
        - name: token
          in: query
          required: true
          description: API token issued by Estated / ATTOM.
          schema:
            type: string
        - name: combined_address
          in: query
          required: false
          description: Full address in a single comma-separated string (street, city, state, zip).
          schema:
            type: string
        - name: street_address
          in: query
          required: false
          description: Full street address line including number, name, and suffix.
          schema:
            type: string
        - name: street_number
          in: query
          required: false
          schema:
            type: string
        - name: street_pre_direction
          in: query
          required: false
          schema:
            type: string
        - name: street_name
          in: query
          required: false
          schema:
            type: string
        - name: street_suffix
          in: query
          required: false
          schema:
            type: string
        - name: street_post_direction
          in: query
          required: false
          schema:
            type: string
        - name: unit_type
          in: query
          required: false
          schema:
            type: string
        - name: unit_number
          in: query
          required: false
          schema:
            type: string
        - name: city
          in: query
          required: false
          schema:
            type: string
        - name: state
          in: query
          required: false
          schema:
            type: string
        - name: zip_code
          in: query
          required: false
          schema:
            type: string
        - name: fips
          in: query
          required: false
          description: 5-digit FIPS county code (paired with `apn`).
          schema:
            type: string
        - name: apn
          in: query
          required: false
          description: Assessor parcel number (paired with `fips`).
          schema:
            type: string
      responses:
        '200':
          description: A property envelope containing data, metadata, and warnings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyEnvelope'
        '400':
          description: Request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Authorization error (invalid, deactivated, or exhausted token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Throttled due to high request rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  securitySchemes:
    tokenQuery:
      type: apiKey
      in: query
      name: token
  schemas:
    PropertyEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Property'
        metadata:
          $ref: '#/components/schemas/ResponseMetadata'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
    ErrorEnvelope:
      type: object
      properties:
        data:
          nullable: true
        metadata:
          $ref: '#/components/schemas/ResponseMetadata'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
        error:
          type: object
          properties:
            code:
              type: string
              description: Estated error code (APE01, ISE01-09, EE01, RE01-RE06, AE02-AE04).
            message:
              type: string
    ResponseMetadata:
      type: object
      properties:
        attom_id:
          type: integer
          description: Unique ATTOM ID associated with the property.
        publishing_date:
          type: string
          format: date
          description: Date the assessor roll data was published.
    Warning:
      type: object
      properties:
        code:
          type: string
          description: Warning code (PW01, PW02, APW01, APW02).
        message:
          type: string
    Property:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ResponseMetadata'
        address:
          $ref: '#/components/schemas/Address'
        parcel:
          $ref: '#/components/schemas/Parcel'
        structure:
          $ref: '#/components/schemas/Structure'
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/Tax'
        assessments:
          type: array
          items:
            $ref: '#/components/schemas/Assessment'
        market_assessments:
          type: array
          items:
            $ref: '#/components/schemas/Assessment'
        valuation:
          $ref: '#/components/schemas/Valuation'
        owner:
          $ref: '#/components/schemas/Owner'
        deeds:
          type: array
          items:
            $ref: '#/components/schemas/Deed'
        boundary:
          $ref: '#/components/schemas/Boundary'
    Address:
      type: object
      properties:
        street_number: { type: string }
        street_pre_direction: { type: string }
        street_name: { type: string }
        street_suffix: { type: string }
        street_post_direction: { type: string }
        unit_type: { type: string }
        unit_number: { type: string }
        formatted_street_address: { type: string }
        city: { type: string }
        state: { type: string }
        zip_code: { type: string }
        zip_plus_four_code: { type: string }
        carrier_code: { type: string }
        latitude: { type: number, format: float }
        longitude: { type: number, format: float }
        geocoding_accuracy: { type: string }
        census_tract: { type: string }
    Parcel:
      type: object
      properties:
        apn_original: { type: string }
        apn_unformatted: { type: string }
        apn_previous: { type: string }
        fips_code: { type: string }
        depth_ft: { type: number, format: float }
        frontage_ft: { type: number, format: float }
        area_sq_ft: { type: integer }
        area_acres: { type: number, format: float }
        county_name: { type: string }
        county_land_use_code: { type: string }
        county_land_use_description: { type: string }
        standardized_land_use_category: { type: string }
        standardized_land_use_type: { type: string }
        location_descriptions:
          type: array
          items: { type: string }
        zoning: { type: string }
        building_count: { type: integer }
        tax_account_number: { type: string }
        legal_description: { type: string }
        lot_code: { type: string }
        lot_number: { type: string }
        subdivision: { type: string }
        municipality: { type: string }
        section_township_range: { type: string }
    Structure:
      type: object
      properties:
        year_built: { type: integer }
        effective_year_built: { type: integer }
        stories: { type: string }
        rooms_count: { type: integer }
        beds_count: { type: integer }
        baths: { type: number, format: float }
        partial_baths_count: { type: integer }
        units_count: { type: integer }
        parking_type: { type: string }
        parking_spaces_count: { type: integer }
        pool_type: { type: string }
        architecture_type: { type: string }
        construction_type: { type: string }
        exterior_wall_type: { type: string }
        foundation_type: { type: string }
        roof_material_type: { type: string }
        roof_style_type: { type: string }
        heating_type: { type: string }
        heating_fuel_type: { type: string }
        air_conditioning_type: { type: string }
        fireplaces: { type: string }
        basement_type: { type: string }
        quality: { type: string }
        condition: { type: string }
        flooring_types:
          type: array
          items: { type: string }
        plumbing_fixtures_count: { type: integer }
        interior_wall_type: { type: string }
        water_type: { type: string }
        sewer_type: { type: string }
        total_area_sq_ft: { type: integer }
        amenities:
          type: array
          items: { type: string }
        other_improvements:
          type: array
          items:
            $ref: '#/components/schemas/AreaItem'
        other_rooms:
          type: array
          items:
            $ref: '#/components/schemas/AreaItem'
        other_features:
          type: array
          items:
            $ref: '#/components/schemas/AreaItem'
        other_areas:
          type: array
          items:
            $ref: '#/components/schemas/AreaItem'
    AreaItem:
      type: object
      properties:
        type: { type: string }
        sq_ft: { type: string }
    Tax:
      type: object
      properties:
        year: { type: integer }
        amount: { type: integer }
        exemptions:
          type: array
          items: { type: string }
        rate_code_area: { type: string }
    Assessment:
      type: object
      properties:
        year: { type: integer }
        land_value: { type: integer }
        improvement_value: { type: integer }
        total_value: { type: integer }
    Valuation:
      type: object
      properties:
        value: { type: integer }
        high: { type: integer }
        low: { type: integer }
        forecast_standard_deviation: { type: integer }
        date: { type: string, format: date }
    Owner:
      type: object
      properties:
        name: { type: string }
        second_name: { type: string, deprecated: true }
        formatted_street_address: { type: string }
        unit_type: { type: string }
        unit_number: { type: string }
        city: { type: string }
        state: { type: string }
        zip_code: { type: string }
        zip_plus_four_code: { type: string }
        owner_occupied: { type: string }
    Deed:
      type: object
      properties:
        document_type: { type: string }
        recording_date: { type: string, format: date }
        original_contract_date: { type: string, format: date }
        deed_book: { type: string }
        deed_page: { type: string }
        document_id: { type: string }
        sale_price: { type: integer }
        sale_price_description: { type: string }
        transfer_tax: { type: number, format: float }
        distressed_sale: { type: boolean }
        real_estate_owned: { type: string }
        seller_first_name: { type: string }
        seller_last_name: { type: string }
        seller2_first_name: { type: string }
        seller2_last_name: { type: string }
        seller_address: { type: string }
        seller_unit_number: { type: string }
        seller_city: { type: string }
        seller_state: { type: string }
        seller_zip_code: { type: string }
        seller_zip_plus_four_code: { type: string }
        buyer_first_name: { type: string }
        buyer_last_name: { type: string }
        buyer2_first_name: { type: string }
        buyer2_last_name: { type: string }
    Boundary:
      type: object
      description: Parcel boundary geometry.
      properties:
        wkt:
          type: string
          description: Well-Known Text MultiPolygon representation.
        geojson:
          type: object
          description: GeoJSON MultiPolygon representation of the parcel.
          properties:
            type:
              type: string
              example: MultiPolygon
            coordinates:
              type: array
              items:
                type: array