Getting Started is Easy!

Nothing could be simpler than setting
up your New Home Feed account.

Create a Free Account

Simple, Intuitive, Affordable.
See Our Pricing Now!

New Home Feed API

New Home Feed XML Format

New Home Feed's default XML schema is a proprietary format designed for readability, ease of development, and maintainability.

Resources

Change History

Schema Detail

Element Description
<root created_on="2012-05-18T21:12:09-05:00" />
root
Base node of the feed; encloses all other elements. Required
created_on attribute
Timestamp when the feed was created. dateTime (YYYY-MM-DDThh:mm:ss format)
<builders total="" />
builders
Container element for all builders. Holds <builder/> elements. Required
total attribute
Total number of builders in this feed. Use to verify successful import. Integer. Optional.

Builder Element

Builder corporations are defined using these elements. Subdivisions (e.g. Happy Homebuilders - North) are not supported.

Repeatable: Yes.

Element Description
<builder is_active="1"> id="" />
builder
Builder element, contains all information for a single Builder
is_active attribute
Setting this value to 0 will remove all this builder's listings from all channels. Data will be kept in the system. Boolean. Optional, default 1.
id attribute
New Home Feed identifier for this builder. Not used in this version of the API. Integer. Optional.
<number/> Unique ID among builders for this source. If one is not provided, New Home Feed will create an appropriate value. The value of this field should never change once set the first time, since New Home Feed uses this value to find existing records in our system. String, up to 100 characters. Optional.
<name/> Consumer-facing or marketing name. Do not include suffixes such as "Inc.", "Corporation", or "Corp". String, up to 100 characters. Required.
<name_reporting/> Name used for reporting and billing. Not consumer-facing. Defaults to consumer name if not provided. String, up to 100 characterse. Optional.
<phone/> Contact phone number. Will be used if children elements do not have a leads phone number. String, up to 30 characters. Optional.
<email/> Contact email address. Value of this field is not used for distributing leads. String, up to 255 characters. Required.
<leads_email/> Default email address for leads. String, up to 255 characters. Required.
<dre_number/> California DRE License Number String, up to 50 characters. Required, if builder is located in CA.
<website/> Link to builder's homepage. Value of this field will be used if children elements do not have a website. URL, up to 255 characters. Must begin with 'http://'. Optional.
<logo_url/> Brand logo. URL, up to 255 characters. Must begin with 'http://'. Optional.
<address/> Contact address. Not consumer-facing. Optional. String, up to 100 characters.
<city/> Contact city. Not consumer-facing. String, up to 50 characters. Optional.
<state/> Contact state abbreviation (e.g. 'CA'). Not consumer-facing. String, exactly 2 characters. Optional.
<zip/> Contact zip/postal code. Not consumer-facing. String, up to 20 characters. Optional.
<communities total="" />
communities
Container element for all communities. Holds <community/> elements.Required, if builder builds by communities.
total attribute
Total number of communities for this builder. Used to verify successful import. Integer. Optional.
<homes total="" />
homes
Container element for all homes that are NOT part of a community. Holds <home/> elements. Required, if builder has homes which are not part of a community..
total attribute
Total number of homes for this builder. Used to verify successful import. Integer. Optional.

Community Element

