Syndication

This page outlines the steps for utilizing Foyer's syndication service

The Foyer syndication system allows you to receive changes to followed listings. The api endpoints are outlined in detail below. You can elect to receive realtime notifications, as outlined below, or use our refreshAllListings endpoint to check for updates as desired.

Push Notifications

In order to receive realtime notifications of changes to listings available to your account, we require a URL of the form api.mycompany.com/foyerNotify that accepts a query parameter of listing=https://api.foyer.ai/reports/:reportId/exportReso The URL provided to your system in the query parameter can then be used to make a network request back to our server for the listing data in standard RESO format.

Make sure to include your valid authorization token in the request header when querying our exportReso endpoint. See Authorization in the sidebar for more details

You can provide your notification URL during sign-up as the notify body parameter or at a later time using the updateNotify endpoint outlined below.

post
Publisher Sign Up

https://api.foyer.ai/accounts/publisherSignUp
This method is used for a publisher to sign up to receive syndication notifications. This method returns an authorization token in the response header. Additional tokens can be generated by using the login method, see Authorization in the sidebar for more details.
Request
Response
Request
Body Parameters
email
required
string
The email to be associated with the account
password
required
string
The password used for authorization
confirmPassword
required
string
The password again for confirmation
notify
optional
string
The url for receiving notifications about changes to available listings
website
optional
string
A website for the organization associated with the account
logo
optional
string
An image url for the organization associated with the account
Response
200: OK
The authentication token will be present in the response header

Be sure to save the authorization token in the response header and include it when making API requests.

post
Publisher Update Notification URL

https://api.foyer.ai/publishers/updateNotify
This method is used to update the push notification URL for your account. A valid authorization token is needed to make sure the correct account is updated.
Request
Response
Request
Headers
Authorization
required
string
Authorization token
Body Parameters
notify
required
string
The url for receiving notifications about changes to available listings
Response
200: OK
The request was successful and push notifications will now be directed to the provided URL

get
Get a listing in RESO format

https://api.foyer.ai/reports/:reportId/exportReso
This endpoint allows you to receive all listing details in standard RESO format
Request
Response
Request
Path Parameters
reportId
optional
string
id for the desired listing
Headers
Authorization
required
string
Authorization token
Response
200: OK
Listing successfully exported. Example below is not an exhaustive list of available fields
{
"ListingKey": "3yd-A2SELL-281884",
"ListingId": "281884",
"PropertyType": "Land",
"PropertySubType": "Other",
"ListPrice": 21900,
...
"Media": [
{
"MediaCategory": "Photo",
"MediaURL": "http://photos.listhub.net/A2SELL/281884/1", // required
"MediaKey": "2483763c0011d2a36483fb3f28ca8c00564abb4d",
"MediaModificationTimestamp": "2019-10-03T09:14:00.000Z"
},
...
]
}
401: Unauthorized
When no valid authorization header is present
{
"statusCode":401,
"error":"Unauthorized",
"message":"Missing authentication"
}
403: Forbidden
When valid header is present but account does not have read permission for this listing
{
"statusCode": 403,
"error": "Forbidden",
"message": "Forbidden"
}

See the Data Dictionary for more information on RESO format

get
Refresh all listings

https://api.foyer.ai/publishers/refreshAllListings
This method is used for receiving an array of exportReso urls that can be used to update all listings available for one's own account.
Request
Response
Request
Headers
Authorization
required
string
Authorization token
Response
200: OK
[
"https://api.foyer.ai/reports/1/exportReso"
"https://api.foyer.ai/reports/2/exportReso"
]