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

Product Kinds by Scenario

Documents and Special Cases

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

Query Parameters

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 photographs
• GROUND_PHOTO_PRESTIGE - Premium ground-level photographs with enhanced processing
• DRONE_PHOTO - Aerial photographs taken by drones
• DRONE_VIDEO - Aerial video content captured by drones

Virtual Experiences

• PHOTO360 - 360-degree panoramic photographs
• MATTERPORT - Professional 3D virtual tour files

Staging & Rendering

• RESIDENTIAL_STAGING - Virtually staged residential property images
• COMMERCIAL_STAGING - Virtually staged commercial property images
• RESIDENTIAL_RENDERING - 3D rendered residential property visualizations
• COMMERCIAL_RENDERING - 3D rendered commercial property visualizations

Documentation Services

• MEASUREMENT_ON_SITE - On-site measurement reports and documentation
• FLOOR_PLAN - Technical floor plan drawings and documents
• FLOOR_PLAN_CERTIFICATION - Certified and official floor plan documents
• ENERGY_CERTIFICATE - Energy efficiency certification documents
• AUTHORITIES_DOCUMENTS - Official documents from local authorities

Visual Types (RequestResourceType)

The visualType parameter specifies the type of visual/resource to request:

Note: For document-based products (FLOOR_PLAN, ENERGY_CERTIFICATE, etc.), visualType should be set to DOCUMENT or omitted.

Response Structure

MaterialsDeliveryDTO

MediaFileResultDTO

LinkResultDTO

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

1. 404 Not Found

   • Order or assignment doesn't exist
   • Materials haven't been delivered yet
   • Check if you received the VISUALS_READY webhook first

2. 400 Bad Request

   • Invalid product type
   • Incompatible visualType for the product
   • Missing required parameters

3. 401 Unauthorized

   • Invalid or expired JWT token
   • Missing Authorization header

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

1. Authentication: Always use JWT tokens for authentication
2. HTTPS: Use HTTPS for all API calls in production
3. Token Management: Store and rotate JWT tokens securely
4. URL Validation: Validate download URLs before accessing them
5. 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:

1. Postman/Insomnia: Import the API specification
2. cURL: Use command-line examples
3. Integration Testing: Set up test orders and assignments

Support

For issues with the Materials API:

1. Check the webhook trigger history for delivery status
2. Verify your authentication and permissions
3. Review the error response details
4. Contact support with order/assignment IDs and error details