---
updatedAt: 2026-05-06T15:17:22.000Z
agentTools:
  projectIndex: https://docs.bkbn.com/llms.txt
---

# Visuals Ready Event Scenarios

## Overview

<br />

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](https://docs.bkbn.com/docs/webhooks#/).

> Please note that the event VISUALS\_READY is pushed through the webhook every time there is a new file. We strongly recommend that you implement versioning on your side to keep track of the files you already have in order to skip redownloading the same file over and over.

<Image align="center" alt="Visuals Ready Event Flow" src="https://files.readme.io/fe6d7d1240aea939f247a2ff40fdf568f3e31f24aacf1b198fd348cc2ad0666a-event_visuals_ready.png" />

## Scenario Table

<br />

| Scenario       | Visual Selection | Trigger                                                       | Description                                                                                     |
| -------------- | ---------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Scenario A** | 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. |
| **Scenario B** | Yes              | The visual selection is done and confirmed.                   | The event is sent when the final visual selection is done.                                      |

## Product Kinds by Scenario

<br />

| Scenario A - After Editing             | Notes             | Scenario B - After Selection | Notes |
| -------------------------------------- | ----------------- | ---------------------------- | ----- |
| Photo (Standard Editing)               |                   |                              |       |
| Standard Ground Video                  |                   | Ground Photo Prestige        |       |
| Standard Drone Video                   |                   | Drone Photo                  |       |
| Standard Ground And Drone Video        |                   | Mast Photo                   |       |
| Prestige Ground And Drone Video        |                   | Photo (Standard Editing)     |       |
| Reel Video                             |                   | Energy Certificate           |       |
| Teaser Video                           |                   | Floorplan Certification      |       |
| Slideshow                              |                   |                              |       |
| Matterport Floorplan With Visit        |                   |                              |       |
| Floorplan Editing 2D                   |                   |                              |       |
| Self-edited Floorplan Editing 2D       |                   |                              |       |
| Floorplan Editing 3D                   |                   |                              |       |
| Mobile Application Floorplan           |                   |                              |       |
| Floorplan Rendering 3D                 |                   |                              |       |
| Matterport SD (Virtual Visit)          |                   |                              |       |
| Matterport HD (Virtual Visit)          |                   |                              |       |
| Matterport Photo                       |                   |                              |       |
| On-site Area Report                    |                   |                              |       |
| Residential Staging                    |                   |                              |       |
| Commercial Staging                     |                   |                              |       |
| Additional photos purchased in gallery |                   |                              |       |
| Authorities Documents                  |                   |                              |       |
| AI Photo Editing                       |                   |                              |       |
| Original photos (self-uploaded)        |                   |                              |       |
| Self-edited photos                     |                   |                              |       |
| AI Text Generator                      | Has own endpoint  |                              |       |
| Visual export                          | To be implemented |                              |       |

## Documents and Special Cases

| Product Kind                             | Special Trigger Condition                                                                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authorities Documents                    | On document 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)                                                                |
| Additional photo purchase in the Gallery | As soon as an additional visual is bought in the gallery, VISUALS\_READY is triggered.                                                                 |

***

For the full event payload, integration examples, and error handling, see [Webhook System Documentation](./WEBHOOK.md#visuals-ready).

# 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

```http
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

```http
GET /materials/12345/12345-A?product=GROUND_PHOTO&visualType=POST
Authorization: Bearer <your-jwt-token>
```

#### Response

**Success (200 OK):**

```json
{
  "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:

| 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:

```json
{
  "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:

```http
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

```javascript
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

```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
<?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