Visuals Ready Event Scenarios
Overview
The VISUALS_READY
event is triggered when materials (visuals, documents, or other deliverables) are ready for download. The exact trigger logic depends on the product kind and workflow scenario. For a full description of the event and its payload, see Webhook System Documentation.

Scenario Table
Scenario | Visuals Taking | Editing | No Selection | Visual Selection | Trigger | Description |
---|---|---|---|---|---|---|
A | Yes/No | Yes | No | No | The edited visuals are uploaded and available for the client. | The event is sent when the edited visuals are ready. The edited visuals don't need a selection. |
B | Yes/No | Yes/No | Yes/No | Yes | The visual selection is done and confirmed. | The event is sent when the final visual selection is done. |
Product Kinds by Scenario
Scenario A (After Editing) | Conditions | Scenario B (After Selection) | Conditions |
---|---|---|---|
Self-edited photos | To be implemented | Ground Photo | More visuals and client has to choose them. |
Visual export | To be implemented | Ground Photo Prestige | More visuals and client has to choose them. |
Ground Photo | Less or exact amount of visuals. | Drone Photo | More visuals and client has to choose them. |
Ground Photo Prestige | Less or exact amount of visuals. | Mast Photo | More visuals and client has to choose them. |
Drone Photo | Less or exact amount of visuals. | Photo (Standard Editing) | More visuals and client has to choose them. |
Mast Photo | Less or exact amount of visuals. | ||
Photo (Standard Editing) | Less or exact amount of visuals. | ||
Standard Ground Video | VIDEOS | ||
Standard Drone Video | |||
Standard Ground And Drone Video | |||
Prestige Ground And Drone Video | |||
Reel Video | |||
Teaser Video | |||
Slideshow | |||
Matterport Floorplan With Visit | FLOORPLANS | ||
Floorplan Editing 2D | |||
Floorplan Editing 3D | |||
Mobile Application Floorplan | |||
Floorplan Rendering 3D | |||
Matterport SD (Virtual Visit) | MATTERPORT | ||
Matterport HD (Virtual Visit) | |||
Matterport Photo | |||
On-site Area Report | |||
Residential Staging | STAGING | ||
Commercial Staging |
Documents and Special Cases
Product Kind | Special Trigger Condition |
---|---|
Authorities Documents | On DocEstate delivery to BKBN VISUALS_READY is triggered without client acceptance (instant) |
Energy Certificate | On FINAL delivery (i.e. NOT PREVIEW or PENDING APPROVAL) after the client has accepted in the gallery, VISUALS_READY is triggered (couple mins delay) |
Floorplan Certification | After client accepts the document in the gallery, VISUALS_READY is triggered (instant) |
AI Photo Editing | After client accepts the visuals in the gallery, VISUALS_READY is triggered (Instant) |
AI Text Generator | Not yet implemented for VISUALS_READY |
Upsell in gallery | As soon as a visual is bought as an upsell in the gallery, VISUALS_READY is triggered. |
For the full event payload, integration examples, and error handling, see Webhook System Documentation.
Materials API Documentation
Overview
The Materials API allows clients to request and retrieve materials (media files, documents, or result URLs) that have been delivered for specific orders and assignments. This endpoint is typically called after receiving a VISUALS_READY
webhook event, which indicates that materials are available for download.
API Endpoint
Request Materials
GET /materials/{orderId}/{assignmentId}
Requests materials for a specific order and assignment combination.
Path Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
orderId | string | Yes | Unique identifier of the order | 12345 |
assignmentId | string | Yes | Unique identifier of the assignment within the order | 12345-A |
Query Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
product | RequestProductKind | Yes | Type of output/deliverable to request | GROUND_PHOTO |
visualType | RequestResourceType | No | Type of visual/resource to request (defaults to POST) | POST |
Authentication
All requests require JWT authentication. Include your token in the Authorization header:
Authorization: Bearer <your-jwt-token>
Example Request
GET /materials/12345/12345-A?product=GROUND_PHOTO&visualType=POST
Authorization: Bearer <your-jwt-token>
Response
Success (200 OK):
{
"orderId": "12345",
"assignmentId": "12345-A",
"orderType": "PHOTO",
"mediaFiles": [
{
"mediaType": "PHOTO",
"downloadUrl": "https://storage.example.com/photos/photo1.jpg",
"originalFileName": "property_front_view.jpg"
},
{
"mediaType": "PHOTO",
"downloadUrl": "https://storage.example.com/photos/photo2.jpg",
"originalFileName": "property_back_view.jpg"
}
],
"resultUrls": []
}
Error Responses:
- 400 Bad Request: Invalid request parameters (e.g., incompatible visualType for product)
- 401 Unauthorized: Authentication required
- 403 Forbidden: Access denied to this resource
- 404 Not Found: Order, assignment, or materials not found
Product Types (RequestProductKind)
The product
parameter specifies what type of output/deliverable you want to retrieve:
Photography & Media
GROUND_PHOTO
- Standard ground-level photographsGROUND_PHOTO_PRESTIGE
- Premium ground-level photographs with enhanced processingDRONE_PHOTO
- Aerial photographs taken by dronesDRONE_VIDEO
- Aerial video content captured by drones
Virtual Experiences
PHOTO360
- 360-degree panoramic photographsMATTERPORT
- Professional 3D virtual tour files
Staging & Rendering
RESIDENTIAL_STAGING
- Virtually staged residential property imagesCOMMERCIAL_STAGING
- Virtually staged commercial property imagesRESIDENTIAL_RENDERING
- 3D rendered residential property visualizationsCOMMERCIAL_RENDERING
- 3D rendered commercial property visualizations
Documentation Services
MEASUREMENT_ON_SITE
- On-site measurement reports and documentationFLOOR_PLAN
- Technical floor plan drawings and documentsFLOOR_PLAN_CERTIFICATION
- Certified and official floor plan documentsENERGY_CERTIFICATE
- Energy efficiency certification documentsAUTHORITIES_DOCUMENTS
- Official documents from local authorities
Visual Types (RequestResourceType)
The visualType
parameter specifies the type of visual/resource to request:
Value | Description | Usage |
---|---|---|
POST | Standard post-processing visuals | Default for most products |
POST_WEB | Web-optimized post-processing visuals | For web display |
DOCUMENT | Document files | Required for document-based products |
RAW | Raw, unprocessed files | For original, unedited content |
Note: For document-based products (FLOOR_PLAN, ENERGY_CERTIFICATE, etc.), visualType
should be set to DOCUMENT
or omitted.
Response Structure
MaterialsDeliveryDTO
Field | Type | Description |
---|---|---|
orderId | string | The order identifier |
assignmentId | string | The assignment identifier |
orderType | OrderType | The type of order (mapped from product) |
mediaFiles | MediaFileResultDTO[] | Array of downloadable media files |
resultUrls | LinkResultDTO[] | Array of result URLs (for virtual tours, etc.) |
MediaFileResultDTO
Field | Type | Description |
---|---|---|
mediaType | MediaFileType | Type of media (PHOTO, VIDEO, DOCUMENT) |
downloadUrl | string | Direct download URL for the file |
originalFileName | string | Original filename of the media |
LinkResultDTO
Field | Type | Description |
---|---|---|
title | string | Title/name of the result |
linkUrl | string | URL to access the result |
MediaFileType
PHOTO
- Image files (JPG, PNG, etc.)VIDEO
- Video files (MP4, MOV, etc.)DOCUMENT
- Document files (PDF, etc.)
Usage Workflow
1. Receive Webhook Notification
When materials are ready, you'll receive a VISUALS_READY
webhook event:
{
"event": "VISUALS_READY",
"timestamp": "2023-01-15T12:45:00Z",
"orderId": "12345",
"assignmentId": "12345-A",
"visualType": "POST",
"product": "GROUND_PHOTO",
"realEstatePropertyId": "RE-123"
}
2. Request Materials
Use the webhook payload to request the materials:
GET /materials/12345/12345-A?product=GROUND_PHOTO&visualType=POST
3. Process the Response
Download the media files or access the result URLs as needed for your application.
Integration Examples
JavaScript/Node.js
async function handleVisualsReadyWebhook(webhookPayload) {
const { orderId, assignmentId, product, visualType } = webhookPayload;
// Request materials
const response = await fetch(
`/materials/${orderId}/${assignmentId}?product=${product}&visualType=${visualType || 'POST'}`,
{
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
}
);
if (response.ok) {
const materials = await response.json();
// Process media files
for (const mediaFile of materials.mediaFiles) {
console.log(`Downloading: ${mediaFile.originalFileName}`);
// Download and process the file
}
// Process result URLs
for (const resultUrl of materials.resultUrls) {
console.log(`Accessing: ${resultUrl.title} at ${resultUrl.linkUrl}`);
}
}
}
Python
import requests
def handle_visuals_ready_webhook(webhook_payload):
order_id = webhook_payload['orderId']
assignment_id = webhook_payload['assignmentId']
product = webhook_payload['product']
visual_type = webhook_payload.get('visualType', 'POST')
# Request materials
response = requests.get(
f'/materials/{order_id}/{assignment_id}',
params={
'product': product,
'visualType': visual_type
},
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
)
if response.status_code == 200:
materials = response.json()
# Process media files
for media_file in materials['mediaFiles']:
print(f"Downloading: {media_file['originalFileName']}")
# Download and process the file
# Process result URLs
for result_url in materials['resultUrls']:
print(f"Accessing: {result_url['title']} at {result_url['linkUrl']}")
PHP
<?php
function handleVisualsReadyWebhook($webhookPayload) {
$orderId = $webhookPayload['orderId'];
$assignmentId = $webhookPayload['assignmentId'];
$product = $webhookPayload['product'];
$visualType = $webhookPayload['visualType'] ?? 'POST';
// Request materials
$url = "/materials/{$orderId}/{$assignmentId}?product={$product}&visualType={$visualType}";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer {$token}",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$materials = json_decode($response, true);
// Process media files
foreach ($materials['mediaFiles'] as $mediaFile) {
echo "Downloading: " . $mediaFile['originalFileName'] . "\n";
// Download and process the file
}
// Process result URLs
foreach ($materials['resultUrls'] as $resultUrl) {
echo "Accessing: " . $resultUrl['title'] . " at " . $resultUrl['linkUrl'] . "\n";
}
}
}
?>
Error Handling
Common Error Scenarios
-
404 Not Found
- Order or assignment doesn't exist
- Materials haven't been delivered yet
- Check if you received the
VISUALS_READY
webhook first
-
400 Bad Request
- Invalid product type
- Incompatible visualType for the product
- Missing required parameters
-
401 Unauthorized
- Invalid or expired JWT token
- Missing Authorization header
-
403 Forbidden
- No access to the specified order/assignment
- Check your permissions
Retry Strategy
- 404 errors: Don't retry immediately - wait for the
VISUALS_READY
webhook - 400 errors: Don't retry - fix the request parameters
- 401/403 errors: Refresh your authentication token
- 5xx errors: Retry with exponential backoff
Security Considerations
- Authentication: Always use JWT tokens for authentication
- HTTPS: Use HTTPS for all API calls in production
- Token Management: Store and rotate JWT tokens securely
- URL Validation: Validate download URLs before accessing them
- File Downloads: Implement proper file download security measures
Rate Limiting
The API implements rate limiting to ensure fair usage. If you exceed the rate limits, you'll receive a 429 Too Many Requests
response. Implement exponential backoff for retries.
Testing
You can test the materials API using:
- Postman/Insomnia: Import the API specification
- cURL: Use command-line examples
- Integration Testing: Set up test orders and assignments
Support
For issues with the Materials API:
- Check the webhook trigger history for delivery status
- Verify your authentication and permissions
- Review the error response details
- Contact support with order/assignment IDs and error details
Updated 1 day ago