# Bees360 API v1

# API Endpoints

Production environment:

https://api.bees360.io/v1

Staging environment:

https://api.stag.bees360.io/v1

# Status Response Code

The following status code can be returned in HTTP responses.

HTTP Code HTTP Description Notes
2xx OK Request is handled successfully.
307 Temporary Redirect The resource has been relocated to a different location.
400 Bad Request Bad request format or invalid argument.
401 Unauthorized Invalid credentials, or token expires.
403 Forbidden Permission denied for a client already authenticated.
404 Not Found Resource is not available at the specified location.
409 Conflict Resource already exists.
422 Unprocessable Entity The request is well-formed but contains invalid data which makes the request cannot be processed.
429 Too Many Requests Some resource has been exhausted, perhaps a per-user quota
500 Internal Server Error Request failed due to Internal error.
503 Service Unavailable The service is currently unavailable.
504 Gateway Timeout The deadline is reached for the request. This error may be returned even when the request is handled successfully.

# Example Error response

400 BAD_REQUEST
{
    "error": {
        "message": "invailid project ID."
    }
}

# Authentication

To authenticate with Bees360 API, first request a client_id and a client_secret from Bees360 development team.

A client must act as a valid user on the Bees360 platform. The user's username and password is required when requesting access tokens.

# Acquire tokens

POST /oauth/token

Requests access_token and refresh_token from Bees360 API.

Currently we support client to use OAuth 2.0 Password Grant to authenticate.

The authentication request should use HTTP Basic authentication with client_id and client_secret.

# Request parameter grant_type required

grant_type should be set to password.

# Request parameter username required

The username of the user the client wants to act on behave of.

# Request parameter password required

The password of the user corresponds to the specified username.

# Request parameter scope optional

scope should be the name of one of the companys the user belongs to.

# Example request

curl -X POST -vu myClientId:myClientSecret https://api.bees360.io/v1/oauth/token \
     -H "Accept: application/json" \
     -d
"password=mypassword&username=myusername&grant_type=password&scope=ABC+INC"

# Example sucessful response:

{
  "access_token": "ff16372e-38a7-4e29-88c2-1fb92897f558",
  "token_type": "bearer",
  "refresh_token": "f554d386-0b0a-461b-bdb2-292831cecd57",
  "expires_in": 43199,
  "scope": "ABC INC",
  "user_id": 10030,
  "jti": "08ccb060-515f-46d0-aaa7-06e38fe94c03"
}

# Refresh token

POST /oauth/token

Acquire refreshed tokens using a valid refresh token.

# Request parameter grant_type required

The grant_type parameter must be set to refresh_token.

# Request parameter refresh_token required

A valid refresh token previously issued to client.

# Request parameter scope optional

scope should be the name of one of the company that the user belongs to.

# Example request

curl -X POST -vu myClientId:myClientSecret https://api.bees360.io/v1/oauth/token \
     -H "Accept: application/json" \
     -d "grant_type=refresh_token&refresh_token=f554d386-0b0a-461b-bdb2-292831cecd57"

# Example successful response

{
  "access_token": "f276df18-cfc2-454e-a6f2-3ec63578c73c",
  "token_type": "bearer",
  "refresh_token": "fb22be4a-2b85-48b3-bbc3-54b91ada9f71",
  "expires_in": 43199,
  "scope": "ABC INC"
  "user_id": 10030,
  "jti": "08ccb060-515f-46d0-aaa7-06e38fe94c03"
}

# Use token

When requesting any endpoints that require authentication, set Bearer [ACCESS_TOKEN] in the HTTP Authorization header.

# Example request

curl https://api.bees360.io/v1/project/1000012 \
    -H "Authorization: Bearer f276df18-cfc2-454e-a6f2-3ec63578c73c"

# Project API

# Create new project

POST /project

Creates a new project on Bees360 platform.

# Request parameter streetAddress required

The street address part of the address of the property to inspect.

# Request parameter city required

The city part of the address of the property to inspect.

# Request parameter state required

The state part of the address of the property to inspect.

# Request parameter zipcode required

The zipcode part of the address of the property to inspect.

# Request parameter country optional

The country part of the address of the property to inspect. Defaults to US.

# Request parameter serviceName required String

Specifies the project's service name.

Acceptable service names include:

[
    "Quick Inspect",
    "Full Adjustment",
    "Roof-only",
    "Exterior",
    "4-Point",
    "4-Point Self"
]

# Request parameter houseType optional String

Specifies the house type of the property. Acceptable values for House type are:

[
    "Residential Single Family",
    "Residential Condo",
    "Residential Townhouse",
    "Residential Multi Family",
    "Residential Apartment",
    "Commercial",
]

# Request paramter dueDate optional String

Specifies the due date for completion of the project, in YYYY-MM-DD format.

# Request paramter policyNumber optional String

Specifies the policy number related to this project.

# Request paramter inspectionNumber optional String

Specifies the inspection number related to this project.

# Request parameter insuredName optional String

Specifies the name of the insured.

# Request parameter insuredPhone optional String

Specifies the phone number of the insured.

# Request parameter insuredEmail optional String

Specifies the email address of the insured.

# Request parameter agentName optional String

Specifies the name of the agent.

# Request parameter agentPhone optional String

Specifies the phone number of the agent.

# Request parameter agentEmail optional String

Specifies the email address of the agent.

# Request parameter policyEffectiveDate optional String

Specifies the Policy Effective Date in YYYY-MM-DD format.

# Request parameter yearBuilt optional Number

Specifies the property's built year as a four-digit integer.

# Example request body:

{
    "streetAddress": "125 Hudson St, APT 708", // required
    "city": "New York",     // required
    "state": "NJ",          // required. Two letters representing a US state.
    "zipcode": "07302",     // required
    "country": "US",        // Currently only US is supported.
    "serviceName": "Quick Inspect", // required
    "houseType": "Residential Single Family",
    "dueDate": "2020-01-31",
    "policyNumber": "1234567",
    "inspectionNumber": "12345678",
    "insuredName": "Jane Doe",
    "insuredPhone": "2232131877",
    "insuredEmail": "insured@example.com",
    "agentName": "John Smith",
    "agentPhone": "1234567891",
    "agentEmail": "agent@example.com",
    "policyEffectiveDate": "2019-12-31",
    "yearBuilt": 1961,
}

Please do not use null as field value. Drop the JSON field if its value is not available.

# Example successful response:

{
    "project": [
        {
            "id": 10001,
            "streetAddress": "125 Hudson St, APT 708",
            "city": "New York",
            "state": "NJ",
            "zipcode": "07302",
            "country": "US",
            "serviceName": "Quick Inspect",
            "houseType": "Residential Single Family",
            "dueDate": "2020-01-31",
            "policyNumber": "1234567",
            "inspectionNumber": "12345678",
            "insuredName": "Jane Doe",
            "insuredPhone": "2232131877",
            "insuredEmail": "insured@example.com",
            "agentName": "John Smith",
            "agentPhone": "1234567891",
            "agentEmail": "agent@example.com",
            "policyEffectiveDate": "2019-12-31",
            "yearBuilt": 1961,
            "inspectionCode": "YN43AR", // 6 random character if `serviceName` is `4-Point Self`, otherwise ""(empty string)
            "inspectionLink": "http://ibees.app/YN43AR" // url for iBees if `serviceName` is `4-Point Self`, otherwise ""(empty string)
        }
    ]
}

# Get project details

GET /project/{projectId}

Retrives the details of the specified project.

# Request argument projectId (required)

The project ID previously returned when creating the project.

# Example successful response:

{
    "project": [
        {
            "id": 10001,
            "streetAddress": "125 Hudson St, APT 708",
            "city": "New York",
            "state": "NJ",
            "zipcode": "07302",
            "country": "US",
            "serviceName": "Quick Inspect",
            "dueDate": "2020-01-31",
            "houseType": "Residential Single Family",
            "policyNumber": "1234567",
            "inspectionNumber": "12345678",
            "insuredName": "Jane Doe",
            "insuredPhone": "2232131877",
            "insuredEmail": "insured@example.com",
            "agentName": "John Smith",
            "agentPhone": "1234567891",
            "agentEmail": "agent@example.com",
            "policyEffectiveDate": "2019-12-31",
            "yearBuilt": 1961,
            "inspectionCode": "",
            "inspectionLink": "",
        }
    ]
}

# Get project status

GET /project/{projectId}/status

Check the status of the specified project.

