BoxBrownie.com API v2.0 Docs

Overview

Virtual Staging jobs allow you to submit images and have 3D rendered furniture and decorations placed in the image.

Create a Virtual Staging Job

POST /api/v2/job/createVirtualStaging

Endpoint: https://www.boxbrownie.com/api/v2/job/createVirtualStaging
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

To create a Virtual Staging job, we require you to send us an XML payload that contains a job title, URLs of the images you wish to be edited, and any virtual staging-specific options that are needed for the job.

Your job XML should start with a job title.

<jobTitle>	String	Required	Max 1 Occurence	The title for the job. 100 characters max

Then, for each primary image that you want to include for editing, your XML should an occurence of <fileGroup>. A file group will contain all the information for the edit that is being performed. Your XML may contain any number of <fileGroup> elements.

<fileGroup>		Required	Multiple Allowed	Represents one output. Contains XML for any images (primary and reference images) and any edit options for the output
<fileGroupComment>	String	Optional	Max 1 Occurence	An optional comment containing any special instructions for the file group

Within the <fileGroup> element, you will need to specify the file URL of the image that is going to be edited. You can specify more than one file URL if desired. The first file URL in each <files> block is treated as the primary image (the one that will be edited). Any subsequent <fileURL> elements will be treated as reference images for the edit. You may include any number of <fileURL> elements, just keep in mind that only the first in each file group will be edited.

<files>		Required	Max 1 Occurence	Contains one or more `<fileURL>` elements for the file group
<fileURL>	String	Required	Multiple Allowed	A file URL. The first occurence of `<fileURL>` in each `<files>` block is treated as the primary image for the file group (the one that will be edited). Subsequent `<fileURL>` elements are treated as reference images only and will not be edited

Within the <fileGroup> element, you may optionally provide a <sampleImages> block that contains one or more <sampleImageId> elements. This can be used to attach pre-uploaded sample images from your BoxBrownie.com account as additional reference images in the job. For more information, see the Sample Images documentation.

<sampleImages>		Optional	Max 1 Occurence	Contains one or more `<sampleImageId>` elements for the file group
<sampleImageId>	String	Required	Multiple Allowed	The unique ID of a sample image from your BoxBrownie.com account.

There are two sets of options that can be provided: Virtual Staging Options and Editing Options. Some Virtual Staging Options are required, and Editing Options are completely optional.

Virtual Staging Options are provided in an <options> block, with each option being defined as an <option> element containing both an <optionName> and an <optionValue>. Below, you can see an interactive list of accepted <optionName> and <optionValue> values.

<options>		Required	Max 1 Occurence	Contains one or more `<option>` elements for the file group
<option>		Required	Multiple Allowed	Contains exactly one `<optionName>` and one `<optionValue>`
<optionName>	String	Required	Max 1 Occurrence	The key of a Virtual Staging Option
<optionValue>	String	Required	Max 1 Occurrence	The key of a Virtual Staging Option Value

Edit Options are completely optional and are provided in an <edits> block, with each edit option being defined as an <edit> element containing an <editName>, an <editValue> and an <editComment>. Below, you can see an interactive list of accepted <editName> and <editValue> values.

<edits>		Optional	Max 1 Occurence	Contains one or more `<edit>` elements for the file group
<edit>		Required	Multiple Allowed	Contains exactly one `<editName>` and one `<editValue>`
<editName>	String	Required	Max 1 Occurrence	The key of an Editing Option
<editValue>	String	Required	Max 1 Occurrence	The key of an Editing Option Value
<editComment>	String	Optional	Max 1 Occurrence	A comment for any special instructions relating to the chosen edit option. This is usually optional, but may be required for some specific editing option values

Example XML

Below, you can see an example XML payload. This example defines 2 <fileGroup> elements with varying options. If this were a real job, you could expect to receive 2 completed output files when completed

