Step 6: Build your Audience for Real Estate. Differently from what happens with real estate listings published by users, for partner integrations, leads are sent to partners via lead form, rather than via Messenger chat. Learn more about Retrieving Leads for commerce.

Step 7: Create and deliver ads for your home listings.

Step 8: Get delivery information to see how people on Facebook are engaging in you ads. See Ads Insights.

Step 9: Use debugging tools to diagnose and resolve problems. See Advantage+ Catalog Ads Debugging Tools.

Step 1: Create a Home Listing Catalog

For Advantage+ Catalog Ads

Your catalog should contain a list of properties that you want to advertise. See Catalog Reference.

To create a home listing catalog for Advantage+ catalog ads, set vertical to home_listings:

Select language

curl \
  -F 'name=Home Listing Catalog Name' \
  -F 'vertical=home_listings' \
  -F 'access_token=<ACCESS TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_product_catalogs

To use the catalog API, you need Marketing API Access Level and accept the Terms of Service⁠ by creating your first catalog through Business Manager⁠.

For commerce

For instructions on how to create a catalog for commerce, visit the Marketplace Platform documentation.

Step 2: Set Up Listing and Prices

Your listing contains information for properties, such as listing ID, name, availability, description, address, bedrooms, bathrooms, and so on. You can have a set of listings uploaded or fetched from your business. A listing item is a single property presented in your website or app.

Supported Feed Formats

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.

For Advantage+ catalog ads, you must provide the listing feed in one of these formats:

File Format	Description	Sample File
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.	Download⁠
CSV, TSV	The first row must list the chosen field names in the order the values will be given. Subsequent rows then supply the corresponding values for each home listing. Nested or multi-value fields such as image can be represented using JSON-encoded values or by a set of “flattened” plain-text columns labeled using JSON-path syntax, such as `image[0].url`, `image[0].tag[0]`, `image[0].tag[1]`.	Download⁠ (CSV)

For commerce, you must provide the listing feed in XML format:

File Format	Description
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.

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>
        </image>
        <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>

Supported Fields - Home Listings

The following supported fields are designed for items you add to your product catalog. For a complete list of supported fields, see the Home Listing reference.

For localized catalogs, see supported fields for home listings.

Our feed parser automatically detects UTF8, UTF16 or UTF32 text-encodings, falling back to LATIN1 if unexpected byte sequences appear. While text in field values can be given in any language, field names must be given exactly as below, in English.