# Request argument projectId (required)

The project ID previously returned when creating the project.

# Example response:

{
    "project": [
        {
            "id": 10001, // project id
            "status": "Returned to Client",
        }
    ]
}

# Possible values for status:

[
    "Project Created",
    "Customer Contacted",
    "Assigned to Pilot",
    "Site Inspected",
    "Returned to Client", // report and images are available to download.
    "Project Canceled",
    "Client Received"// marked as received by client
    "Receive Error" // marked as error state by client
]

# Search projects by status

GET /project?status={projectStatus}&limit={countLimit}&start={startId}

Search the list of projects by project status. The list will be sorted base on the projectId in ascending order.

# Request parameter projectStatus optional

The status of projects to search for. See Possible values for status. When this parameter is omit, the operation will search for projects in any status.

# Request parameter limit optional

Limit the number of projects to return. The default value is 100. This value cannot exceed 500.

# Request parameter startId optional

Specify the returned projects has an ID that is larger than or equal to startId. You may combine this and limit to achieve pagination. The default value is 0.

# Example response

{
    "project": [
        {
            "id": 12345,
            "streetAddress": "125 Hudson St, APT 708",
            "city": "New York",
            "state": "NY",
            "zipcode": "10013",
            "country": "US",
            "serviceName": "Quick Inspect",
            "status": "Returned to Client",
        },
        {
            "id": 23456,
            "streetAddress": "37 Washington St.",
            "city": "Jersey City",
            "state": "NJ",
            "zipcode": "07302",
            "country": "US",
            "serviceName": "Quick Inspect",
            "status": "Returned to Client",
        }
    ]
}

# Update project status

PUT /project/{projectId}/status

# Request Parameter value String

Specifices the target status. Currently the only acceptable values are ["Client Received", "Receive Error", "Project Canceled"].

  • Client Received may only be triggered when the project's current status is Returned to Client.
  • Receive Error may be set regardless of the project's current status.
  • Project Canceled may be set regardless of the project's current status.

# Example Request Body

{
    "value": "Client Received",
}

# Example response

{
    "project": [
        {
            "id": 12345,
            "status": "Client Received",
        }
    ]
}

# Get project images

GET /project/{projectId}/image

Returns a list of images URLs and their descriptions.

# Request argument projectId (required)

The project ID previously returned when creating the project.

# Example response

{
    project: [
        {
            "id": 12345,
            "image": [
                {
                    "id": "4d0d5299-053a-40d0-82cd-da65a59df63d",
                    "source": "Drone",
                    "direction": "Front",
                    "type": "Close Up",
                },
                {
                    "id": "6d70013a-7aa3-4d62-a87f-b9ec724a4052",
                    "source": "Mobile",
                    "type": "Content",
                    "direction": "Rear",
                },
            ]
        }
    ]
}

# Get project image archive

GET /project/{projectId}/image/archive

When image archive is available to download, will return a 307 Temporary Redirect response, which redirects to a location to download the image archive.

The default Content-Type is application/zip. Currently, we only support .zip format.

# Request argument projectId (required)

The project ID previously returned when creating the project.

# Example response

307 Temporary Redirect
Content-Type: application/zip
Location: https://api.bees360.io/v1/project/12345/file/original_images_xxxxxx.zip
...

If the image archive is unavailable, returns HTTP 404 Not Found response.

The image archive is usually available after the project' status is turned to Returned to Client. However if the report type returned from GET /project/{projectID}/report is Inspection Closeout Report, which means the inspection is cancelled for whatever reason, the image archive will not be available.

# Get project's available reports

GET /project/{projectId}/report

Returns a list of reports available to download.

# Request argument projectId required

The project ID previously returned when creating the project.

# Example response

{
    project: [
        {
            "id": 12345,
            "report": [
                {
                    "id": 100123, // report id
                    "type": "Full-scope Underwriting Report", // report type
                }
            ]
        }
    ]
}

# Empty response (no report available)

{
    project: [
        {
            "id": 12345,
            "report": []
        }
    ]
}

# Available report types

Report Name Sample
Premium Damage Assessment Report Sample Report
Roof-only Underwriting Report Sample Report
Full-scope Underwriting Report Sample Report

# Report API

# Get report file

GET /report/{reportId}/file

