BoxBrownie.com API v2.0 Docs

Overview

Development Site Plan jobs allow you to submit site plan sketches/documents and have them converted into presentable and easily readable versions for use in marketing.

Create a Development Site Plan

POST /api/v2/job/createDevelopmentSitePlan

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

To create a Development Site Plan job, we require you to send us an XML payload that contains a job title and one or more <fileGroup> blocks that describe the file URL of the files to work from, and any desired editing options.

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 set of site plan files that you want to include in the job, your XML should include 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 files (primary and reference files) 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 URLs of the site plan working files. You can specify more than one file URL if desired. The first file URL in each <files> block is treated as the primary file (the one that will be worked from). Any subsequent <fileURL> elements will be treated as reference files for the edit. You may include any number of <fileURL> elements.

<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 file for the file group. Subsequent `<fileURL>` elements are treated as reference files 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.

Site Plan 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 edit
<option>		Required	Multiple Allowed	Contains exactly one `<optionName>` and one `<optionValue>`
<optionName>	String	Required	Max 1 Occurrence	The key of a Site Plan Option
<optionValue>	String	Required	Max 1 Occurrence	The key of a Site Plan Option Value

Example XML

Below, you can see an example XML payload. This example defines 1 <fileGroup> element with two <fileURL> elements provided. If this were a real job, you could expect to receive 1 completed output file when completed

<job>
    <jobTitle>My Dev Site Plan</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>NUMBER_OF_LOTS</optionName>
                <optionValue>LOTS_TIER_3</optionValue>
            </option>
            <option>
                <optionName>PLAN_STYLE</optionName>
                <optionValue>STYLE_KENSINGTON</optionValue>
            </option>
            <option>
                <optionName>PLAN_ORIENTATION</optionName>
                <optionValue>ORIENTATION_LANDSCAPE</optionValue>
            </option>
            <option>
                <optionName>PAGE_ORIENTATION</optionName>
                <optionValue>ORIENTATION_LANDSCAPE</optionValue>
            </option>
            <option>
                <optionName>DISPLAY_NORTH</optionName>
                <optionValue>OPTION_NO</optionValue>
            </option>
            <option>
                <optionName>DISPLAY_MEASUREMENTS</optionName>
                <optionValue>Yes. See Dimensions on First Image</optionValue>
            </option>
            <option>
                <optionName>DISPLAY_LOT_NUMBERS</optionName>
                <optionValue>OPTION_YES</optionValue>
            </option>
            <option>
                <optionName>FILE_SIZE</optionName>
                <optionValue>FILE_SIZE_10MB</optionValue>
            </option>
            <option>
                <optionName>FILE_TYPE</optionName>
                <optionValue>FILE_TYPE_PDF</optionValue>
            </option>
            <option>
                <optionName>DISPLAY_ADDRESS</optionName>
                <optionValue>123 Fake St, Mooloolaba QLD 4558</optionValue>
            </option>
        </options>
        <fileGroupComment>Here is a comment on this site plan</fileGroupComment>
    </fileGroup>
</job>

Example Response

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

{
  "success": "1",
  "job": {
    "jobId": "130fe17ee35d8e0444d18aeed9265555ede53050",
    "jobTitle": "My Site Plan",
    "jobReference": "J888492240117",
    "jobStatus": "Pending",
    "jobDateSubmitted": "2024-03-19 15:11:34",
    "jobCost": "50.00",
    "jobCostCurrency": "AUD"
  }
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <job>
        <jobId>130fe17ee35d8e0444d18aeed9265555ede53050</jobId>
        <jobTitle>My Site Plan</jobTitle>
        <jobReference>J888492240117</jobReference>
        <jobStatus>Pending</jobStatus>
        <jobDateSubmitted>2024-03-19 15:11:34</jobDateSubmitted>
        <jobCost>50.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
    </job>
</response>

Simulate a Site Plan

POST /api/v2/job/simulateDevelopmentPlan

Endpoint: https://www.boxbrownie.com/api/v2/job/simulateDevelopmentPlan
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 Site Plan 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 Site Plan 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": "50.00",
  "jobCostCurrency": "AUD",
  "xmlIsValid": "1"
}

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

