Webhooks

Webhooks allow you to subscribe to certain iGUIDE events. When an iGUIDE event is triggered, our backend sends an HTTP POST request to the webhook's configured URL. The request body is a valid JSON object representing the iGUIDE event.

Event Delivery

The event object is delivered in the body of a corresponding HTTP POST request.

If the receiving server has successfully processed the event, it should return an HTTP 2xx response. If the receiving server cannot process the event at the moment, it should return an HTTP 5xx response; the event will be re-sent later. If the receiving server returns any other HTTP response code (4xx, 3xx, etc.), the event will be silently dropped without re-attempting delivery.

If the receiving server has responded with HTTP 5xx, we will try to resend the event in 10-15 minutes. After the fifth failed attempt, we will stop trying to deliver the event.

Current Limitations

The current limitations are:

• The only supported event type is ready.
• There is no way to query events that were sent out.
• If your server was unavailable for some time, there is no way to know which events were sent during that time.
• iGUIDE webhook list can be modified by iGUIDE editors only.

Event Object Structure

The iGUIDE event object has the following structure:

Property	Type	Description
type	string	Event type.
	other JSON properties are populated based on type value.

Other different fields can be present in the object based on the event type value. This field set differs for various event types.

{
  "type": "<EVENT TYPE>",
  ... Other JSON fields specific to this event type ...
}

iGUIDE Ready Event

Once the iGUIDE data is uploaded and has been made publicly available, the ready event will trigger. Please note that the event may be sent multiple times (e.g. if there was a draft error and the iGUIDE data had to be re-uploaded).

Event Object

Property	Type	Description
type	string	Event type, it is set to ready.
iguideId	string	iGUIDE ID; an immutable value that never changes.
defaultViewId	string	iGUIDE's Default view Id; the value can change during iGUIDE life time.
iguideAlias	string	iGUIDE alias; the value can change during iGUIDE life time.
workOrderId	string	iGUIDE's current work order Id; the value can change during iGUIDE life time.
authtoken	string	Access token value. The token is valid for 3 weeks from the moment the event is issued. This value is required to access the private documents of an iGUIDE View. More details are provided in Access Tokens.
urls	URL Object	Common iGUIDE URLs
property	Property Object	Property information: address, coordinates, etc.
summary	Summary Object	Property summary: floor area values, room area/dimensions, etc.
billingInfo	BillingInfo Object	Billing information
banner	Banner Object	Banner information: company, email, phone, etc.

NOTE

A full sample of an iGUIDE Ready event object for https://youriguide.com/api-docs-sample is available at iguide-ready-event.json.

WARNING

The actual JSON object you receive may contain other properties not mentioned in this document. These properties are deprecated and are kept for backward compatibility only. Ignore any properties not present in this document, as they may be removed at any time without notice.

Example of iGUIDE Ready event object for https://youriguide.com/api-docs-sample

{
  "type": "ready",
  "iguideId": "igYGFV5GG6V8DD1",
  "iguideAlias": "api-docs-sample",
  "workOrderId": "WO1234",
  "urls": {
    "publicUrl": "https://youriguide.com/api-docs-sample/",
    "unbrandedUrl": "https://unbranded.youriguide.com/api-docs-sample/",
    "embeddedUrl": "https://youriguide.com/embed/api-docs-sample/",
    "manageUrl": "https://manage.youriguide.com/iguides/edit/igYGFV5GG6V8DD1",
    "media": {
      ...
    }
  },
  "property": {
    "fullAddress": "301 King St E, Kitchener, ON",
    "country": "CA",
    "postalCode": "N2G 2L3",
    "stateProvince": "ON",
    "city": "Kitchener",
    "streetName": "King St E",
    "streetNumber": "301",
    "location": {
      "lat": 43.447568,
      "lng": -80.484302
    }
  },
  "authtoken": "eyJhbGciOiJIUzI.eyJhY3Rpb24iOiJhY2Nlc3MtdmlldyI.tcz1uUYtL",
  "billingInfo": {
    ...
  },
  "summary": {
    ...
  },
  "banner": {
    ...
  },
}

Property Object

Property	Type	Description
fullAddress	string	Full property address (for Canada and US the country is omitted)
country	string	Country abbreviation according to ISO 3166.
city	string	City/town/village name
postalCode	string	Postal/ZIP code value
stateProvince	string	Province/state abbreviation according to ISO 3166
streetName	string	Street name
streetNumber	string	Street number
unit	string	Unit number
location	object	Coordinates
location.lat	number	Latitude
location.lng	number	Longitude