If the report is available, will return a 307 Temporary Redirect response, which redirects to a location to download the report.

The default Content-Type will be application/pdf. Currently we only supported .pdf format.

# Request parameter compressed optional

Using compressed=true to get the compressed report. If there is a compressed report, return the expected response, otherwise return HTTP 404 Not Found response.

# Example response

307 Temporary Redirect
Content-Type: application/pdf
Location: https://api.bees360.io/v1/report/12345/file/roof_only_underwriting_report_xxxxxx.pdf
...

If the report file is unavailable, returns HTTP 404 Not Found response.

# Get report summary

GET /report/{reportId}/summary

# Attribute project.id Number

Specifies the project ID to which this report belongs to.

# Attribute project.serviceName Number

Specifies the project's service name.

# Attribute project.insuredName Number

Specifies the name of the insured involved in this report.

# Attribute project.inspectionTime Number

Specifies the inspection time for the report using the number of seconds since UNIX Epoch Time.

# Attribute project.completionTime Number

Specifies the completion time for the report using the number of seconds since UNIX Epoch Time.

# Attribute yearBuilt Number

The built year as a four-digit integer.

# Attribute lotSize Number

The lot size in acres.

# Attribute livingArea Number

The total living area in Sq.Ft..

# Attribute risk.overallCondition String

Overall risk condition, possible values include [ "Excellent", "Good", "Average", "Fair", "Poor" ].

# Attribute risk.AreaEconomy String

Status of area economy, possible values include [ "improving", "stable", "declining" ].

# Attribute risk.neighborhood String

Type of neighborhood, possible values include [ "Urban", "Suburban", "Rural" ].

# Attribute risk.gatedCommunity Boolean

Whether the property is located in a gated community.

# Attribute risk.isolatedDwelling Boolean

Whether the property is an isolated dwelling.

# Attribute risk.seasonalDwelling Boolean

Whether the property is a seasonal dwelling.

# Attribute risk.businessOperation String

A string representing the type of business operation of the property, possible values include ["Farming", "Gardening", "Professional Services"].

# Attribute risk.vacant Boolean

Whether the property is vacant.

# Attribute risk.rental Boolean

If the property is being rented (has tenants).

# Attribute bldg.overallCondition String

Building overall condition, possible values include [ "Excellent", "Good", "Average", "Fair", "Poor" ].

# Attribute bldg.construction String

Construction material, possible values include [ "Concrete Block", "Frame", "Fire Resistive" ].

# Attribute bldg.constructionOverWater String

Building partially or completed constructed over water.

# Attribute bldg.dwellingType String

Dwelling type, possible values include [ "Single-family", "Multi-family", "Condo" ].

# Attribute bldg.garage String

The type of garage, such as ["Attached", "Detached", "Built-in", "Carport", "None"].

# Attribute bldg.hvac String

The type of HVAC, such as ["Central", "Window Unit", "Split Unit", "Baseboard heating", "Gas forced air heating"].

# Attribute bldg.numStories Number

The number of stories of the main dwelling.

# Attribute bldg.windProtections List

List of any wind protections discovered, such as ["Impact Resistant Door", "High Impact Glass"]. If none observed, the field will be absent or has null value.

# Attribute bldg.hurricaneStraps Boolean

Whether hurricane straps was discovered.

# Attribute bldg.foundation String

The type of foundation, such as ["Slab on Grade", "Concrete Slab", "Basement"].

# Attribute bldg.manufacturedOrMobileHome String

Whether the building is manufactured or a mobile home.

# Attibute bldg.designatedHistoricHome Boolean

If building is Designated Historic Home.

# Attibute bldg.exteriorDamage Boolean

If the property has noticeable exisiting exterior damage.

# Attribute roof.estAge String

Estimated roof age, possible values include ["less than 1 year", "1 ~ 5 years", "5 - 10 years"].

# Attribute roof.estLife String

Estimated roof remaining life, possible values include ["less than 1 year", "1 ~ 5 years", "5 - 10 years"].

# Attribute roof.overallCondition String

Overall roof condition, possible values include [ "Excellent", "Good", "Average", "Fair", "Poor" ].

# Attribute roof.geometry Object

An object presenting roof geometry and its corresponding percentage. Possible properties include [ "Flat", "Gable", "Hip" ]. The value of each property presents its corresponding percentage.

