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.

    Catalog

    • You should create only one catalog for all your listings. Please avoid creating separate catalogs for each agency.
    • The feed file format has to be XML. It can be compressed (zip, gzip and bz2) to save time while uploading. See below for an example.
    • Set up a scheduled feed upload with a suggested setting of 24 hours interval. If you need more frequent updates, you can see more detailed instructions below.

    Listings

    • Send at least two high quality images – without watermarks or banners.
    • Remember that Marketplace only supports residential properties – so listings shouldn’t include offices, garages, parking bays etc.
    • Remove all rich text tags from descriptions as Marketplace doesn’t support rich text formats (e.g. HTML) and will trim tags automatically.
    • Include up to three floorplans, in an image format like JPEG or PNG, as part of the total of 20 images allowed per property.
    • Please provide your full address details, including street name and house number (the house number will not appear in the listing).
    • Provide coordinates for longitude and latitude to make sure properties can be easily located on the map view.
    • Poor quality listings may be rejected – or warnings issued by the catalogue tool.

    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:
    • floorplan. Max for 3 images.
    • agentLogo. Max for 1 image.

    property_type

    string

    Required.

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

    listing_type

    string

    Required.

    Allowed values: for_rent_by_agent, for_rent_by_owner.

    address

    object

    Required.

    City and postcode are basic minimum requirements. If the full address is provided, which is recommended, the listing will be discoverable on the map view. if the address is not provided in full, the listing will be only discoverable in list view.

    See Address Object Parameters.

    price

    string

    Required.

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

    availability

    string

    Required.

    Only allowed value: for_rent.

    url

    string

    Required.

    Link to listing page. Must be a valid URL.

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

    num_beds

    float

    Optional.

    The total number of bedrooms. It can be omitted or set to 0 for Studios.

    num_baths

    float

    Optional.

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

    num_rooms

    float

    Optional.

    The total number of rooms.

    Country specific required fields

    NameTypeDescription

    additional_fees_description

    string

    FR, UK specific.

    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.


    Please include all necessary information regarding the price and associated fees/charges (in FR, "honoraires") e.g. the amount of estate agency fees including taxes, the percentage of real estate agency fees including taxes, fees charged to buyer or seller or both.


    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

    virtual_tour_url

    string

    Optional

    3D virtual tour URL. Limited virtual tour providers supported: Matterport.

    Example: https://3dprovider.com/tourid.

    home_listing_group_id

    string

    Optional.

    use this field If you have multiple units in one property or building and would like to group them as one listing. To do this add the same group ID to these listings. The grouped listing will show the different units e.g. different prices/number of bedrooms.

    See an example.

    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.

    area_size

    int

    Optional.

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

    area_unit

    string

    Optional.

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

    Allowed values: sq_ft, sq_m.

    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.

    available_date

    string

    Optional.

    The date since the property is (or will be) available. Format: YYYY-MM-DD.

    video

    array

    Optional.

    In video, url

    string

    Required in video nodes.

    A valid video URL. The URL must be accessible without requiring authentication. The videos can be stored in an external storage service and also Vimeo download links are supported. The supported formats are the same as the Graph API supports. A list of supported formats can be found here.

    In video, tag

    enum

    Required in video nodes.

    Used to set the role of the video

    Allowed values:

    preRecordedVideo

    Home Sales specific fields

    NameTypeDescription

    listing_type

    string

    Required.

    Type of seller.

    Allowed values: for_sale_by_agent, for_sale_by_owner.

    availability

    string

    Required.

    Listing availability.

    Allowed value: for_sale.

    sale_type

    string

    Optional.

    Type of sale.

    Allowed value: new, resale, former.

    construction_status

    string

    Optional.

    Construction status of property.

    Allowed value: under_construction, ready_to_move, pre_release, release.

    tenure_type

    string

    Optional.

    Tenure type of property.

    Allowed value: freehold, leasehold, cooperative, power_of_attorney, strata_title.

    garden_type

    string

    Optional.

    Whether or not the listing has a garden.

    Allowed values: garden, none.

    parking_type

    string

    Optional.

    Type of parking.

    Allowed values: garage, none, off-street, street, other.

    fee_schedule_url

    string

    Optional.

    The external link to the Agency Fee Schedule. The input should be a url.

    This link will appear within the “Fees Apply” or “Frais applicable” pop-up beside the price on the PDP.

    coownership_status

    string

    Optional.

    Whether or not this is a co-ownership property. Allowed values: is_coownership or is_not_coownership.

    coownership_num_lots

    int

    Optional.

    The number of lots in the co-ownership.


    Must be greater than 0.

    coownership_proceedings_status

    string

    Optional.

    Whether or not proceedings are underway.


    Allowed values: has_proceedings or no_proceedings.

    coownership_charge

    string

    Optional.

    Annual running charges. Value expressed in euro per year.


    Example: <coownership_charge>1,000 EUR</coownership_charge>

    agent_rera_id

    string

    Optional.

    Agent RERA ID for India

    property_rera_id

    string

    Optional.

    Property RERA ID for India

    Address Object Parameters

    NameTypeDescription

    addr1

    string

    Optional.

    If the full address is provided, which is recommended, the listing will be discoverable on the map view. If the address is not provided in full, the listing will be only discoverable in list view.

    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>agentLogo</tag>
            </image>
            <image>
                <url>http://example.com/12345678-4.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