Example of Property object for https://youriguide.com/api-docs-sample

{
  "fullAddress": "301-301 King St E, Kitchener, ON",
  "country": "CA",
  "postalCode": "N2G 2L3",
  "stateProvince": "ON",
  "city": "Kitchener",
  "streetName": "King St E",
  "streetNumber": "301",
  "unit": "301",
  "location": {
    "lat": 43.447568,
    "lng": -80.484302
  }
}

BillingInfo Object

Property	Type	Description
iguideType	string	The package type. Possible values: standard -- Standard iGUIDE premium -- Premium iGUIDE radix -- Radix iGUIDE photos -- Photos-only iGUIDE auto-draft -- AutoDraft iGUIDE
addons	Array of string	Array of enabled add-ons (both paid and free). Possible values: vr, streetview, advmeas, floorplanner
billableAreaSqFeet	number	Billable area in square feet
billableAreaSqMeters	number	Billable area in square meters

Example of BillingInfo object for https://youriguide.com/api-docs-sample

{
  "iguideType": "standard",
  "addons": ["vr", "advmeas"],
  "billableAreaSqFeet": 4214.89137997613,
  "billableAreaSqMeters": 391.5762224695776
}

Banner Object

Property	Type	Description
fullName	string	Banner owner's name
title	string	Banner owner's title
company	string	Company name
phones	object	Array of banner's phone object
emails	Array of string	Array of banner's emails
website	string	Company's URL
socialLinks	object	Array of banner's social link object

WARNING

This object does not appear if its View does not have a banner.

Example of object for https://youriguide.com/api-docs-sample

{
  "fullName": "John Doe",
  "title": "Broker of Record",
  "company": "Test Brokerage",
  "phones":  [
    {
      "label":  "CEO",
      "number": "111-222-3333"
    },
    {
      "label":  "VP",
      "number": "111-222-4444"
    }
  ],
  "emails": [ "johndoe@brokerage.ca", "slee@planitar.com" ],
  "website": "http://www.brokerage.ca",
  "socialLinks": [
    {
      "label": "Facebook",
      "link": "https://www.facebook.com/realtorradio"
    },
    {
      "label": "Twitter",
      "link": "https://twitter.com/realtorradio"
    }
  ]
}

URL Object

Property	Type	Description
publicUrl	string	Public iGUIDE View URL
unbrandedUrl	string	Public iGUIDE View URL that is guaranteed to display it with no branding information
embdeddedUrl	string	Public iGUIDE View URL to be embedded in an iframe
manageUrl	string	URL to edit the iGUIDE View on iGUIDE Portal
mediaUrls	Localized Media URL Object	URLs to iGUIDE View Media: Gallery, PDF floor plans, SVG floor plans, etc

TIP

When an iGUIDE View is accessed via unbrandedUrl an unbranded version of iGUIDE Viewer is displayed to the user. That is, there is no agent branding info, no external video; the "Map" tab may also be hidden.

Example of URL object for https://youriguide.com/api-docs-sample

{
  "publicUrl": "https://youriguide.com/api-docs-sample/",
  "unbrandedUrl": "https://unbranded.youriguide.com/api-docs-sample/",
  "embeddedUrl": "https://youriguide.com/embed/api-docs-sample/",
  "manageUrl": "https://manage.youriguide.com/iguides/edit/igYGFV5GG6V8DD1",
  "mediaUrls": {
    "en": {
      "pdfImperial": "https://youriguide.com/api-docs-sample/doc/floorplan_imperial_en.pdf",
      "pdfMetric": "https://youriguide.com/api-docs-sample/doc/floorplan_metric_en.pdf",
      "galleryFrontImage": "https://youriguide.com/api-docs-sample/doc/front.image",
      "galleryLowResZip": "https://youriguide.com/api-docs-sample/doc/gallery-low-res.zip",
      "galleryZip": "https://youriguide.com/api-docs-sample/doc/gallery.zip",
      "offlineZip": "https://youriguide.com/api-docs-sample/doc/offline_en.zip",
      "sphereZip": "https://youriguide.com/api-docs-sample/doc/spheres.zip",
      "svgZip": "https://youriguide.com/api-docs-sample/doc/svg.zip",
      "dxfZip": "https://youriguide.com/api-docs-sample/doc/dxf_metric.zip",
      "embedImage": "https://youriguide.com/api-docs-sample/doc/embed_preview.jpg"
    },
    "fr": {
      "pdfImperial": "https://youriguide.com/api-docs-sample/doc/floorplan_imperial_fr.pdf",
      "pdfMetric": "https://youriguide.com/api-docs-sample/doc/floorplan_metric_fr.pdf",
      ...
    }
  }
}

