Upload Listings

List Real Estate Rentals on Marketplace.

Listing properties on Facebook Marketplace is currently a closed beta program.

Agencies who want to list their home rentals on Marketplace can sign up through one of our listing partners.

Getting started

Facebook Product Catalog is used to upload inventory to Facebook Marketplace. In this document, you'll find a step-by-step guide on how to create the catalog, upload it and keep the feed up to date.

1
2
Check the best practices to prepare your feed.
3
Description of the all fields in Real Estate Home listings Catalog.
  • Country specific fields
  • Feed XML example
  • 4

    Step 1: Catalog Setup

    To create a Catalog for Facebook Marketplace, you need a Business Manager account and permission to manage it. If you're new to Facebook business, you may need to set up Business Manager first from https://business.facebook.com/

    Create a Real Estate catalog using the Product Catalog UI
    1. Go to Catalog Manager (https://www.facebook.com/products).
    2. Click [Create Catalog].
    3. Select the catalog type [Real estate - Home Listings] and click Next.
    4. Select Select the business your catalog belongs to and enter a name for your catalog.

    Step 2: Best Practices

    The catalog will contain information for properties such as listing id, name, availability, description, address, bedrooms, bathrooms, images and so on.
    Providing good quality listings is the key success factor for a good experience for Facebook Marketplace users with your partner branding. Poor quality or missing information in the catalog can be the cause of listings being rejected or warnings by the catalog tool.

    Best Practices and requirements

    • Listing file format has to be XML. See below for an example.
    • Send 2+ images per listing. Images should be high quality, and without watermarks or banners.
    • Marketplace only supports residential units for rent currently. (The feed should not contain offices, parking spots, garages, boxes, etc., but only residential houses, apartments, flats, condos, etc.)
    • Remove rich text tags in the description. Marketplace description will not support rich text format(HTML) and will trim the tags automatically.
    • Filter the listings that fall outside of the normal range of the price according to the market. (For example, 1$, less then 100$ or more than 100,000$.)
    • Please provide the full address (including street number and street name). The street number will not appear on the listing.
    • You can add up to 3 floorplan images. They must be provided in an image format (e.g. jpg, png), and they add up in the total count of 20 max images per listing. E.g. a listing can have 18 photos and 2 floorplans.
    • The coordinates (latitude, longitude) of the listings are not required. Anyway, without this information, the listing will only show in a list view and will not appear on the map view. We therefore recommend to include the full address information where possible to get the maximum discoverability.

    Step 3: Feed specs

    Listing Feed

    This is a set of listings uploaded or fetched from your business. A listing item is a single property presented in your website or app. You can have a single feed for all properties in your catalog, or you can have multiple feeds where one feed represents properties in a single country, for a single real estate agency, or for one broker.

    Feed file format: You must provide the listing feed in XML format.

    File FormatDescription

    XML

    Typically generated by automated feed provider systems. A root <listings> XML node encloses a set of <listing> nodes, each representing a home listing. The file must begin with a valid <?xml declaration tag.

    CSV, TSV, JSON

    These formats are not currently supported.

    Our feed parser automatically detects UTF8, UTF16 or UTF32 text-encodings, falling back to LATIN1 if unexpected byte sequences appear.

    Field names must be given exactly as below, in English, while text in field values can be given in any language.

    Basic fields

    NameTypeDescription

    home_listing_id

    string

    Required.

    Unique apartment/home/condo level id - most granular id possible.

    name

    string

    Required.

    Title of the listing.

    description

    string

    Required.

    Short text describing the property. This is a very important field, and it reflects the quality of the listings.

    • Don't include promotional text or any links;
    • Don't enter text in all capital letters;
    • HTML is not supported;
    • Use line breaks (\n, and not <br/>) to format your description.
    • Max 5000 characters are allowed.

    image

    array

    Required.

    Max 20 items - Max image size: 4MB.

    The first photo will be displayed on Marketplace as the cover image.

    In image, url

    string

    Required.

    A valid image URL.

    In image, tag

    enum

    Optional.

    Used to set the role of the image

    Allowed values:

    only floorplan. Max for 3 images.

    num_beds

    float

    Required.

    The total number of bedrooms. It can be 0 for Studios.

    num_baths

    float

    Required.

    The total number of bathrooms. It must be minimum 1.

    num_rooms

    float

    Required.

    The total number of rooms.

    property_type

    string

    Required.

    Type of property. Allowed values: apartment, builder_floor, condo, house, house_in_condominium, house_in_villa, loft, other, penthouse, studio, townhouse.

    listing_type

    string

    Required.

    Type of property. Allowed values: for_rent_by_agent, for_rent_by_owner.

    area_size

    int

    Required.

    The area / space of the floor plan of the listing.

    area_unit

    string

    Required.

    The units (square feet , or square meters) of the floor area value.

    Allowed values:sq_ft, sq_m.

    address

    object

    Required.

    A complete address for the listing that must be resolvable to its location.

    See Address Object Parameters.

    price

    string

    Required.

    Currency should follow ISO 4217 currency codes such as 13,999 USD.

    availability

    string

    Required.

    Whether or not the listing is available.

    Allowed value: for_rent.

    url

    string

    Required.

    Link to listing page. Must be a valid URL.

    Example: http://www.realestatecompany.com/example.

    Country specific required fields

    NameTypeDescription

    additional_fees_description

    string

    Required in FR, UK.

    Additional fees for the listing. Any text entered in this field will be rendered in a separated popup dialog, accessible via a "Fees apply" button displayed in the listing details page.

    Max length: 5000 characters.

    energy_rating_eu

    string

    The listing's energy rating. A grade and a value should be specified.

    Example: <grade>A</grade><value>123</value>


    If you don't have this information and would like to highlight "DPE Non communiqué" (or similar wording) you can add this to the description.

    co2_emission_rating_eu

    string

    The listing's CO2 emissions rating. A grade and a value should be specified.
    Example: <grade>A</grade><value>123</value>


    If you don't have this information and would like to highlight "DPE Non communiqué" (or similar wording) you can add this to the description.

    property_tax

    string

    Required in BR.

    Currency should follow ISO 4217 currency codes such as 1,999 USD.

    condo_fee

    string

    Required in BR.

    Currency should follow ISO 4217 currency codes such as 1,999 USD.

    parking_spaces

    int

    Required in BR.

    Number of parking places available.

    built_up_area_size

    int

    Required in IN.

    Additional area size field for India market to represent built up area size. area_size will represent carpet area size.

    Optional fields

    The following fields are optional but recommended. The more fields completed with structured information about the listings, the higher the quality of listings.

    NameTypeDescription

    home_listing_group_id

    string

    Optional.

    Adding the same group ID to two or more listing will create a multi-listing. Group ID is an arbitrary string you can choose to uniquely identify the group. This field is intended to organize multiple listings into one, e.g. condos, or more in general, different flats in the same building.

    Multi-listings support different prices and features, e.g. different number of rooms.

    See an example of multi-listing.

    num_units

    int

    Optional.

    The total number of units in the building (if applicable).

    agent_id

    string

    Optional.

    Unique per agent. The id of the agent.

    agent_name

    string

    Optional.

    The listing agent's name.

    Example: John Smith .

    agent_company

    string

    Optional.

    The listing agent's company name.

    Example: Real Estate Properties .

    agent_phone

    string

    Optional.

    The listing agent's phone number. Must be a valid phone number format, and must include the country code. When this field is populated, a "Call" button is shown the listing detail page.

    Example: +13603453333, 001(360)345-3333.

    agent_fb_page_id

    string

    Optional.

    The listing agent's Facebook Page ID.

    latitude

    float

    Optional.

    The latitude of the listing. Example: 37.484100

    latitude

    float

    Optional.

    The longitude of the listing. Example: -122.148252

    neighborhood

    string

    Optional.

    Listing neighborhood. Can have multiple items - Max 20 items.

    furnish_type

    string

    Optional.

    Type of furniture present in the property. Allowed values: furnished, semi-furnished,unfurnished.

    heating_type

    string

    Optional.

    Type of heating present in the property. Allowed values: central,gas,electric,radiator,other,none.

    ac_type

    string

    Optional.

    Type of air conditioning. Allowed values: central, other,none.

    laundry_type

    string

    Optional.

    Type of laundry. Allowed values: in_unit,in_building, other,none.

    parking_type

    string

    Optional.

    Type of parking. Allowed values: garage,street,off-street, other,none.

    pet_policy

    string

    Optional.

    To indicate which pets are allowed in the listing.

    Allowed values: cat, dog, all, none.

    year_built

    string

    Optional.

    YYYY format, 4 digit year.

    Example: 1994.

    partner_verification

    string

    Optional.

    Whether your company has verified the listing.

    Allowed values: verified, none.

    num_pets_allowed

    int

    Optional.

    The number of cats/dogs allowed

    security_deposit

    string

    Optional.

    The security deposit.

    Example: 300 USD

    holding_deposit

    string

    Optional.

    The holding deposit.

    Example: 300 USD

    application_fee

    string

    Optional.

    The application fee.

    Example: 300 USD

    pet_deposit

    string

    Optional.

    The pet deposit. Example: 300 USD

    pet_monthly_fee

    string

    Optional.

    The pet monthly fee.

    Example: 300 USD

    unit_features

    string

    Optional.

    The unit features. Allowed values: air_conditioner, balcony, basement, bike_parking, cable_tv, ceiling_fan, concierge_service, dishwasher, doorman, elevator, fireplace, fitness, furnished, garbage_disposal, laundry, microwave, online_application, oven, package_service, parking, patio, pet_park, refrigerator, resident_lounge, roof_deck, secured_entry, storage, swimming_pool, walk_in_closet, wheelchair_access.

    pet_restrictions

    string

    Optional.

    Pet restrictions. Allowed values: breed_restrictions, size_restrictions, other.

    floor_types

    string

    Optional.

    Floor types. Allowed values: carpet, concrete, hardwood, laminate, tile.

    rent_free_weeks

    string

    Optional.

    Rent free weeks. Allowed values: free_move_in_service, rent_free_weeks, other.

    Address Object Parameters

    NameTypeDescription

    addr1

    string

    Required.

    Street address of the property.

    Example: 675 El Camino Real

    city

    string

    Required.

    City where the property is located.

    Example: Palo Alto

    region

    string

    Required.

    State, county, region or province for the property.

    Example: California

    country

    string

    Required.

    Country of the property.

    Example: United States

    postal_code

    string

    Required unless country doesn't have postal code system.

    Postal or zip-code of the the property.

    Example: 94125, NW1 3FG

    Feed XML example

    <?xml version="1.0" encoding="UTF-8"?>
    <listings>
        <title>example.com Feed</title>
        <link rel="self" href="http://www.example.com"/>
        <listing>
            <home_listing_id>12345678</home_listing_id>
            <name>1 Hacker Way, Menlo Park, CA 94025</name>
            <availability>for_rent</availability>
            <description>An amazing listing</description>
            <address format="simple">
                <component name="addr1">1 Hacker Way</component>
                <component name="city">Menlo Park</component>
                <component name="region">California</component>
                <component name="country">United States</component>
                <component name="postal_code">94025</component>
            </address>
            <latitude>1.11414</latitude>
            <longitude>-1.835003</longitude>
            <neighborhood>Menlo Oaks</neighborhood>
            <image>
                <url>http://example.com/12345678-1.jpg</url>
            </image>
            <image>
                <url>http://example.com/12345678-2.jpg</url>
            </image>
            <image>
                <url>http://example.com/12345678-3.jpg</url>
                <tag>floorplan</tag>
            </image>
            <unit_features_>air_conditioner</unit_features>
            <unit_features_>bike_parking</unit_features>
            <listing_type>for_rent_by_agent</listing_type>
            <num_baths>6</num_baths>
            <num_beds>5</num_beds>
            <num_units>1</num_units>
            <price>110000 USD</price>
            <property_type>house</property_type>
            <url>http://www.example.com/link_to_listing</url>
            <year_built>2007</year_built>
        </listing>
    </listings>

    Step 4: Upload Catalog Data Feed

    You can refresh home listing info in the catalog by setting up a recurring (scheduled) feed upload and updating your feed. In Marketplace, we highly recommend to use the Set a Schedule option.

    Set a schedule for your catalog data feed upload

    1. Go to Catalog Manager.
    2. Click Data Sources.
    3. Click Add Data Source.
    4. Click Use Data Feeds and click Next.
    5. Click Set a schedule.
    6. Choose how frequently you want Facebook to check your data feed for updates.
      You can choose Daily, Hourly and Weekly. If you choose Hourly or Weekly as your frequency, you can also specify when your scheduled upload repeats.
    7. Enter the direct URL for your feed. You can use URLs that use http, https, ftp or sftp. Note: The URL should point directly to your data feed file; otherwise, the upload may fail.
    8. (Optional) Enter the username and password for the data feed provider. This is different than the username and password you use to access your Facebook ad account.
    9. Enter a name for your data feed.
    10. Choose the currency type for your data feed. The currency type is used for your data feed if you don't specify it in your data feed file.
    11. Click Next.
    12. Review your data feed file for any errors. If you're missing any required columns in your file, or there are columns that Facebook doesn't recognize, you can map them to the appropriate columns here. Any columns mapped here are saved for future data feed uploads.
    13. Click Next.

    Update Inventory in Real-time

    Your app must have the ads_management permission reviewed in order to make changes to the catalog via the API.

    The System User (owner of the token) must be admin of the catalog that you will be changing via the API. The token must have the ads_management scope granted.

    Read the Catalog Batch API documentation.

    To update or delete products more frequently than the periodic fetches, the Catalog Batch API may be used to perform real-time updates to individual products using retailer IDs. Any updates made through the Catalog Batch API should also be reflected in the product feed so that the updates are preserved after it is next fetched.

    The Batch API does not provide error information in as much detail as the Feed API. Use Feed Upload errors as the source of truth.

    Appendix: Multi language feed upload

    Marketplace Real Estate supports multi language experience. When you add secondary language feed to a catalog, you can create another feed with the second language from that single catalog. The information on the secondary feeds overrides your default language when the relevant audience sees your listings.

    This feature will be applicable only for the specific country partners. Please contact to your Facebook representative to find out possibility in your market.

    1. Create a catalog with a data feed for your default language and country.
    2. Create an XML file only with the listing ID (home_listing_id) and additional fields that required local language overwrite like name, description or additional fields
      * To overwrite information, the home_listing_id must match the ones in your original catalog data feed.
    3. Add the additional information feed from the Catalog manager.

      Add the additional feed from the Catalog manager [Add Home Listing Information] - [Add Language Information]


    4. Double check the 2 data sources within the same catalog.

    Full error reporting / Catalog debugging

    This functionality is in beta.

    There is an API that allows you to download the full report of your catalog errors. Check the question "How can I see the full error list of my catalog?" in our FAQ list for more details.

    Need help?

    You can contact Facebook's Support team any time you have questions.

    Contact us