<job>
    <jobTitle>My Virtual Staging Job</jobTitle>
    <fileGroup>
        <files>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured06.png</fileURL>
        </files>
        <sampleImages>
            <sampleImageId>99ccd87633acb90545c7ebcf4f57511df8d50a33</sampleImageId>
            <sampleImageId>d9c2ca823cf01a54df60f190da405151eab3c700</sampleImageId>
        </sampleImages>
        <options>
            <option>
                <optionName>ROOM_NAME</optionName>
                <optionValue>ROOM_MAIN_BEDROOM</optionValue>
            </option>
            <option>
                <optionName>FURNITURE_STYLE</optionName>
                <optionValue>STYLE_MODERN</optionValue>
            </option>
        </options>
        <edits>
            <edit>
                <editName>IMAGE_ENHANCEMENT</editName>
                <editValue>OPTION_YES</editValue>
                <editComment>Test comment</editComment>
            </edit>
            <edit>
                <editName>ITEM_REMOVAL</editName>
                <editValue>ITEM_REMOVAL_TIER_1</editValue>
                <editComment>Remove this, this and this</editComment>
            </edit>
        </edits>
        <fileGroupComment>Here is another comment</fileGroupComment>
    </fileGroup>
    <fileGroup>
        <files>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured06.png</fileURL>
        </files>
        <options>
            <option>
                <optionName>ROOM_NAME</optionName>
                <optionValue>ROOM_KITCHEN</optionValue>
            </option>
            <option>
                <optionName>FURNITURE_STYLE</optionName>
                <optionValue>STYLE_MODERN</optionValue>
            </option>
        </options>
        <fileGroupComment>Here is 2nd filegroup comment</fileGroupComment>
    </fileGroup>
</job>

Example Response

Below, you can see an example response for the above example API Request.