Element Description
<community is_active="" id="" />
community
Contains all information for a single community.
is_active attribute
Setting this value to 0 will remove this community from all listing websites that list communities. This will not affect the status of plans and homes belonging to this community.
id attribute
New Home Feed identifier for this community. For internal use only. Integer. Optional.
<number/> Unique ID among communities for this builder. If one is not provided, New Home Feed will create an appropriate value. The value of this field should never change once set the first time, since New Home Feed uses this value to find existing records in our system. String, up to 50 characters. Optional.
<name/> Marketing name for this community (e.g. 'Creekside Glen'). String, up to 100 characters. Required.
<leads_email/> Default email address for leads for this community. String, up to 255 characters. Required.
<website/> Link to community's homepage. URL, up to 255 characters. Must begin with 'http://'. Recommended
<share_with_realtors/> Set this value to 1 to make this community available to realtors on listing websites that support this. Boolean. Optional, default 1.
<price_low/> Low end of price range for homes in this community. Integer. Optional.
<price_high/> High end of price range for homes in this community. Integer. Optional.
<sqft_low/> Low end of size range for homes in this community. Integer. Optional.
<sqft_high/> High end of size range for homes in this community. Integer. Optional.
<description/> Description of this community. String. Recommended
<marketing_status/> Supported values are 'Active', 'GrandOpening', 'Closeout', 'ComingSoon'. Enumerated string. Optional.
<address/> Street address. Required. String, up to 100 characters.
<address_2/> Street address - second line. String, up to 100 characters. Optional.
<city/> City name be overriden by New Home Feed or listing websites using geolocation lookup (based on ZIP). Required. String, up to 50 characters.
<state/> Use 2-digit USPS abbreviations only. Required. String, exactly 2 characters.
<zip/> 5- or 9-digit ZIP code for US (only first 5 digits will be used); postal code for international. Required. String, up to 20 characters.
<county/> May be overriden by New Home Feed or listing websites using geolocation lookup (based on ZIP). Optional. String, up to 50 characters.
<country/> Use 2-digit USPS abbreviations only. 'US' is the only supported value at this time. Optional. String, exactly 2 characters; default 'US'.
<driving_directions/> String. Optional.
<latitude/> Used in automated routing. Geolocation coordinates of the community (e.g. main entrance) in decimal degrees (e.g. 43.285909) Decimal. Required, if longitude is present.
<longitude/> Used in automated routing. Geolocation coordinates of the community (e.g. main entrance) in decimal degrees (e.g. -102.938021) Decimal. Required, if latitude is present.
<promo_headline/> Optional. String, up to 100 characters.
<promo_description/> String. Optional.
<promo_url/> URL, up to 255 characters. Must begin with 'http://'. Optional.
<neighborhood_name/> The name of any neighborhood the community is located within. e.g. 'North Beach' or 'West Hollywood' String, up to 100 characters. Optional.
<neighborhood_description/> A marketing description of any amenities near the community. e.g. 'Three large parks and two supermarkets are all within walking distance. North County Reserve has over 10 miles of hiking/biking trails and is a short drive away.' String. Optional.
<style/> A single community style. Supported values are 'MasterPlanned', 'Gated', 'Adult', 'CondoOnly', 'AgeRestricted'. Enumerated string. Optional.
<community_amenities/> Container element for all amenities for this community. Holds <community_amenity/> elements.
<images/> Container element for all images for this community. Holds <image/> elements.
<community_services/> Container element for all services for this community. Holds <community_service/> elements.
<community_testimonials/> Container element for all testimonials for this community. Holds <community_testimonial/> elements.
<community_utilities/> Container element for all utilities for this community. Holds <community_utility/> elements.
<community_videos/> Container element for all videos for this community. Holds <video/> elements.
<sales_office/> See <sales_office/> element.
<schools/> Container element for all schools for this community. Holds <school/> elements.
<plans total=""/>
plans
Container element for all plans for this community. Holds <plan/> elements.
total attribute
Total number of plans for this community. Used to verify successful import. Integer. Optional.

Community Amenity Element

Element Description
<community_amenity/> Contains all information for a single community Amenity
<category/> Supported values:
  • Baseball
  • Basketball
  • Beach
  • Clubhouse
  • CommunityCenter
  • GolfCourse
  • Greenbelt
  • Lake
  • Marina
  • Park
  • Playground
  • Pond
  • Pool
  • Soccer
  • Tennis
  • Trails
  • Views
  • Volleyball
  • WaterfrontLots
Enumerated string. Required.
<name/> String, up to 100 characters. Required.
<website/> URL, up to 255 characters. Must begin with 'http://'. Optional.

Community Service Element

Element Description
<community_service/> Contains all information for a single Community Service
<type/> Supported values are:
  • GroundsCare
  • HOA
  • Maintenance
  • MedicalCare
  • Security
  • Shopping
Required. Enumerated string.
<name/> Required. String, up to 100 characters.

Community Testimonial Element

Element Description
<community_testimonial/> Contains all information for a single Community Testimonial
<sequence_position/> Indicates the preferred display order when there are multiple testimonials. Integer. Required.
<quote/> The flattering comments someone has to say about a community. Do not surround the quote with quotation marks and do not use HTML. String. Required.
<attribution/> The name of the person who said the flattering comments. String, up to 100 characters. Required.

