Getting Started

For commerce catalogs, to publish Real Estate listings, your business needs to be verified.

Step 1: Create a Home Listing catalog.

Step 2: Set up listing and pricing.

Step 3: Update options.

Step 4: Filter listing catalog to listing set.

Step 5: Send Offline Conversions (Optional)

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 Dynamic Ads Debugging Tools.

Step 1: Create a Home Listing Catalog

For Dynamic Ads

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

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

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

To create a catalog for commerce, 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.
  2. Click Create Catalog.
  3. Select the catalog type [Real estate - Home Listings] and click Next.
  4. Select the business your catalog belongs to and enter a name for your catalog.


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 dynamic ads, you must provide the listing feed in one of these formats:

File FormatDescriptionSample 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 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.

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>

Real Estate Supported Fields

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 TypeDescription

home_listing_id

type: string

Required for dynamic 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 dynamic ads. Optional for commerce.

Building or apartment's unique ID. Must be unique per group.

name

type: string

Required for dynamic ads and commerce.

Title of home listing. Example: Modern Eichler in Green Oaks

availability

type: string

Required for dynamic 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 dynamic 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 dynamic ads and commerce.

City where the property is located.

See Address Object Parameters.

Example: Menlo Park

address.region

type: string

Required for dynamic ads and commerce.

State, county, region, or province for the property.

See Address Object Parameters.

Example: Menlo Park

address.country

type: object

Required for dynamic ads and commerce.

Country where the property is located.

See Address Object Parameters.

Example: United States

address.postal_code

type: string

Required for dynamic ads and commerce.

Country where the property is located.

See Address Object Parameters.

Example: United States

latitude

type: float

Required for dynamic ads and commerce.

Latitude of the listing.

Example: 37.484100

longitude

type: float

Required for dynamic ads and commerce.

Longitude of the listing.

Example: -122.148252

neighborhood

type: string

Required for dynamic 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 dynamic 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 dynamic 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 dynamic 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 dynamic ads. Required for commerce.

Max characters: 5000

Description of the property.

Example: Beautiful 3BD home available in Belmont

num_beds

type: float

Optional for dynamic ads. Required for commerce.

Total number of bedrooms. Can be 0 for Studios.

Example: 2

num_baths

type: float

Optional for dynamic ads.

Total number of bathrooms. For commerce, must be 1 at minimum.

num_rooms

type: float

Not applicable for dynamic ads. Required for commerce.

Total number of rooms of property.

property_type

type: string

Optional for dynamic ads.

Type of property. Supported values for dynamic 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 dynamic ads.

Type of property listing. Supported values for dynamic 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 dynamic ads. Required for commerce.

Area or space of the floor plan's listing.

area_unit

type: string

Not applicable for dynamic 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 dynamic ads. Optional for commerce.

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

furnish_type

type: string

Not applicable for dynamic ads. Optional for commerce.

Type of furniture available in the property. Supported values: furnished, semi-furnished,unfurnished.

heating_type

type: string

Not applicable for dynamic 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 dynamic ads. Optional for commerce.

Type of laundry available. Supported values: in_unit,in_building, other,none.

num_units

type: int

Optional for dynamic ads and commerce.

Total number of units (apartments, condos) available for rent.

Example: 0

parking_type

type: string

Not applicable for dynamic 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 dynamic 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 dynamic 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.

Country-Specific Required Fields — Commerce Only

These country-specific required fields apply to commerce only.

NameDescription

additional_fees_description

type: string

Required in France (FR) and United Kingdom (UK).

Max length: 5000 characters

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.

energy_rating_eu

type: 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

type: 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

type: string

Required in Brazil (BR).

Format property tax 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: 1,999 USD

condo_fee

type: string

Required in Brazil (BR).

Format condo fee 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: 1,999 USD

parking_spaces

type: int

Required in Brazil (BR).

Number of parking places available.

built_up_area_size

type: int

Required in India (IN).

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

Image Object Parameters


Field Name and TypeDescription

url

type: string

Required for dynamic ads and commerce.

Image source URL. To use carousel ads, provide a square 1:1 aspect ratio images of at least 600x600px. To show single image ads, use images with a 1.91:1 aspect ratio image of at least 1200x630px.

tag

type: string

Optional for dynamic 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 TypeDescription

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 TypeDescription

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",
    },
]

Step 3: Update Options

Dynamic Ads

For dynamic 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:

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

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

Multi-language 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.

  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. 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 dynamic ad. Each listing catalog can have many listing sets.

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:

OperatorsType 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)

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

KeyDescription

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.

FieldDescription

content_ids

home_listing_id from the catalog upload

content_type

Set to APARTMENT

Event Details

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

FieldDescription

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