Localized Media URL Object

Document URL object looks as follows:

Property	Type	Description
en	Media URL Object	URLs to iGUIDE View Media in English: Gallery, PDF floor plans, SVG floor plans, etc
fr	Media URL Object	URLs to iGUIDE View Media in French: Gallery, PDF floor plans, SVG floor plans, etc.

TIP

Today the documents are only available in English and French. More languages are going to be added as needed.

Media URL Object

Property	Type	Description
galleryFrontImage	string	URL to the front image in the Gallery. public
pdfMetric	string	PDF floor plan in metric units. public
pdfImperial	string	PDF floor plan in imperial units. public
galleryZip	string	URL to ZIP file containing all original Gallery images. private
galleryLowRes	string	URL to ZIP file containing all Low-Res Gallery images. private
sphereZip	string	URL to ZIP file containing all panorama sphere images. private
offlineZip	string	URL to offline ZIP file. private
svgZip	string	URL to a ZIP file containing SVG floor plans for all floors. private
dxfZip	string	URL to a ZIP file containing DXF floor plans for all floors. private
embedImage	string	URL to a preview image displayed in an iframe embedding the iGUIDE View. public

Public documents are publicly accessible using their URLs. These documents are marked with public in the table above.

Private documents cannot be accessed publicly and require an access token to be present in the URL. For more details please refer to Access Tokens. Private documents are marked with private in the table above.

Example of Media URL object for https://youriguide.com/api-docs-sample

{
  "pdfImperial": "https://youriguide.com/api-docs-sample/doc/floorplan_imperial.pdf",
  "pdfMetric": "https://youriguide.com/api-docs-sample/doc/floorplan_metric.pdf",
  "galleryFrontImage": "https://youriguide.com/api-docs-sample/doc/front.image",
  "galleryLowResZip": "https://youriguide.com/api-docs-sample/doc/gallery-low-res.zip",
  "galleryZip": "https://youriguide.com/api-docs-sample/doc/gallery.zip",
  "offlineZip": "https://youriguide.com/api-docs-sample/doc/offline_en.zip",
  "sphereZip": "https://youriguide.com/api-docs-sample/doc/spheres.zip",
  "svgZip": "https://youriguide.com/api-docs-sample/doc/svg.zip",
  "dxfZip": "https://youriguide.com/api-docs-sample/doc/dxf_metric.zip",
  "embedImage": "https://youriguide.com/api-docs-sample/doc/embed_preview.jpg"
}

Access Tokens

Private documents cannot be accessed without an access token. When sharing private documents, be sure to add an access token value to the Query String of the document URL as follows: <DOC URL>?accessToken=<ACCESS-TOKEN-VALUE>.

For example, suppose you get an iGUIDE Ready event with following values: Offline ZIP URL is https://youriguide.com/api-docs-sample/doc/offline.zip, and access token value is qD8iA. Then the Offline ZIP URL presented to the end user should be: https://youriguide.com/api-docs-sample/doc/offline.zip?accessToken=qD8iA (that is <iGUIDE View Doc URL>?accessToken=<ACCESS-TOKEN-VALUE>).

WARNING

Both public and private documents for Protected Views require a special access token. More details to come.

Test Webhook Endpoint

In order to test your endpoint:

1. Store the sample iGUIDE ready event object available at iguide-ready-event.json on your local file system.
2. Run cURL to simulate an iGUIDE event submission.

# Store iguide-ready-event.json locally:
curl -fsL 'https://docs.youriguide.com/samples/iguide-ready-event.json' \
  -o iguide-ready-event.json

# Submit iguide-ready-event.json to your webhook URL:
curl -fsv \
  -X POST \
  -H 'Content-Type: application/json' \
  -d @iguide-ready-event.json \
  "<YOUR WEBHOOK URL>"