Community Utility Element

Element Description
<community_utility/> Contains all information for a single Community Utility
<type/> Supported values are:
  • Electric
  • Garbage
  • Gas
  • ISP
  • Telephone
  • WaterWastewater
Required. Enumerated string.
<name/> String, up to 100 characters. Required.
<phone/> String, up to 30 characters. Optional.

Video Element

Element Description
<video/> Contains all information for a single video.
<sequence_position/> Indicates the preferred display order when there are multiple videos. Integer. Required.
<url/> Location of the video file on the web. URL, up to 255 characters. Must begin with 'http://'. Required.
<title/> e.g. "Walking Tour" String, up to 50 characters. Recommended.

School Element

Element Description
<school/> Contains all information for a single School
<ncesid/> National Center for Education Statistics ID String, up to 12 characters. Required.

Plan Element

Element Description
<plan is_active="1" id="" />
plan
Contains all information for a single Plan
is_active attribute
This plan is available to be sent to listing websites. Does not affect the status of homes built on this plan.
id attribute
New Home Feed identifier for this plan. For internal use only. Integer. Optional.
<number/> Unique ID among plans for this community. If one is not provided, New Home Feed will create an appropriate value. The value of this field should never change once set the first time, since New Home Feed uses this value to find existing records in our system. String, up to 50 characters. Optional.
<name/> Marketing name for this plan (e.g. 'Buckingham - 1'). Required. String, up to 50 characters.
<style/> Supported values:
  • Single Family
  • Condominium
  • Townhome
  • Carriage House
  • Garden Home
Enumerated string. Optional.
<base_price/> Low end of price range for homes in this plan. Integer. Required.
<base_sqft/> Low end of size range for homes in this plan. Integer. Optional.
<stories/> Integer. Optional.
<bedrooms/> Number of bedrooms. Set to 0 for a studio. Integer. Required.
<master_bedroom_location/> Supported values:
  • U - Upstairs (default)
  • D - Downstairs
Enumerated string. Optional.
<baths/> Number of full bathrooms. Integer. Required.
<half_baths/> Number of partial bathrooms. Integer. Optional.
<garage/> Number of cars that can fit in the garage. Integer. Optional.
<garage_entry/> Supported values:
  • Front
  • Rear
  • Side
Enumerated string. Optional.
<garage_detach/> Is the garage detached from the home? Boolean. Optional, default 0.
<dining_areas/> Number of dining areas Integer. Optional.
<basement/> Does this plan always include a basement? Boolean. Optional, default 0.
<land_price/> Does the plan price include the lot? Boolean. Optional, default 1.
<marketing_headline/> String, up to 100 characters. Optional.
<description/> String. Recommended.
<virtual_tour/> Link to virtual tour. URL, up to 255 characters. Must begin with 'http://'. Optional.
<plan_viewer/> Link to interactive floorplan viewer. URL, up to 255 characters. Must begin with 'http://'. Optional.
<plan_amenities/> Container element for all amenities for this plan. Holds <plan_amenity/> elements.
<elevation_images/> Container element for all elevation images for this plan. Holds <image/> elements.
<images/> Container element for all floorplan images for this plan. Holds <image/> elements.
<interior_images/> Container element for all interior photos for this plan. Holds <image/> elements.
<plan_options/> Container element for all options for this plan. Holds <option/> elements.
<homes/> Container element for all homes built on this plan. Holds <home/> elements.

Plan Amenity Element

Element Description
<plan_amenity/> Contains all information for a single plan Amenity
<name/> Features available to all homes in this plan:
  • Fireplaces
  • Vaulted Ceilings
  • WalkInClosets
Enumerated string. Required.

Image Element

Element Description
<image/> Contains all information for a single Image
<sequence_position/> Indicates the preferred display order when there are multiple images. Integer. Required
<reference/> Location of the image on the web. URL, up to 255 characters. Must begin with 'http://'. Required.
<type/> For communities, supported values are:
  • 0 - Standard image, default
  • 1 - Driving Directions
  • 2 - Community Banner
  • 3 - Lot Map