{
  "success": "1",
  "job": {
    "jobId": "380f7831bbb0d3ece5ebaf7c5faf9a935536c957",
    "jobTitle": "My Virtual Staging Job",
    "jobReference": "VS373735194179",
    "jobStatus": "Pending",
    "jobDateSubmitted": "2024-02-28 15:41:47",
    "jobCost": "72.00",
    "jobCostCurrency": "AUD"
  }
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <job>
        <jobId>380f7831bbb0d3ece5ebaf7c5faf9a935536c957</jobId>
        <jobTitle>My Virtual Staging Job</jobTitle>
        <jobReference>VS373735194179</jobReference>
        <jobStatus>Pending</jobStatus>
        <jobDateSubmitted>2024-02-28 15:41:47</jobDateSubmitted>
        <jobCost>72.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
    </job>
</response>

Simulate a Virtual Staging Job

POST /api/v2/job/simulateVirtualStaging

Endpoint: https://www.boxbrownie.com/api/v2/job/simulateVirtualStaging
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

The BoxBrownie.com API allows you to simulate the creation of a Virtual Staging job in order to check for any errors in the XML payload of a job submission by using this endpoint. Additionally, this endpoint will return the expected job credit cost for the XML payload.

This endpoint accepts the same XML that you would use with the Create a Virtual Staging Job endpoint.

Note: Using this endpoint will not create any jobs in your account, and will not charge your BoxBrownie.com account.

Note: Estimated credit cost does not take into account any free trials associated with your BoxBrownie.com account.

Example Response

Below, you can see an example response when supplying job XML to this endpoint.

{
  "success": "1",
  "jobCost": "72.00",
  "jobCostCurrency": "AUD",
  "xmlIsValid": "1"
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <jobCost>72.00</jobCost>
    <jobCostCurrency>AUD</jobCostCurrency>
    <xmlIsValid>1</xmlIsValid>
</response>

Retrieve a Virtual Staging Job

GET /api/v2/job/{jobReference}

Endpoint: https://www.boxbrownie.com/api/v2/job/{jobReference}
HTTP Method: GET
Requires Authentication? Yes
Required Parameters: jobReference
Optional Parameters: (string) responseFormat [json|xml]

You may retrieve details about any job in your BoxBrownie.com account by supplying the reference number of the job jobReference.

Example Response

{
  "job": {
    "jobId": "380f7831bbb0d3ece5ebaf7c5faf9a935536c957",
    "jobTitle": "My Virtual Staging Job",
    "jobReference": "VS373735194179",
    "jobStatus": "Completed",
    "jobDateSubmitted": "2024-02-28 15:41:47",
    "jobCost": "72.00",
    "jobCostCurrency": "AUD",
    "jobDateCompleted": "2024-02-29 07:22:14",
    "output": {
      "file": [
        {
          "fileId": "f157e4f01b39190b03114f22590b5f49269e527b",
          "fileURL": "https://boxbrownie-virtual-staging.b-cdn.net/380f7831bbb0d3ece5ebaf7c5faf9a935536c957/edited/f157e4f01b39190b03114f22590b5f49269e527b.jpg"
        },
        {
          "fileId": "02e59728409223c2a31b9d412341cebd09abcfac",
          "fileURL": "https://boxbrownie-virtual-staging.b-cdn.net/380f7831bbb0d3ece5ebaf7c5faf9a935536c957/edited/02e59728409223c2a31b9d412341cebd09abcfac.jpg"
        }
      ]
    }
  }
}

<?xml version="1.0"?>
<response>
    <job>
        <jobId>380f7831bbb0d3ece5ebaf7c5faf9a935536c957</jobId>
        <jobTitle>My Virtual Staging Job</jobTitle>
        <jobReference>VS373735194179</jobReference>
        <jobStatus>Completed</jobStatus>
        <jobDateSubmitted>2024-02-28 15:41:47</jobDateSubmitted>
        <jobCost>72.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
        <jobDateCompleted>2024-02-29 07:22:14</jobDateCompleted>
        <output>
            <file>
                <fileId>f157e4f01b39190b03114f22590b5f49269e527b</fileId>
                <fileURL>https://boxbrownie-virtual-staging.b-cdn.net/380f7831bbb0d3ece5ebaf7c5faf9a935536c957/edited/f157e4f01b39190b03114f22590b5f49269e527b.jpg</fileURL>
            </file>
            <file>
                <fileId>02e59728409223c2a31b9d412341cebd09abcfac</fileId>
                <fileURL>https://boxbrownie-virtual-staging.b-cdn.net/380f7831bbb0d3ece5ebaf7c5faf9a935536c957/edited/02e59728409223c2a31b9d412341cebd09abcfac.jpg</fileURL>
            </file>
        </output>
    </job>
</response>

Rework a Virtual Staging Job

POST /api/v2/job/reworkVirtualStaging

Endpoint: https://www.boxbrownie.com/api/v2/job/reworkVirtualStaging
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

After a Virtual Staging job has been completed, you will have the ability to submit rework requests for any number of completed output images. Similarly to creating a new job, you will be required to supply an XML payload describing which images to rework, with instructions about what you want changed.

You must supply either a <jobId> or a <jobReference> and at least one <rework> block that contains both one <fileId> and one <reworkComment>

Images are supplied in the form of a <fileId>, which can be obtained when retrieving a completed job.

Optionally, you may submit one or more reference files with each <rework> block by including a <referenceFiles> block that includes one or more <fileURL> elements.

Note: Virtual Staging jobs can only be reworked if it has been less than 2 months since the jobDateCompleted time, and if there are no existing active reworks for the job.

Example XML

Below, you can see an example XML payload. In this example, we are requesting 2 reworks for the supplied jobId. The first rework also contains 2 reference files.

<job>
    <jobId>633e99992f6ba94270e3fda635d42464c12edcd0</jobId>
    <rework>
        <fileId>f157e4f01b39190b03114f22590b5f49269e527b</fileId>
        <reworkComment>Please replace dining chairs</reworkComment>
        <referenceFiles>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured06.png</fileURL>
        </referenceFiles>
    </rework>
    <rework>
        <fileId>02e59728409223c2a31b9d412341cebd09abcfac</fileId>
        <reworkComment>Please replace queen bed with single bed</reworkComment>
    </rework>
</job>

Example Response

{
  "success": "1",
  "reworkId": "565adb6ddfd7ff139f4e82c7edd55d24b7898e12"
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <reworkId>565adb6ddfd7ff139f4e82c7edd55d24b7898e12</reworkId>
</response>

Virtual Staging Options

GET /api/v2/job/virtualStagingOption

Endpoint: https://www.boxbrownie.com/api/v2/job/virtualStagingOption
Endpoint: https://www.boxbrownie.com/api/v2/job/virtualStagingOption/{optionName}
HTTP Method: GET
Requires Authentication? No
Optional Parameters:
(string) optionName,
(string) responseFormat [json|xml]

When creating a new Virtual Staging job, you will supply some options to tell us how you would like your virtual staging to be done. This is done by providing pairs of <optionName> and <optionValue>.

You can query this endpoint to return a list of all accepted virtual staging options and their accepted values. Alternatively, you can provide the optional optionName parameter to return only information and accepted values for that specific option

Below is a table of accepted <optionName> keys. Click on an <optionName> to see a table of accepted <optionValue> keys for that item.

Example Response

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingOption

{
  "options": [
    {
      "optionName": "ROOM_NAME",
      "optionDescription": "Room Name/Area",
      "optionRequired": "1",
      "optionType": "Multiple Choice",
      "optionValues": [
        {
          "optionValue": "ROOM_BATHROOM_ENSUITE",
          "optionValueDescription": "Bathroom/Ensuite"
        },
        {
          "optionValue": "ROOM_BEDROOM_1",
          "optionValueDescription": "Bedroom 1"
        },...
      ]
    },
    {
      "optionName": "FURNITURE_REQUIRED",
      "optionDescription": "Furniture & Accessories Required",
      "optionRequired": "0",
      "optionType": "Free Text",
      "optionValues": {}
    },...
  ]
}

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingOption?responseFormat=xml

<?xml version="1.0"?>
<response>
    <options>
        <optionName>ROOM_NAME</optionName>
        <optionDescription>Room Name/Area</optionDescription>
        <optionRequired>1</optionRequired>
        <optionType>Multiple Choice</optionType>
        <optionValues>
            <optionValue>ROOM_BATHROOM_ENSUITE</optionValue>
            <optionValueDescription>Bathroom/Ensuite</optionValueDescription>
        </optionValues>
        <optionValues>
            <optionValue>ROOM_BEDROOM_1</optionValue>
            <optionValueDescription>Bedroom 1</optionValueDescription>
        </optionValues>
        ...
    </options>
    <options>
        <optionName>FURNITURE_REQUIRED</optionName>
        <optionDescription>Furniture &amp; Accessories Required</optionDescription>
        <optionRequired>0</optionRequired>
        <optionType>Free Text</optionType>
        <optionValues/>
    </options>
    ...
</response>

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingOption/FILE_SIZE

{
  "optionName": "FILE_SIZE",
  "optionDescription": "File Size Limit (MLS and other online websites) ",
  "optionRequired": "0",
  "optionType": "Multiple Choice",
  "optionValues": [
    {
      "optionValue": "FILE_SIZE_10MB",
      "optionValueDescription": "10 MB & Under"
    },
    {
      "optionValue": "FILE_SIZE_5MB",
      "optionValueDescription": "5 MB & Under"
    },
    {
      "optionValue": "FILE_SIZE_ORIGINAL",
      "optionValueDescription": "Same size as original (may vary slightly)"
    }
  ]
}

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingOption/FILE_SIZE?responseFormat=xml

<?xml version="1.0"?>
<response>
    <optionName>FILE_SIZE</optionName>
    <optionDescription>File Size Limit (MLS and other online websites) </optionDescription>
    <optionRequired>0</optionRequired>
    <optionType>Multiple Choice</optionType>
    <optionValues>
        <optionValue>FILE_SIZE_10MB</optionValue>
        <optionValueDescription>10 MB &amp; Under</optionValueDescription>
    </optionValues>
    <optionValues>
        <optionValue>FILE_SIZE_5MB</optionValue>
        <optionValueDescription>5 MB &amp; Under</optionValueDescription>
    </optionValues>
    <optionValues>
        <optionValue>FILE_SIZE_ORIGINAL</optionValue>
        <optionValueDescription>Same size as original (may vary slightly)</optionValueDescription>
    </optionValues>
</response>

Accepted Options

Note: Options with a type of Free Text accept text strings as their value instead of an Option Value Key.

Option Name	Option Description	Option Type	Required?
ROOM_NAME	Room Name/Area	Multiple Choice	Yes
FURNITURE_STYLE	Look of Furniture	Image Selection	Yes
FURNITURE_REQUIRED	Furniture & Accessories Required	Free Text
FILE_SIZE	File Size Limit (MLS and other online websites)	Multiple Choice
DISCLAIMER_TEXT	Your Disclaimer Text	Free Text

Editing Options

GET /api/v2/job/virtualStagingEditingOption

Endpoint: https://www.boxbrownie.com/api/v2/job/virtualStagingEditingOption
Endpoint: https://www.boxbrownie.com/api/v2/job/virtualStagingEditingOption/{editName}
HTTP Method: GET
Requires Authentication? No
Optional Parameters:
(string) editName,
(string) responseFormat [json|xml]

When creating a new Virtual Staging job, you may supply some optional editing options that will be applied to your images prior to the virtual staging process. This is done by providing pairs of <editName> and <editValue>.

You can query this endpoint to return a list of all accepted virtual staging editing options and their accepted values. Alternatively, you can provide the optional editName parameter to return only information and accepted values for that specific editing option

Note: Editing options are generally costed options, meaning they will add to the credit total for the job. When querying this endpoint, if you are authenticated, credit costs will be returned in your specified currency.

Below is a table of accepted <editName> keys. Click on an <editName> to see a table of accepted <editValue> keys for that item.

Example Response

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingEditingOption

{
  "edits": [
    {
      "editName": "IMAGE_ENHANCEMENT",
      "editDescription": "Image Enhancement",
      "editValues": {
        "editValue": "OPTION_YES",
        "editValueDescription": "Yes",
        "creditCost": "2.00",
        "currency": "AUD"
      }
    },
    {
      "editName": "ITEM_REMOVAL",
      "editDescription": "Item Removal",
      "editValues": [
        {
          "editValue": "ITEM_REMOVAL_TIER_1",
          "editValueDescription": "Item Removal & Virtual Cleaning - Minor",
          "creditCost": "5.00",
          "currency": "AUD"
        },
        {
          "editValue": "ITEM_REMOVAL_TIER_2",
          "editValueDescription": "Item Removal & Virtual Cleaning - Standard",
          "creditCost": "10.00",
          "currency": "AUD"
        }
      ]
    },
    ...
  ]
}

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingEditingOption?responseFormat=xml

<?xml version="1.0"?>
<response>
    <edits>
        <editName>IMAGE_ENHANCEMENT</editName>
        <editDescription>Image Enhancement</editDescription>
        <editValues>
            <editValue>OPTION_YES</editValue>
            <editValueDescription>Yes</editValueDescription>
            <creditCost>2.00</creditCost>
            <currency>AUD</currency>
        </editValues>
    </edits>
    <edits>
        <editName>ITEM_REMOVAL</editName>
        <editDescription>Item Removal</editDescription>
        <editValues>
            <editValue>ITEM_REMOVAL_TIER_1</editValue>
            <editValueDescription>Item Removal &amp; Virtual Cleaning - Minor</editValueDescription>
            <creditCost>5.00</creditCost>
            <currency>AUD</currency>
        </editValues>
        <editValues>
            <editValue>ITEM_REMOVAL_TIER_2</editValue>
            <editValueDescription>Item Removal &amp; Virtual Cleaning - Standard</editValueDescription>
            <creditCost>10.00</creditCost>
            <currency>AUD</currency>
        </editValues>
    </edits>
    ...
</response>

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingEditingOption/IMAGE_ENHANCEMENT

{
  "editName": "IMAGE_ENHANCEMENT",
  "editDescription": "Image Enhancement",
  "editValues": {
    "editValue": "OPTION_YES",
    "editValueDescription": "Yes",
    "creditCost": "2.00",
    "currency": "AUD"
  }
}

URLhttps://www.boxbrownie.com/api/v2/job/virtualStagingEditingOption/IMAGE_ENHANCEMENT?responseFormat=xml

<?xml version="1.0"?>
<response>
    <editName>IMAGE_ENHANCEMENT</editName>
    <editDescription>Image Enhancement</editDescription>
    <editValues>
        <editValue>OPTION_YES</editValue>
        <editValueDescription>Yes</editValueDescription>
        <creditCost>2.00</creditCost>
        <currency>AUD</currency>
    </editValues>
</response>

Accepted Editing Options

Edit Name	Edit Description
IMAGE_ENHANCEMENT	Image Enhancement
COLOUR_CHANGE	Colour Change
DAY_TO_DUSK	Day to Dusk
ITEM_REMOVAL	Item Removal & Virtual Cleaning
TURN_ON_LIGHTS	Turn On Lights

Topics

Virtual Staging

Overview

Create a Virtual Staging Job

Example XML

Example Response

Simulate a Virtual Staging Job

Example Response

Retrieve a Virtual Staging Job

Example Response

Rework a Virtual Staging Job

Example XML

Example Response

Virtual Staging Options

Example Response

Accepted Options

Editing Options

Example Response

Accepted Editing Options