V3 Order Status Webhook

Overview

Subscribe to the Order Statuses Webhook to get real-time updates on the status of your PlanOmatic order. Think of the webhook as a push notification! Get started by getting access to our integration in PlanOintegrate. Request access >

👍
Improved V3 Order Object
We have cut out what is no longer needed from the order object that is included in our webhooks, and added new elements that are relevant to our industry today. For example, the V3 order object now includes photo URLs! No need to use an additional API for photo asset retrieval. Photo URLs are now included in webhooks when ready.

Stay Up to Date on the Status of Your Orders

By subscribing to the webhook, your team will immediately be alerted of any issues on-site and be notified within seconds of the photos being delivered. Store these updates in your system to create transparency throughout your marketing/leasing teams. Order Event Triggers >

Order Status Webhook Features

Feature	V3	V2	Description
Receive Real Time Updates on the Status of Your Orders	✅	✅	Stay in the loop throughout the life cycle of your order with live updates.
Receive 3D Tours Links As Soon As They Are Available	✅	✅	Once an order's 3D tour becomes available, a link to the tour can be found in the webhook payload. Learn more.
Receive Photo and Floor Plan Assets As Soon As They Are Available	✅		Once an order's photo and floor plan assets become available, you can grab links to them in the V3 Order Status Webhook. Learn more.
Receive Custom Metadata About the Order	✅		Receive up too a 1000 character JSON object sent with order request. Read more in the metadata param in the Order API.

Important Webhook Payload Data

The majority of the data in the webhook payload has the same body structure as the parameters in the V3 Create Order API. However, there are some pieces of data that are available after the order is created.

Event That Triggered the Webhook

Every time an order status webhook is sent, it is because the order experienced an event. The events indicate an order has been scheduled, or the appointment has been completed, or the requested assets have been delivered, and many more. Order Event Triggers >

"event": "order.delivered"

3D Tour Links

In the webhook payload below, you can see a links key where you will find a links to 3D tours when they are ready. The key of the 3D tour link will depend on the services ordered. If a Zillow 3D tour is ordered, you will find the link in the key zillow_3d_link.

"links": {
    "zillow_3d_link": "https://www.zillow.com/view-3d-home/XXXXXXXXXX",
    "photo_manage_link": "https://go.planomatic.com/planox/manage_photos/XXXXXX"
  }

Photo and Floor Plan Links

Photo and Floor Plan data can be found in the photos array in the webhook payload. Below is a description of the of the photo attributes and an example.

"photos": [
   {
     "full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX1.jpg",
     "full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX1/cw.jpg",
     "uploaded_at": "2022-02-25T06:41:58.000Z",
     "modified_at": "2022-03-25T21:07:56.000Z",
     "caption": "Front View",
     "sequence": 1,
   }
]

Attributes Details

Attribute	Description
full_size_url	URL to full sized version of photo. Generally at the aspect ratio of (3600 × 2400).
full_size_watermarked_url	URL to full sized watermarked version of photo. Generally at the aspect ratio of (3600 × 2400).
uploaded_at	UTC datetime of moment when the photo was uploaded.
modified_at	UTC datetime of moment when the photo was last modified.
sequence	Numerical sequence of photo based on PlanOmatic sorting pattern. Please consult [email protected] before building any logic based on field.
caption	Human readable data describing the photo. Please consult [email protected] before building any logic based on field.

Appointment Rescheduled

From time to time a PlanOtech will need to reschedule an appointment because of weather, sickness, or other event. When this happens, PlanOmatic will broadcast a appointment.awaiting_reschedule webhook event to subscribers. This event will contain details about the reason for the rescheduling and a new appointment. Below is an example of an appointments array upon a appointment.awaiting_reschedule event.

"appointments": [
  {
    "appointment_id": 3002,
    "start_datetime": "2024-01-11T17:56:10.000+00:00",
    "cancelation_reason": null,
    "cancelation_notes": null,
    "canceled": false
  },
  {
    "appointment_id": 2911,
    "start_datetime": "2024-01-10T16:00:00.000+00:00",
    "cancelation_reason": "Weather does not allow for outdoor photography",
    "cancelation_notes": "Roads too icy",
    "canceled": true
  }
],

You can pull a lot of useful information from an orders appointments object such as the time and date of the appointment start_datetime in Coordinated Universal Time (UTC). This time is an estimate until the PlanOtech is on site.

You can also note why a reschedule has taken place by observing the canceled appointment attribute and pulling the cancelation_reason and cancelation_notes. Our standard cancelation_reasons are subject to change and are as of Q1 2024:

Personal Matter
Ran Out of Time
Sick
Too Far
Weather does not allow for outdoor photography

Attributes Details

Attribute	Description
appointments.id	PlanOmatic appointment id
appointments.start_datetime	Date time of the start of the appointment. Estimate prior to the actual appointment.
appointments.cancelation_reason	Reason for reschedule. List above.
appointments.cancelation_notes	Additional notes on cancelation from PlanOtech
appointments.canceled	Simple true or false value to identify if a specific appointment (not order) has been canceled.

Unable To Complete Appointment Details

From time to time you may send an order to PlanOmatic when the property is not ready for the services requested. For example, if there is no lockbox for our photographer to use to access the property, our photographer will call our client's on-site contact and if there is no response the PlanOtech will submit the order as appointment.unable_to_complete and provide a reason and description.

"unable_to_complete_appt": true,
"unable_to_complete_appt_reason": "Onsite: No Lockbox",
"unable_to_complete_appt_notes": "Did not discover a lockbox and checked both front and back door as well as around the house.  Texted contact but received no respons.",

Attributes Details