Retrieve a Development Site Plan

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": "130fe17ee35d8e0444d18aeed9265555ede53050",
    "jobTitle": "My Site Plan",
    "jobReference": "J888492240117",
    "jobStatus": "Complete",
    "jobDateSubmitted": "2024-03-19 15:11:34",
    "jobCost": "40.00",
    "jobCostCurrency": "AUD",
    "jobDateCompleted": "2024-03-20 12:30:24",
    "output": {
      "file": [
        {
          "fileId": "75eebcbab044b3fe3358392b56d92b8c6fd6d208",
          "fileURL": "https://boxbrownie.b-cdn.net/completed/75eebcbab044b3fe3358392b56d92b8c6fd6d208.jpg"
        }
      ]
    }
  }
}

<?xml version="1.0"?>
<response>
    <job>
        <jobId>130fe17ee35d8e0444d18aeed9265555ede53050</jobId>
        <jobTitle>My Site Plan</jobTitle>
        <jobReference>J888492240117</jobReference>
        <jobStatus>Complete</jobStatus>
        <jobDateSubmitted>2024-03-19 15:11:34</jobDateSubmitted>
        <jobCost>40.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
        <jobDateCompleted>2024-03-20 12:30:24</jobDateCompleted>
        <output>
            <file>
                <fileId>75eebcbab044b3fe3358392b56d92b8c6fd6d208</fileId>
                <fileURL>https://boxbrownie.b-cdn.net/completed/75eebcbab044b3fe3358392b56d92b8c6fd6d208.jpg</fileURL>
            </file>
        </output>
    </job>
</response>

Rework a Site Plan

POST /api/v2/job/reworkDevelopmentSitePlan

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

After a Development Site Plan 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.

Note: Development Site Plan 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 any supplied <fileId> values.

Example XML

Below, you can see an example XML payload. In this example, we are requesting 1 rework for the supplied jobId.

<job>
    <jobId>130fe17ee35d8e0444d18aeed9265555ede53050</jobId>
    <rework>
        <fileId>75eebcbab044b3fe3358392b56d92b8c6fd6d208</fileId>
        <reworkComment>Please add more clouds in the sky</reworkComment>
    </rework>
</job>

Example Response

{
  "success": "1"
}

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

Site Plan Options

GET /api/v2/job/developmentSitePlanOption

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

When creating a new Development Site Plan, you will supply an <options> block to tell us how you would like your image editing 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 site plan options and their accepted values. Alternatively, you can provide the optional optionName parameter to return only information and accepted values for that specific site plan option.

Example Response

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

{
  "options": [
    {
      "optionName": "NUMBER_OF_LOTS",
      "optionDescription": "Number of Lots",
      "optionRequired": "1",
      "optionType": "Multiple Choice",
      "optionValues": [
        {
          "optionValue": "LOTS_TIER_1",
          "optionValueDescription": "1 to 6",
          "optionValueCreditCost": "30.00"
        },
        {
          "optionValue": "LOTS_TIER_2",
          "optionValueDescription": "7 to 15",
          "optionValueCreditCost": "40.00"
        },
        {
          "optionValue": "LOTS_TIER_3",
          "optionValueDescription": "16 to 35",
          "optionValueCreditCost": "50.00"
        },
        ...
      ]
    },
    ...
  ]
}

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