Field Name and Type	Description
`home_listing_id` type: string	Required for Advantage+ catalog ads and commerce. Unique home (apartment/condo) listing ID; most granular ID possible. Example: `FB_home_1234`
`home_listing_group_id` type: string	Not applicable to Advantage+ catalog ads. Optional for commerce. Building or apartment’s unique ID. Must be unique per group.
`name` type: string	Required for Advantage+ catalog ads and commerce. Title of home listing. Example: `Modern Eichler in Green Oaks`
`availability` type: string	Required for Advantage+ catalog ads and commerce. Current availability for the home listing. Supported values are: `for_sale`, `for_rent`, `sale_pending`, `recently_sold`, `off_market`, `available_soon`. For commerce, the only supported value is ‘for_rent’.
`address` type: string	Required for Advantage+ catalog ads and commerce. Street address for the property that must be resolvable to its location. See Address Object Parameters. Example: `1 Hacker Way`
`address.city` type: string	Required for Advantage+ catalog ads and commerce. City where the property is located. See Address Object Parameters. Example: `Menlo Park`
`address.region` type: string	Required for Advantage+ catalog ads and commerce. State, county, region, or province for the property. See Address Object Parameters. Example: `Menlo Park`
`address.country` type: object	Required for Advantage+ catalog ads and commerce. Country where the property is located. See Address Object Parameters. Example: `United States`
`address.postal_code` type: string	Required for Advantage+ catalog ads and commerce. Country where the property is located. See Address Object Parameters. Example: `United States`
`latitude` type: float	Required for Advantage+ catalog ads and commerce. Latitude of the listing. Example: `37.484100`
`longitude` type: float	Required for Advantage+ catalog ads and commerce. Longitude of the listing. Example: `-122.148252`
`neighborhood` type: string	Required for Advantage+ catalog ads. Optional, but strongly recommended for commerce. Max neighborhoods allowed: 20 Listing neighborhood for the property. Can have multiple neighborhoods. If you have more than one neighborhood, add additional columns for each type and use JSON-path syntax in each column name to indicate the number of neighborhoods. Example: `neighborhood[0]; neighborhood[1]`
`price` type: string	Required for Advantage+ catalog ads and commerce. Sale or rental price of the property. Format price as the cost, followed by the [3-digit ISO currency code](https://en.wikipedia.org/wiki/ISO_4217?fbclid=IwAR0_xYfUmL3kIUA6sMeEaFAzbJa4MLeMiPDPrftFSX6wkKiTXxPinC-5j70”>, with a space between cost and currency. Example: `13,999 USD`
`image` type: object	Required for Advantage+ catalog ads and commerce. Maximum images: 20 Maximum size: 4 MB The URL for the image used in your ad. For square (1:1) aspect ratios in the carousel ad format, your image should be 600x600. For single image ads, your image should be at least 1200x630 pixels. For commerce, The first photo is displayed in the commerce feed as the cover image. Example: `image[0].url`, `image[0].tag[0]` See Image Object Parameters.
`url` type: string	Required for Advantage+ catalog ads and commerce. Link to the property listing page. Must be a valid URL. See Image Object Parameters. Example: `http://www.realestate.com`
`description` type: string	Optional for Advantage+ catalog ads. Required for commerce. Max characters: 5000 Description of the property. Example: `Beautiful 3BD home available in Belmont`
`num_beds` type: float	Optional for Advantage+ catalog ads. Required for commerce. Total number of bedrooms. Can be `0` for Studios. Example: `2`
`num_baths` type: float	Optional for Advantage+ catalog ads. Total number of bathrooms. For commerce, must be `1` at minimum.
`num_rooms` type: float	Not applicable for Advantage+ catalog ads. Required for commerce. Total number of rooms of property.
`property_type` type: string	Optional for Advantage+ catalog ads. Type of property. Supported values for Advantage+ catalog ads: `apartment`, `condo`, `house`, `land`, `manufactured`, `other`, `townhouse`. Supported values for commerce: `apartment`, `builder_floor`, `condo`, `house`, `house_in_condominium`, `house_in_villa`, `loft`, `penthouse`, `studio`, `townhouse`, `other`.
`listing_type` type: string	Optional for Advantage+ catalog ads. Type of property listing. Supported values for Advantage+ catalog ads: `for_rent_by_agent`, `for_rent_by_owner`, `for_sale_by_agent`, `for_sale_by_owner`, `foreclosed`, `new_construction`, `new_listing`. Supported values for commerce: `for_rent_by_agent`, `for_rent_by_owner`.
`area_size` type: int	Not applicable for Advantage+ catalog ads. Required for commerce. Area or space of the floor plan’s listing.
`area_unit` type: string	Not applicable for Advantage+ catalog ads. Required for commerce. The units (square feet or square meters) of the floor area’s value. Supported values: `sq_ft`, `sq_m`.
`ac_type` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Type of air conditioning. Supported values: `central`, `other`,`none`.
`furnish_type` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Type of furniture available in the property. Supported values: `furnished`, `semi-furnished`,`unfurnished`.
`heating_type` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Type of heating installed in the property. Supported values: `central`,`gas`,`electric`,`radiator`,`other`,`none`.
`laundry_type` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Type of laundry available. Supported values: `in_unit`,`in_building`, `other`,`none`.
`num_units` type: int	Optional for Advantage+ catalog ads and commerce. Total number of units (apartments, condos) available for rent. Example: `0`
`parking_type` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Type of parking available on property. Supported values: `garage`,`street`,`off-street`, `other`,`none`.
`partner_verification` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Whether the partner company has verified the listing. Supported values: `verified`, `none`.
`year_built` type: string	Year the property was built, using the YYYY format, 4 digit year. Example: 1994.
`pet_policy` type: string	Not applicable for Advantage+ catalog ads. Optional for commerce. Indicates the pets allowed on the property: `cat`, `dog`, `all`, `none`.
`available_dates_price_config` type: object	List of dates and prices that a listing is available. When you provide values, Facebook can recommend listings based on their available dates and dynamically show the associated price in your ad. See Available Dates Object Parameters
`applink` type: object	App link to listing.
`status` Type: string	Controls whether an item is active or archived in your catalog. Only active items can be seen by people in your ads, shops or any other channels. Supported values: `active`, `archived`. Items are active by default. Learn more about archiving items⁠. Example: `active` Note: Some partner platforms such as Shopify may sync items to your catalog with a status called staging, which behaves the same as `archived`. This field was previously called `visibility`. While we still support the old field name, we recommend that you use the new name.

Country-Specific Required Fields — Commerce Only

Visit the Marketplace Platform documentation for commerce country-specific required fields.

Image Object Parameters

Field Name and Type Description

Field Name and Type	Description
`url` type: string	Required for Advantage+ catalog ads and commerce. Image source URL. Follow these image specifications: All images must be in JPG, GIF, or PNG format. For carousel ads and collection ads: Images display in square (1:1) format. The minimum image size is 500 x 500 px. We recommend 1024 x 1024 px for best quality. For single image ads: Images display at a 1.91:1 aspect ratio. The minimum image size is 500 x 500 px. We recommend 1200 x 628 px for best quality.
`tag` type: string	Optional for Advantage+ catalog ads and commerce. Tag appended to the image that shows what’s in the image. There can be multiple tags associated with an image. Examples: `Fitness Center`, `Swimming Pool` `INSTAGRAM_STANDARD_PREFERRED` - Allows advertisers to tag a specific image in their feed as the default image that will be used for Instagram. This tag is case sensitive.

url

type: string

Required for Advantage+ catalog ads and commerce.

Image source URL. Follow these image specifications:

All images must be in JPG, GIF, or PNG format.

For carousel ads and collection ads: Images display in square (1:1) format. The minimum image size is 500 x 500 px. We recommend 1024 x 1024 px for best quality.

For single image ads: Images display at a 1.91:1 aspect ratio. The minimum image size is 500 x 500 px. We recommend 1200 x 628 px for best quality.

tag

type: string

Optional for Advantage+ catalog ads and commerce.

Tag appended to the image that shows what’s in the image. There can be multiple tags associated with an image.

Examples: Fitness Center, Swimming Pool

INSTAGRAM_STANDARD_PREFERRED - Allows advertisers to tag a specific image in their feed as the default image that will be used for Instagram. This tag is case sensitive.

Address Object Parameters

Field Name and Type	Description
`addr1` type: string	Required. Street address of hotel. Example: `675 El Camino Real`
`city` type: string	Required. City where hotel is located. Example: `Palo Alto`
`region` type: string	Required. State, county, region or province for hotel. Example: `California`
`country` type: string	Required. Country of the hotel. Example: `United States`
`postal_code` type: string	Postal or zip-code of the property. Required unless country does not have a postal-code system. Examples: `94125`, `NW1 3FG`

Available Dates Price Config

With available_dates_price_config, you can provide the availability and prices of each property for a given date range. When you include date ranges in this field, Facebook factors this availability into our product recommendations and tries to show listings that are available for the dates someone searched on your site. Optionally, if you include pricing we can also show date-specific prices in your ad creative. To enable this feature, you must also send Facebook lease_start_date and lease_end_date in your pixel events.

Available Dates Object Parameters

Field Name and Type	Description
`start_date` type: string	Optional if `end_date` is provided. Start of the available date range in ISO-8601 format; inclusive of the start date. If you only provide `start_date`, `end_date` defaults to a year from that date. Example: `YYYY-MM-DD`, such as `2018-01-01`.
`end_date` type: string	Optional if `start_date` is provided. End of the available date range in ISO-8601 format; excludes the end date. If you only provide `end_date`, `start_date` defaults to the current date. Example: `YYYY-MM-DD`, such as `2018-02-01`.
`rate` type: string	Integer price of the listing during this time range. Example: `10000` if the listing was `$100.00 USD`
`currency` type: string	Required if you provide `rate`. ISO-4217⁠ currency code. Example: `USD`, `GBP`, etc.
`interval` type: string	Length of stay for the specified rate. Allowed values are: `nightly`, `weekly`, `monthly`, `sale`.

This is an example of a listing’s availability and how it appears in JSON:

"available_dates_price_config": [
    {
        // available until 11/01 at $150/night
        "end_date": "2018-11-01",
        "rate": "15000",
        "currency": "USD",
        "interval": "nightly",
    },
    {
        // available from 11/01 - 12/01 at $200/night
        "start_date": "2018-11-01",
        "end_date": "2018-12-01",
        "rate": "20000",
        "currency": "USD",
        "interval": "nightly",
    },
    {
        // available from 11/01 onward at $500/week
        "start_date": "2018-11-01",
        "rate": "50000",
        "currency": "USD",
        "interval": "weekly",
    },
]

Product Deep Links

Provide deep links in feed following the App Links specification. Deep link information in feed takes precedence over any information Facebook collects with App Links metadata with our web crawler.

If you already have deep link information from App Links, you don’t need to specify this data. Facebook uses information from App Links to display the correct deep link. To display deep links in your ads, see Advantage+ Catalog Ads, Ad Template.

Step 3: Update Options

Advantage+ Catalog Ads

For Advantage+ catalog ads, you can refresh home listing info in the catalog through the following ways with direct upload. See Direct Upload Feed Reference

Example — You can manually do a one-time upload:

Select language

  curl \
-F "url=http://www.example.com/sample_feed.xml" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_FEED_ID>/uploads

Commerce

For commerce, 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

Go to Commerce Manager⁠.

Click Data Sources.

Click Add Data Source.

Click Use Data Feeds and click Next.

Click Set a schedule.

Choose how frequently you want Facebook to check your data feed for updates: Daily, Hourly ,and Weekly. If you choose Hourly or Weekly as your frequency, you can also specify when your scheduled upload repeats.

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.

(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.

Enter a name for your data feed.

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.

Click Next.

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.

Click Next.

Multilanguage Feed Upload

Commerce supports a multilanguage experience. When you add a 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 is applicable only for the specific country partners. Please contact to your Facebook representative to find out possibility in your market.

Create a catalog with a data feed for your default language and country.

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.

Add the additional information feed from the Commerce Manager.

Add the additional feed from the Commerce Manager [Add Home Listing Information] - [Add Language Information]

Confirm the 2 data sources within the same catalog.

Step 4: Filter Listing Catalog to Listing Set

This is a group of items in a catalog that you advertise in your Advantage+ catalog ads. Each listing catalog can have many listing sets.

Select language

  curl \
-F "name=test set" \
-F 'filter={"availability":{"eq":"for_sale"}}' \
-F "access_token=" \
https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/product_sets

The above filter is made up of the following operators and data:

Operators	Type of filter
`i_contains`	Contains substring (case insensitive)
`i_not_contains`	Does not contain substring (case insensitive)
`contains`	Contains substring (case sensitive)
`not_contains`	Does not contain substring (case sensitive)
`eq`	Equal to (case insensitive)
`neq`	Not equal to (case insensitive)
`lt`	Less than (numeric fields only)
`lte`	Less than or equal to (numeric fields only)
`gt`	Greater than (numeric fields only)
`gte`	Greater than or equal to (numeric fields only)

Data	Data to filter
`availability`	Listing availability. Example: `for_sale`
`listing_type`	Listing type. Example: `for_sale_by_agent`
`property_type`	Property type. Example: `house`
`price`	Listing price
`name`	Name
`city`	City
`country`	Country
`region`	Region or state
`postal_code`	Postal code
`num_beds`	Number of beds
`num_baths`	Number of baths

Step 5: Send Offline Conversions

You can send offline conversion events and see how many customers viewed or clicked on Facebook ads and commerce listings before converting; use the Offline Conversions API and add the following fields in step 4. Upload Offline Events.

Match Keys

Match keys compare a conversion to a user.

Key	Description
`email`	Email address(es) Hash
`phone`	Phone number(s) Hash
`fn`	First name Hash
`ln`	Last name Hash
`madid`	Apple or Android advertising ID Hash
`zip`	ZIP code(s) Hash
`ct`	City Hash
`st`	State Hash
`country`	Country Hash
`dob`	Date of birth (DD format) Hash
`doby`	Date of birth (YYYY format) Hash
`gen`	Gender Hash
`age`	Age Hash
`lead_id`	Lead ID of Marketplace leads

Custom Data

Custom data compares a conversion to a dealer.

Field	Description
`content_ids`	`home_listing_id` from the catalog upload
`content_type`	Set to `home_listing`

Event Details

Event details describe the offline conversion event that took place. The upload frequency is daily, within 48 hours of the event.

Field	Description
`event_name`	Required Event type enum: `ViewContent` `Search` `AddToCart` `AddToWishlist` `Lead` = Had a phone call or other qualified lead `CompleteRegistration` = Appointment setup `InitiateCheckout` = Agency visit `AddPaymentInfo` = Property viewing `Purchase` = Lease signed `Other`
`event_time`	Required Time of the event
`value`	Required Rent value. Set to `0` for non-lease events.
`currency`	Required Currency code

Did you find this page helpful?