# Attribute roof.comments List

List of comments to the roof.

# Attribute roof.material Object

A Object that records the roof material and its corresponding percentage. Possible roof material properties include [ "CompositeShingles", "BuildupRoofNoGravel", "ClayConcreteTiles", "LightMetalPanels", "SinglePlyMembrane", "SinglePlyMembraneBallasted", "Slate", "StandingSeamMetalRoof", "WoodenShingles" ].

# Attribute roof.coveringMaterial List

List of dominant covering material, including [ "Asphalt", "Modified Bitumen", "Metal", "Wood", "Tile", "Aluminum" ].

# Attribute roof.hasSolarPanel Boolean

Whether any solar panels present on roof.

# Attribute roof.hasCurlingShingles Boolean

If roof has curling shingles.

# Attribute roof.hasGranularLoss Boolean

If roof has granular loss.

# Attribute roof.hasMissingDamagedShingles Boolean

If roof has missing or damaged shingles.

# Attribute roof.hasPatchedAreas Boolean

If roof has been repaired with patches.

# Attribute roof.hasTarp Boolean

If roof has a tarp.

# Attribute exterior.overallCondition String

Whether the overall condition of exterior is satisfactory.

# Attribute exterior.siding Object

Siding material and its corresponding percentage. The object's properties are the name of the siding material, and the values represents its percentage. Possible values for siding materials include ["Asbestos", "Vingl", "Metal", "Stone", "Brick Veneer", "Hardiplank", "Stucco", "Concrete Block", "Wood Shake", "Aluminum", "Log", "Stone Veneer"].

# Attribute exterior.hasShutters Boolean

Whether any shutters discovered.

# Attribute exterior.hasPorch Boolean

Whether property has porch.

# Attribute exterior.hasStairsWithoutHandRails Boolean

If stairs are present without hand rails.

# Attribute exterior.hasYardDebris Boolean

If yard has excessive yard debris/trash.

# Attribute exterior.hasDiscardedVehicles Boolean

If yard has unregistered vehicles on premises.

# Attribute exterior.hasTreeLimbs Boolean

If there are trees or tree limbs touching or overhanging home.

# Attribute exterior.hasPoolWithoutFence Boolean

If pool present does it have a 4 ft fence with self locking gate?

# Attribute exterior.numDogPresent Number

# of dogs over 40lbs.

# Attribute exterior.hasDogPresent Boolean

List of text comments to exterior.

# Attribute exterior.comments List

List of text comments to exterior.

# Attribute interior.overallCondition String

Conditional of overall interior, possible values include ["Excellent", "Good", "Average", "Fair", "Poor"]

# Attribute interior.hasVisibleLeaks Boolean

If active or inactive leaks are visible.

# Attribute interior.hasExistingDamage Boolean

If there is existing interior damage is present.

# Attribute interior.plumbing.noShutoffValve Boolean

If there are any plumbing fixtures without shut off valves.

# Attribute interior.plumbing.hasOldWaterHeater Boolean

If the water heater is older than 15 years.

# Attribute interior.plumbing.hasPoorWaterHeaterCondition Boolean

If the water heater is rusting or in poor condition, has exposed wires or no TPR Valve.

# Attribute interior.electric.hasIneligiblePanel Boolean

Ineligible panel, Split bus, fuse boxes, Stablok, Federal Pacific, GTE-Sylvania, Challenger or Zinsco.

# Attribute addlStructures List

List of additional structures on the property, such as ["Storage Shed", "Horse Stable", "Garden", "Barn"].

# Attribute hazards List

List of text comments of hazards discovered.

# Attribute recommendations List

List of recommendations. Each recommendation is an object with a text property, and an image property. text is a String describing the recommendation, and image is an object that contains at least an id property that represents the image's unique identifier.

# Example response