<?xml version="1.0"?>
<response>
    <options>
        <optionName>NUMBER_OF_LOTS</optionName>
        <optionDescription>Number of Lots</optionDescription>
        <optionRequired>1</optionRequired>
        <optionType>Multiple Choice</optionType>
        <optionValues>
            <optionValue>LOTS_TIER_1</optionValue>
            <optionValueDescription>1 to 6</optionValueDescription>
            <optionValueCreditCost>30.00</optionValueCreditCost>
        </optionValues>
        <optionValues>
            <optionValue>LOTS_TIER_2</optionValue>
            <optionValueDescription>7 to 15</optionValueDescription>
            <optionValueCreditCost>40.00</optionValueCreditCost>
        </optionValues>
        <optionValues>
            <optionValue>LOTS_TIER_3</optionValue>
            <optionValueDescription>16 to 35</optionValueDescription>
            <optionValueCreditCost>50.00</optionValueCreditCost>
        </optionValues>
        ...
    </options>
    ...
</response>

URLhttps://www.boxbrownie.com/api/v2/job/developmentSitePlanOption/PLAN_STYLE

{
  "optionName": "PLAN_STYLE",
  "optionDescription": "Style Selection",
  "optionRequired": "1",
  "optionType": "Multiple Choice",
  "optionValues": [
    {
      "optionValue": "STYLE_WATERFORD",
      "optionValueDescription": "Waterford",
      "optionValueCreditCost": "0.00"
    },
    {
      "optionValue": "STYLE_MONTREAL",
      "optionValueDescription": "Montreal",
      "optionValueCreditCost": "0.00"
    },
    {
      "optionValue": "STYLE_KENSINGTON",
      "optionValueDescription": "Kensington",
      "optionValueCreditCost": "0.00"
    },
    ...
  ]
}

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

<?xml version="1.0"?>
<response>
    <optionName>PLAN_STYLE</optionName>
    <optionDescription>Style Selection</optionDescription>
    <optionRequired>1</optionRequired>
    <optionType>Multiple Choice</optionType>
    <optionValues>
        <optionValue>STYLE_WATERFORD</optionValue>
        <optionValueDescription>Waterford</optionValueDescription>
        <optionValueCreditCost>0.00</optionValueCreditCost>
    </optionValues>
    <optionValues>
        <optionValue>STYLE_MONTREAL</optionValue>
        <optionValueDescription>Montreal</optionValueDescription>
        <optionValueCreditCost>0.00</optionValueCreditCost>
    </optionValues>
    <optionValues>
        <optionValue>STYLE_KENSINGTON</optionValue>
        <optionValueDescription>Kensington</optionValueDescription>
        <optionValueCreditCost>0.00</optionValueCreditCost>
    </optionValues>
    ...
</response>

Accepted Site Plan Option

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

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

Option Name	Option Description	Type	Required?
NUMBER_OF_LOTS	Number of Lots	Multiple Choice	Yes
PLAN_STYLE	Style Selection	Multiple Choice	Yes
DISPLAY_NORTH	Display North	Multiple Choice	Yes
DISPLAY_MEASUREMENTS	Development Site Plan measurements to be displayed?	Free Text	Yes
DISPLAY_LOT_NUMBERS	Include Lot Numbers	Multiple Choice	Yes
DISCLAIMER_ACCURACY_MEASUREMENT	Disclaimer (Accuracy & Measurement)	Multiple Choice
FILE_SIZE	File Size Limit (MLS and other online websites)	Multiple Choice	Yes
DISPLAY_AGENCY_LOGO	Include an agency or developer logo?	Multiple Choice
DISPLAY_ADDRESS	Include Street/Building address to be displayed	Free Text	Yes
FILE_TYPE	Output File Type	Multiple Choice	Yes
DISPLAY_LEGEND	Display Legend	Multiple Choice
PLAN_ORIENTATION	Plan Orientation	Multiple Choice
PAGE_ORIENTATION	Page Orientation	Multiple Choice

Topics

Development Site Plan

Overview

Create a Development Site Plan

Example XML

Example Response

Simulate a Site Plan

Example Response

Retrieve a Development Site Plan

Example Response

Rework a Site Plan

Example XML

Example Response

Site Plan Options

Example Response

Accepted Site Plan Option