Attribute	Description
unable_to_complete_appt	Simple true or false value to identify if the order resulted in an appointment that was unable to complete.
unable_to_complete_appt_reason	Category of issue. For a list of category options, reach out to [email protected]
unable_to_complete_appt_notes	Additional description about the issue written by the PlanOtech. Please consult [email protected] before building any logic based on field.

Order Cancelation Details

On rare occasion, PlanOmatic may cancel an order for being out of range of the currently supported service areas / markets. When this happens, the order_cancelation_reason will be set to "Out of Range." If your team still desires services for the property, then they may need to find another vendor to temporarily assist until PlanOmatic is able to expand into the new service area / market.

"appointments": [
  {
    "appointment_id": 2911,
    "cancelation_reason": "Other: Scheduling Mistake",
    "cancelation_notes": "Off schedule on Sunday"
  }
],
"order_cancelation_reason": "Other: Scheduling Mistake",
"order_cancelation_notes": "Off schedule on Sunday",

Attributes Details

Attribute	Description
order_cancelation_reason	Category of issue. For a list of category options, reach out to [email protected]
order_cancelation_notes	Additional description about the issue written by the PlanOtech. Please consult [email protected] before building any logic based on field.

Example Webhook Payload

Below is an example of PlanOmatic's order object. This is the structure of order data that is used for webhook and API response payloads.

{
  "order_id": 654321, 						            // PlanOmatic Order ID
  "external_property_id": "{property_id}", 		// Custom Property ID passed by client
  "event": "order.delivered",					        // Event that triggered webhook
  "created": "2021-05-18T18:03:30.000Z",
	"metadata": {
     'metadata_key1': 'abc123', 
  	 'metadata_key2': 'wxyz987'
	 },
  "external_order_id": "{external_order_id}",
  "order_status": "completed",
  "billing_entity": {
    "slug": "investment_entity_1",
    "name": "Investment Entity Number 1"
  },
  "property": {
    "location": {
      "address": "123 Fake St, Unit A, Denver, CO, 80205",
      "street": "123 Fake St",
      "street2": "Unit A",
      "city": "Denver",
      "state": "CO",
      "postal_code": "80205",
      "country": "US",
      "market": "Denver",
      "latitude": "95.784747",
      "longitude": "-43.848483",
    },
    "property_type": "single_family",
    "bedrooms": "3",
    "bathrooms": "2.5",
    "price": "3000",
    "square_footage": "1500"
  },
  "services": [
    {
      "slug": "photos",
      "quantity": 15,
      "name": "Photos",
      "price": "12500"
    },
    {
      "slug": "zillow_3d",
      "quantity": 1,
      "name": "Zillow 3D Home Tour",
      "price": "12500"
    }
  ],
  "property_access": {
    "vacant": true,
    "method_of_access": "lockbox_code",
    "access_code": "4321",
    "lockbox_location": "Behind A/C Unit",
    "preferred_date": "YYYY-MM-DD",
    "onsite_contact_name": "Jane Doe",
    "onsite_contact_email": "[email protected]",
    "onsite_contact_phone": "+1 555-555-5555"
  },
  "order_notes": "Some special instructions",
  "appointments": [                     // Webhook exclusive data
    { // Not included: PlanOmatic deliverable, post order notification, order updates
      "appointment_id": 7654321,
      "start_datetime": "2021-05-20T18:00:00.000+00:00",
      "end_datetime": "2021-05-20T18:30:00.000+00:00",
      "duration_m": 30,
      "planotech_name": "Bobby",
      "cancelation_reason": null,
      "cancelation_notes": null,
      "canceled":false
    }
  ],
  "order_cancelation_reason": null,		   // Webhook exclusive data
  "order_cancelation_notes": null,		   // Webhook exclusive data
  "unable_to_complete_appt": false,        // Webhook exclusive data
  "unable_to_complete_appt_reason": null,  // Webhook exclusive data
  "unable_to_complete_appt_notes": null,   // Webhook exclusive data
  "links": {                               // Webhook exclusive data
    "matterport_3d_link": "https://my.matterport.com/show/?m=XXXXXXXXXX",
    "zillow_3d_link": "https://www.zillow.com/view-3d-home/XXXXXXXXXX",
    "photo_manage_link": "https://go.planomatic.com/planox/manage_photos/XXXXXX"
  },
  "photos": [                              // Webhook exclusive data
    {
      "sequence": 1,
      "caption": "Front View",
      "full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX1.jpg",
      "full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX1/cw.jpg",
      "uploaded_at": "2022-02-25T06:41:58.000Z",
      "modified_at": "2022-03-25T21:07:56.000Z"
    },
    {
      "sequence": 2,
      "caption": "Kitchen",
      "full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX2.jpg",
      "full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX2/cw.jpg",
      "uploaded_at": "2022-02-25T06:41:58.000Z",
      "modified_at": "2022-03-25T21:07:56.000Z"
    },
    {
      "sequence": 3,
      "caption": "Bedroom",
      "full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX3.jpg",
      "full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX3/cw.jpg",
      "uploaded_at": "2022-02-25T06:41:58.000Z",
      "modified_at": "2022-03-25T21:07:56.000Z"
    }
  ],
  "legacy_order_id": 543210  //Orders before 2022 may have referenced a different ID which we call the "legacy_order_id"
}

Overview

👍Improved V3 Order Object

Stay Up to Date on the Status of Your Orders

Order Status Webhook Features

Important Webhook Payload Data

Event That Triggered the Webhook

3D Tour Links

Photo and Floor Plan Links

Attributes Details

Appointment Rescheduled

Attributes Details

Unable To Complete Appointment Details

Attributes Details

Order Cancelation Details

Attributes Details

Example Webhook Payload

👍
Improved V3 Order Object