For plans and homes, supported values are:
  • 0 - Elevation
  • 1 - Interior
  • 2 - Floorplan

Enumerated string. Required.
<title/> e.g. "Community Recreation Area" String, up to 50 characters. Recommended.
<caption/> e.g. "The Olympic-size pool is heated year-round." String, up to 100 characters. Recommended.

Option Element

Element Description
<option/> Contains all information for a single home or plan Option. Homes assigned to a plan will inherit all option values unless explicitly overridden in the Home element.
<type/> Supported values:
  • Basement
  • Bath
  • Bedroom
  • Garage
  • LivingArea
Enumerated string. Required
<name/> String, up to 100 characters. Optional.
<price/> Integer. Optional.
<sqft/> Integer. Optional.

Home Element

Element Description
<home is_active="1" id="" />
home
Home element, contains all information for a single spec listing.
id attribute
New Home Feed identifier for this home. For internal use only. Integer. Optional.
<number/> Unique ID among homes for this plan. If one is not provided, New Home Feed will create an appropriate value. The value of this field should never change once set the first time, since New Home Feed uses this value to find existing records in our system. String, up to 50 characters. Optional.
<listing_title/> Marketing name for this listing title (e.g. 'Gorgeous New Home on Corner Lot'). Required. String, up to 50 characters.
<home_type/> Supported values:
  • spec
  • model
  • lot
Enumerated string. Optional.
<property_type/> Supported values:
  • apartment
  • condo
  • coop
  • farm-ranch
  • houseboat
  • income-investment
  • loft
  • lot-land
  • multi-family home
  • manufactured
  • mobile-manufactured
  • single-family home
  • townhouse
  • vacant land
  • other
Enumerated string. Optional.
<sales_status/> Supported values:
  • active
  • contingent
  • pending
  • sold
  • withdrawn
  • for rent
  • for sale
<lot/> Lot number String, up to 20 characters. Optional.
<parcel_id/> Parcel ID or 8-digit Tax ID for this property. String, up to 10 characters. Optional.
<address/> Property street address. String, up to 100 characters. Required, if property has an address.
<address/> Property street address - second line. String, up to 100 characters. Optional.
<city/> City name be overriden by New Home Feed or listing websites using geolocation lookup (based on ZIP). String, up to 50 characters. Required, if property has an address.
<state/> Use 2-digit USPS abbreviations only. String, exactly 2 characters. Required, if property has an address.
<zip/> 5- or 9-digit ZIP code for US (only first 5 digits will be used); postal code for international. String, up to 20 characters. Required, if property has an address.
<street_intersection/> String, up to 100 characters. Optional.
<county/> May be overriden by New Home Feed or listing websites using geolocation lookup (based on ZIP). String, up to 50 characters. Optional.
<country/> Use 2-digit USPS abbreviations only. 'US' is the only supported value at this time. String, exactly 2 characters; default 'US'. Optional.
<latitude/> Used in automated routing. Geolocation coordinates of the community (e.g. main entrance) in decimal degrees (e.g. 43.285909) Decimal. Required, if longitude is present.
<longitude/> Used in automated routing. Geolocation coordinates of the community (e.g. main entrance) in decimal degrees (e.g. -102.938021) Decimal. Required, if latitude is present.
<elevation/> Elevation of property, in feet. Integer. Optional.
<date_listed/> Format YYYY-MM-DD. Date. Optional.
<date_sold/> Format YYYY-MM-DD. Date. Optional.
<move_in_date/> Format YYYY-MM-DD. Date. Optional.
<term/> Supported values:
  • purchase
  • lease
  • rent
Enumerated string. Optional.
<price/> Integer. Required.
<sqft/> Integer. Optional.
<stories/> Integer. Optional.
<unit_level/> Story unit is on, if in a multi-family property. Integer. Optional.
<number_of_units/> Total number of units in the building, if in a multi-family property. Integer. Optional.
<location/> Location of unit in the building. Supported values:
  • corner
  • interior
  • end
    • Enumerated string. Optional.
<year_built/> Format YYYY. Integer. Optional.
<baths/> Integer. Optional.
<half_baths/> Integer. Optional.
<bedrooms/> Integer. Optional.
<master_bedroom_location/> Supported values:
  • U - Upstairs (default)
  • D - Downstairs