{
    "report": [
        {
            "id": 98231,
            "type": "Full-scope Underwriting Report",
            "project": {
                "id": 12345,
                "inspectionNumber": "12345678",
                "serviceName": "Exterior",
                "insuredName": "Jane Doe",
                "inspectionTime": 1597609827,
                "completionTime": 1597629371
            },
            "summary": {
                "yearBuilt": 1945,
                "livingArea": 1560,
                "lotSize": 0.27,
                "risk": {
                    "overallCondition": "Good",
                    "areaEconomy": "Stable",
                    "neighborhood": "Suburban",
                    "gatedCommunity": false,
                    "isolatedDwelling": false,
                    "seasonalDwelling": false,
                    "businessOperation": "Farming",
                    "vacant": false,
                    "rental": true
                },
                "bldg": {
                    "overallCondition": "Good",
                    "dwellingType": "Single Family Detached",
                    "construction": "Frame",
                    "constructionOverWater": true,
                    "garage": "Attached",
                    "hvac": "Central",
                    "numStories": 2,
                    "windProtections": [
                        "None observed"
                    ],
                    "hurricaneStraps": false,
                    "foundation": "Basement",
                    "manufacturedOrMobileHome": "Manufactured",
                    "designatedHistoricHome": false,
                    "exteriorDamage": true
                },
                "roof": {
                    "overallCondition": "Good",
                    "estAge": "less than 1 year",
                    "estLife": "5 ~ 10 years",
                    "geometry": {
                        "Flat": 50,
                        "Gable": 20,
                        "Hip": 30
                    },
                    "coveringMaterial": [
                        "Asphalt"
                    ],
                    "hasSolarPanel": false,
                    "hasCurlingShingles": false,
                    "hasGranularLoss": false,
                    "hasMissingDamagedShingles": false,
                    "hasPatchedAreas": false,
                    "hasTarp": false,
                    "material": {
                        "CompositeShingles": 100,
                        "BuildupRoofNoGravel": 0,
                        "ClayConcreteTiles": 0,
                        "LightMetalPanels": 0,
                        "SinglePlyMembrane": 0,
                        "SinglePlyMembraneBallasted": 0,
                        "Slate": 0,
                        "StandingSeamMetalRoof": 0,
                        "WoodenShingles": 0
                    },
                    "comments": [
                        "Front Slope: Missing shingles.",
                        "Left Slope: Missing shingles."
                    ]
                },
                "exterior": {
                    "overallCondition": "Good",
                    "siding": {
                        "Hardiplank": 100
                    },
                    "hasShutters": false,
                    "hasPorch": true,
                    "hasStairsWithoutHandRails": false,
                    "hasYardDebris": false,
                    "hasDiscardedVehicles": false,
                    "hasTreeLimbs": false,
                    "hasPoolWithoutFence": false,
                    "numDogPresent": 15,
                    "hasDogPresent": false,
                    "comments": [
                         "Left Elevation: Broken window glass."
                    ]
                },
                "interior": {
                    "overallCondition": "Good",
                    "hasVisibleLeaks": false,
                    "hasExistingDamage": false,
                    "plumbing": {
                        "noShutoffValve": false,
                        "hasOldWaterHeater": false,
                        "hasPoorWaterHeaterCondition": false
                    },
                    "electric": {
                        "hasIneligiblePanel": false
                    }
                },
                "addlStructures": [ "Barn" ],
                "hazards": [
                    "Fireplace on exterior of front slope was noted.",
                    "The property is located about 237 ft. from the Laurel Lake.",
                    "2 dogs was spoted."
                ],
                "recommendations": [
                    {
                        "text": "Removal of Diving Board/Slides",
                        "image": [
                            {
                                "id": "3f1d8a93-0404-4419-b42d-72e25ef5cde8"
                            },
                            {
                                "id": "4e90cae0-7c29-4e7e-befa-f8a1d930ed4d"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

# Image API

# Get image file

GET /image/{imageId}/file

Get image by image Id.

# Request Argument imageId required

The ID of the specified image. This can be found either from Project API or Report API.

If image with the specified imageId is found, the server may directly return the image binary data or redirect the request to another location to access the image.

# Example Response

307 Temporary Redirect
Content-Location: http://example.com/xxxxxx.jpg
...

When the requested image does not exist, accessing the redirected URL will respond with 404 Not Found.

# Automated Testing Support

To facilitate using the staging environment for automated testing, all projects created with inspectionNumber=report_provided will be processed automatically within 5 minutes. This means any project created using inspectionNumber=report_provided in the staging environment, will have its status set to Returned to Client in 5 minutes. After its status is changed to Return to Client, you may access its reports and images.

The sample report and images will be static between difference projects, regardless of the project's information.