Enumerated string. Optional.
<garage/> Number of cars that can fit in the garage. Integer. Optional.
<garage_entry/> Supported values:
  • Front
  • Rear
  • Side
Enumerated string. Optional.
<garage_detach/> Is the garage detached from the home? Boolean. Optional, default 0.
<dining_areas/> Number of dining areas Integer. Optional.
<basement/> Does this plan always include a basement? Boolean. Optional, default 0.
<marketing_headline/> String, up to 100 characters. Optional.
<description/> String. Recommended.
<directions/> String. Optional.
<listing_url/> Link to a page with more information about this home. URL, up to 255 characters. Must begin with 'http://'. Recommended.
<mls_id/>
<mls_name/>
<mls_number/>
<neighborhood_name/> See community description for this field. If not populated, will inherit from the community value. String, up to 100 characters. Optional.
<neighborhood_description/> See community description for this field. If not populated, will inherit from the community value. String. Optional.
<broker_name/>
<broker_phone/>
<broker_email/>
<broker_website/>
<broker_logo_url/>
<broker_address/>
<broker_city/>
<broker_state/>
<broker_zip/>
<home_fees/> Container element for all taxes/fees for this home. Holds <home_fee/> elements.
<images/> Container element for all images for this home. Holds <image/> elements.
<home_options/> Container element for all options for this home. Holds <option/> elements.
<home_videos/> Container element for all videos for this home. Holds <video/> elements.
<home_virtual_tours/> Container element for all virtualtours for this home. Holds <video/> elements.

Home Fee Element

Element Description
<home_fee/> Contais all information for a single Home Fee or Tax
<type/> Type of fee or tax (e.g. 'Property Taxes'). String, up to 100 characters. Required.
<amount/> Total payment amount of fee/tax in US dollars (e.g. 500) Integer. Required.
<year/> Year this fee/tax is due or applied to. (e.g. 2012) Integer. Optional.

Sales Office Element

Element Description
<sales_office id="" />
sales_office
id attribute
New Home Feed identifier for this sales office. For internal use only. Integer. Optional.
<address/> String, up to 100 characters. Required.
<address_2/> String, up to 100 characters. Optional.
<city/> String, up to 50 characters. Required.
<state/> Contact state abbreviation (e.g. 'CA'). String, exactly 2 characters. Required.
<zip/> Contact zip/postal code. String, up to 20 characters. Required.
<latitude/> Used in automated routing. Geolocation coordinates of the sales office in decimal degrees (e.g. 43.285909) Decimal. Required, if longitude is present.
<longitude/> Used in automated routing. Geolocation coordinates of the sales office in decimal degrees (e.g. -102.938021) Decimal. Required, if latitude is present.
<phone/> Contact phone number. Include area code and optional extension. e.g. 408-123-4500 x476 String, up to 30 characters. Required.
<fax/> Contact fax number. Include area code. e.g. 408-123-4501 String, up to 30 characters. Optional.
<email/> Contact email address. String, up to 255 characters. Recommended.
<hours/> Hours that the sales office is open for buyers. e.g. 'Mon-Fri 8am-5pm, Sat 9am-5pm, closed Sunday' String. Recommended.
<mls_code/>
<website/> Link to the Sales Office website. URL, up to 255 characters. Must begin with 'http://'. Optional.
<sales_agents/> Holds <sales_agent/> elements.

Sales Agent Element

Element Description
<sales_agent id="" />
sales_agent
id attribute
New Home Feed identifier for this sales office. For internal use only. Integer. Optional.
<name/> Name of person who represents the given community. e.g. 'John Smith'. String, up to 100 characters. Required.
<email/> Agent's email address. If no email is given, the sales office email will be used. String, up to 255 characters. Recommended.
<phone/> Agent's direct phone number. If no phone number is given, the sales office phone number will be used. String, up to 30 characters. Recommended.
<phone_ext/> Agent's direct phone extension. Integer Optional.
<picture_url/> Link to agent's photo, suitable for display in a listing. URL, up to 255 characters. Must begin with 'http://'. Optional.