1. Overview

Homestyler OpenAPI enables enterprise customers and partners to manage design-related data and automate downstream workflows through signed HTTP APIs.

  • Retrieve renderings and 720 virtual tours for users or projects within an enterprise account.
  • View, delete, and manage design projects.
  • Retrieve furniture used in designs to support quotation, merchandising, and recommendations.
  • Synchronize kitchen, bath, and custom-furniture design details to production systems.

1.1 Base URL

Code
https://global-api.homestyler.com

1.2 Content type

Unless otherwise specified, API requests use JSON.

Code
Content-Type: application/json

1.3 Standard request envelope

Field Type Required Description
appKey String Yes Public application key assigned by Homestyler.
timestamp Long Yes Client request timestamp in milliseconds.
sign String Yes MD5 signature generated with the endpoint-specific signature string.
...business fields Varies Varies Endpoint-specific parameters listed in the API reference.

1.4 Standard response envelope

Field Type Description
success Boolean Indicates whether the operation succeeded.
code String Error or status code. Empty or success-specific values depend on server implementation.
msg String Human-readable message.
data Object/Array Endpoint-specific response payload.
Code
{
 "success": true,
 "code": "0",
 "msg": "success",
 "data": { }
}

1.5 Pagination object

Field Type Description
pageSize Integer Number of items requested per page. Maximum is 100 where noted.
pageNo Integer Current page number.
total Integer Total number of records.

2. Authentication and Signing

2.1 Obtain credentials

Activate the Team Edition service and request AK/SK credentials from Homestyler. The application public key is sent as appKey; the secret key is retained server-side by the integrator and used only to generate signatures.

2.2 Signature generation

Each signed API lists its signature string. Concatenate values exactly in the specified order, without separators, append appSecret, and calculate the MD5 hexadecimal digest.

Code
// Example
appKey = "appKeyDemo"
appSecret = "appSecretDemo"
empId = "xxxxxx"
timestamp = 1680257066155

signString = appKey + empId + timestamp + appSecret
sign = md5(signString)
 = 3611b836afb0ebc8daf72ee6fe866b7a
  • Generate signatures only in trusted backend services. Never expose appSecret in browser, mobile, or client-side code.
  • Use HTTPS for all requests and uploads.
  • Use a fresh timestamp for each request. Reject or retry locally if the timestamp is stale.
  • Log request IDs and response codes, but never log appSecret or full signed strings in production logs.

3. Quick Start

3.1 List projects

The following example shows the general request pattern for a signed JSON API call.

Code
POST /global-team/hs/api/project/list
Content-Type: application/json

{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(empId + name + timestamp + appSecret)>",
 "empId": "E10001",
 "name": "Apartment",
 "pageSize": 20,
 "pageNo": 1
}

3.2 Floorplan import flow

Step API Purpose
1 Get upload URL Request a temporary object-storage URL for the floorplan source file.
2 Upload file PUT the USDZ or PNG file to the returned temporary URL.
3 Generate floorplan with file Create an asynchronous import job and receive scanId.
4 Get floorplan Poll until status is ANALYZE_SUCCESS or ANALYZE_FAIL. Timeout recommended by source: 120 seconds.
5 Export floorplan / bill Download floorplan output or bill by designId.

4. Endpoint Overview

Group Method Path Operation
Project POST /global-team/hs/api/project/list Get project list
Project POST /global-team/hs/api/project/detail Get project basic info
Project POST /global-team/hs/api/project/detail/delete Delete project
Floorplan POST /global-team/hs/api/floorplan/url Get temporary upload URL
File Upload PUT <temporary URL> Upload USDZ or PNG file
Floorplan POST /global-team/hs/api/floorplan/upload Generate floorplan with file
Floorplan POST /global-team/hs/api/floorplan/get Get floorplan processing status
Floorplan POST /global-team/hs/api/floorplan/download Export floorplan
Floorplan POST /global-team/hs/api/floorplan/bill/download Export bill
Rendering POST /global-team/hs/api/rendering/list Get renderings of a project
Admin POST /global-team/hs/api/admin/employee/list Get employee list
Admin POST /global-team/hs/api/admin/collaborate/emp Set collaboration permission
SKU POST /global-team/hs/api/sku/inventory Modify SKU inventory
Model POST /global-team/hs/api/model/brand Create or update brand
Model POST /global-team/hs/api/model/brand/query Query brand
Model POST /global-team/hs/api/model/folder/create Create folder
Model POST /global-team/hs/api/model/folder/relation/move Bind model to folder
Model POST /global-team/hs/api/model/delete Delete model
Model POST /global-team/hs/api/model/query Get model
Model POST /global-team/hs/api/model/tile/single Upload or modify tile
Model POST /global-team/hs/api/model/tile/mutil Upload or modify tile with multiple textures
Model POST /global-team/hs/api/model/three/dimensions Upload 3D model

5. Project APIs

5.1 Get project list

POST /global-team/hs/api/project/list

Query project details by employee and project name. Returned projects include design-stage and construction-stage projects.

Request parameters

Parameter Required Type Description
name No String Project name filter.
empId No String Employee ID filter.
pageSize Yes Integer Page length. Maximum 100.
pageNo Yes Integer Current page number.

Signature string

Code
empId + name + timestamp + appSecret

Response data

Field Type Description
page Page Pagination information.
items ProjectItem[] Project list.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(empId + name + timestamp + appSecret)>",
 "empId": "E10001",
 "name": "Apartment",
 "pageSize": 20,
 "pageNo": 1
}

ProjectItem

Field Type Description
id String Project ID.
name String Project name.
image String Project cover image.
lastTimeModified String Last update time.

5.2 Get project basic info

POST /global-team/hs/api/project/detail

Obtain basic information for a project. Enterprise users can access projects created within their enterprise account.

Request parameters

Parameter Required Type Description
id Yes String Project ID.

Signature string

Code
id + timestamp + appSecret

Response data

Field Type Description
id String Project ID.
name String Project name.
description String Project description.
versionId String Project version.
empId String Employee ID.
basicAttributes BasicAttributes Basic project attributes.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(id + timestamp + appSecret)>",
 "id": "project_123"
}

BasicAttributes

Field Type Description
area Double Project area.
bedroomNum Integer Number of bedrooms.
livingroomNum Integer Number of living rooms.
bathroomNum Integer Number of bathrooms.
style ProjectStyle Project style.

ProjectStyle

Field Type Description
code String Style or area code as returned by Homestyler.

5.3 Delete project

POST /global-team/hs/api/project/detail/delete

Delete a project by project ID.

Implementation note This is a destructive operation. Integrators should confirm permissions and maintain an audit trail before calling it.

Request parameters

Parameter Required Type Description
id Yes String Project ID.

Signature string

Code
id + timestamp + appSecret

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(id + timestamp + appSecret)>",
 "id": "project_123"
}

6. Floorplan APIs

6.1 Get upload URL

POST /global-team/hs/api/floorplan/url

Request a temporary file upload URL for USDZ or PNG floorplan source files.

Request parameters

Parameter Required Type Description
empId Yes String Real employee ID on the Homestyler platform.
fileType Yes String File type enumeration: usdz, png.

Signature string

Code
empId + fileType + timestamp + appSecret

Response data

Field Type Description
url String Temporary signed URL used to upload the file.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(empId + fileType + timestamp + appSecret)>",
 "empId": "E10001",
 "fileType": "usdz"
}

6.2 Upload file

PUT <temporary upload URL>

Upload the binary source file to the temporary URL returned by the Get upload URL API. This call is made to object storage rather than the Homestyler API host.

Implementation note Use Content-Type model/vnd.usdz+zip for USDZ files and image/png for PNG files. Include x-oss-object-acl: public-read.

Example request

Code
# USDZ example
curl --silent --location --request PUT '<temporary-usdz-url>' \
 --header 'x-oss-object-acl: public-read' \
 --header 'Content-Type: model/vnd.usdz+zip' \
 --data '@/path/to/scan.usdz'

# PNG example
curl --silent --location --request PUT '<temporary-png-url>' \
 --header 'x-oss-object-acl: public-read' \
 --header 'Content-Type: image/png' \
 --data '@/path/to/scan.png'

6.3 Generate floorplan with file

POST /global-team/hs/api/floorplan/upload

Transform a USDZ iOS RoomPlan file or supported image into a Homestyler floorplan.

Implementation note The operation is asynchronous. Store scanId and poll Get floorplan until a terminal status is returned.

Request parameters

Parameter Required Type Description
empId Yes String Real employee ID on Homestyler. Creation will fail if invalid.
coverImageFileUrl Yes String Cover image URL for the project to be generated.
url Yes String File URL returned by the upload URL process.
type No String USDZ or IMAGE. Default is USDZ.
grossArea No String Building area. Required when type is IMAGE.
projectName Yes String Project name. Maximum length 60.

Signature string

Code
coverImageFileUrl + empId + grossArea + projectName + url + timestamp + type + appSecret

Response data

Field Type Description
scanId String Generate request ID used for polling.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(coverImageFileUrl + empId + grossArea + projectName + url + timestamp +
type +
appSecret)>",
 "empId": "E10001",
 "coverImageFileUrl": "https://cdn.example.com/cover.png",
 "url": "https://object-storage.example.com/temporary/usdz/scan.usdz",
 "type": "USDZ",
 "projectName": "RoomPlan Import"
}

6.4 Get floorplan

POST /global-team/hs/api/floorplan/get

Poll floorplan import status and retrieve the designId when processing succeeds. Polling timeout in the source is 120 seconds.

Implementation note Continue polling for UPLOAD_SUCCESS or ANALYZING. Stop polling when ANALYZE_SUCCESS or ANALYZE_FAIL is returned.

Request parameters

Parameter Required Type Description
empId Yes String Real employee ID on Homestyler.
scanId Yes String scanId returned by Generate floorplan with file.

Signature string

Code
empId + scanId + timestamp + appSecret

Response data

Field Type Description
scanId String Generate request ID.
status String UPLOAD_SUCCESS, ANALYZING, ANALYZE_SUCCESS, or ANALYZE_FAIL.
designId String Returned only when status is ANALYZE_SUCCESS.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(empId + scanId + timestamp + appSecret)>",
 "empId": "E10001",
 "scanId": "scan_123"
}

6.5 Export floorplan

POST /global-team/hs/api/floorplan/download

Export a floorplan by designId.

Request parameters

Parameter Required Type Description
designId Yes String Design ID.
includeFurniture No Boolean Whether furniture is included.
outputType No String Output type. Source example: png.

Signature string

Code
designId + includeFurniture + outputType + timestamp + appSecret

Response data

Field Type Description
url String Temporary download URL. Must be downloaded within the validity period.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(designId + includeFurniture + outputType + timestamp + appSecret)>",
 "designId": "design_123",
 "includeFurniture": true,
 "outputType": "png"
}

6.6 Export bill

POST /global-team/hs/api/floorplan/bill/download

Export a bill for a floorplan/design.

Request parameters

Parameter Required Type Description
designId Yes String Design ID.

Signature string

Code
designId + timestamp + appSecret

Response data

Field Type Description
url String Temporary download URL. Must be downloaded within the validity period.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(designId + timestamp + appSecret)>",
 "designId": "design_123"
}

7. Rendering APIs

7.1 Get renderings of a project

POST /global-team/hs/api/rendering/list

Obtain renderings from the specified design project. Rendering details are returned in chronological order.

Request parameters

Parameter Required Type Description
projectId Yes String Project ID.
pageSize Yes Integer Page length. Maximum 100.
pageNo Yes Integer Current page number. Default 1.
renderType No String image, panorama, navipano, aerial, topview, or video.

Signature string

Code
projectId + timestamp + appSecret

Response data

Field Type Description
page Page Pagination information.
items RenderingItem[] Rendering list.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(projectId + timestamp + appSecret)>",
 "projectId": "project_123",
 "renderType": "image",
 "pageSize": 20,
 "pageNo": 1
}

RenderingItem

Field Type Description
renderId String Rendering ID.
url String Rendering address.
renderType String Rendering type.
subRenderType String Rendering subtype, for example 1k, 2k, or 4k for image renderings.

8. Admin APIs

8.1 Get employee list

POST /global-team/hs/api/admin/employee/list

Obtain the list of employees in the enterprise account.

Implementation note The source formula omits timestamp for this endpoint. Confirm with the Homestyler API team whether timestamp is still required in the request envelope.

Request parameters

Parameter Required Type Description
pageSize Yes Integer Page length. Maximum 100.
pageNo Yes Integer Current page number. Default 1.
name No String Employee name filter.

Signature string

Code
name + pageNo + pageSize + appSecret

Response data

Field Type Description
page Page Pagination information.
items Employee[] Employee list.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(name + pageNo + pageSize + appSecret)>",
 "name": "Lee",
 "pageSize": 20,
 "pageNo": 1
}

Employee

Field Type Description
name String Employee name.
email String Employee email.
empId String Employee ID.

8.2 Additive collaboration

POST /global-team/hs/api/admin/collaborate/emp

Set or update employee collaboration permission for a design.

Implementation note The original pages split this operation across two pages. The request parameters above consolidate the visible empId, designId, and operateType fields with the visible signature formula.

Request parameters

Parameter Required Type Description
empId Yes String Employee ID.
designId Yes String Design ID.
operateType Yes String READONLY, EDIT, or NO_PERMISSION.

Signature string

Code
designId + empId + operateType + timestamp + appSecret

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(designId + empId + operateType + timestamp + appSecret)>",
 "designId": "design_123",
 "empId": "E10001",
 "operateType": "EDIT"
}

9. SKU APIs

9.1 Modify inventory

POST /global-team/hs/api/sku/inventory

Modify SKU inventory by merchant SKU ID.

Request parameters

Parameter Required Type Description
skuId Yes String Merchant's own SKU ID.
num Yes Integer Inventory quantity.

Signature string

Code
num + skuId + timestamp + appSecret

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(num + skuId + timestamp + appSecret)>",
 "skuId": "SKU-10001",
 "num": 50
}

10. Model and Catalog APIs

10.1 Create or update brand

POST /global-team/hs/api/model/brand

Create or update a brand. A brand UUID is returned upon creation and should be stored by the integrator.

Request parameters

Parameter Required Type Description
uuid No String Leave blank for creation. Required for update.
brandName Yes String Brand name.
brandLogoUrl Yes String Brand logo URL.
type Yes String Operation type: create or update.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(brandLogoUrl + brandName + timestamp + appSecret)

Response data

Field Type Description
uuid String Brand UUID returned by Homestyler.

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(brandLogoUrl + brandName + timestamp + appSecret)>",
 "type": "create",
 "brandName": "Demo Brand",
 "brandLogoUrl": "https://cdn.example.com/logo.png"
}

10.2 Query brand

POST /global-team/hs/api/model/brand/query

Query brand information by brand name or UUID.

Request parameters

Parameter Required Type Description
brandName No String Query brand by name.
uuid No String Query brand by UUID.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(timestamp + appSecret)>",
 "brandName": "Demo Brand"
}

10.3 Create folder

POST /global-team/hs/api/model/folder/create

Create or modify model folders. The system creates a new folder when the folder name does not already exist.

Request parameters

Parameter Required Type Description
folderName Yes String Folder name, for example folder/sub-folder. Up to two levels.
folderType Yes String Folder type: 2d or 3d.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(folderType + folderName + timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(folderType + folderName + timestamp + appSecret)>",
 "folderType": "2d",
 "folderName": "Tiles/Marble"
}

10.4 Bind model to folder

POST /global-team/hs/api/model/folder/relation/move

Bind or move an uploaded model to one or more folders.

Request parameters

Parameter Required Type Description
modelId Yes String Model ID.
folderNameList Yes List Folder name list, for example ["folder/sub-folder"] or ["folder"].
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(modelId + timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(modelId + timestamp + appSecret)>",
 "modelId": "model_123",
 "folderNameList": ["folder/sub-folder"]
}

10.5 Delete model

POST /global-team/hs/api/model/delete

Delete one or more models or tiles.

Implementation note This is a destructive operation. Maintain an integration-side audit trail before deletion.

Request parameters

Parameter Required Type Description
idList Yes List Tile or model ID list.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(timestamp + appSecret)>",
 "idList": ["tile_001", "tile_002"]
}

10.6 Get model

POST /global-team/hs/api/model/query

Query model information by ID list.

Request parameters

Parameter Required Type Description
idList Yes List Tile or model ID list.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(timestamp + appSecret)>",
 "idList": ["tile_001"]
}

10.7 Upload tile

POST /global-team/hs/api/model/tile/single

Upload or modify a single-texture tile.

Request parameters

Parameter Required Type Description
id Yes String Unique tile ID.
category Yes String Category ID. Supplied by Homestyler.
materialEffect Yes String Material effect. Supplied by Homestyler.
name Yes String Tile name.
width Yes Integer Width in millimeters.
length Yes Integer Length in millimeters.
brandId Yes String Brand ID.
srcUrl Yes String Original texture resource URL.
folderNameList Yes List Folder list, for example ["folder/sub-folder"].
previewImage No String Preview image URL.
categoryIdentifyType Yes String Fixed value: id.
rotationAngle No String See Update Tile Filter and Rotation Angle API.
tileLookFilterList No JSON See Update Tile Filter and Rotation Angle API.
brandCollectionEnName No String Brand collection English name; use filter collectionName.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(category + id + materialEffect + name + timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(category + id + materialEffect + name + timestamp + appSecret)>",
 "id": "tile_001",
 "category": "5c10c875-c168-425a-9ee0-e53c03adddc6",
 "materialEffect": "material/marble tiles",
 "name": "Carrara White 600x600",
 "width": 600,
 "length": 600,
 "brandId": "brand_uuid",
 "srcUrl": "https://cdn.example.com/tile/carrara.png",
 "folderNameList": ["Tiles/Marble"],
 "categoryIdentifyType": "id"
}

10.8 Upload tile with multiple textures

POST /global-team/hs/api/model/tile/mutil

Upload or modify one tile with multiple textures.

Implementation note The source path uses "mutil" rather than "multi". Use the path exactly as provided.

Request parameters

Parameter Required Type Description
id Yes String Unique tile ID.
category Yes String Category ID. Supplied by Homestyler.
materialEffect Yes String Material effect. Supplied by Homestyler.
name Yes String Tile name.
width Yes Integer Width in millimeters.
length Yes Integer Length in millimeters.
brandId Yes String Brand ID.
srcUrl Yes String Original texture resource URL.
fileList Yes JSON Texture file list. Refer to Homestyler demo.
splicingMethod Yes JSON Splicing method. Refer to Homestyler demo.
folderNameList Yes List Folder list, for example ["folder/sub-folder"].
previewImage No String Preview image URL.
categoryIdentifyType Yes String Fixed value: id.
rotationAngle No String See Update Tile Filter and Rotation Angle API.
tileLookFilterList No JSON See Update Tile Filter and Rotation Angle API.
brandCollectionEnName No String Brand collection English name; use filter collectionName.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(category + id + materialEffect + name + timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(category + id + materialEffect + name + timestamp + appSecret)>",
 "id": "tile_multi_001",
 "category": "d7981192-acaf-4097-ba62-53af7e58daa7",
 "materialEffect": "material/tiles",
 "name": "Pattern Tile",
 "width": 600,
 "length": 600,
 "brandId": "brand_uuid",
 "srcUrl": "https://cdn.example.com/tile/base.png",
 "fileList": [],
 "splicingMethod": {},
 "folderNameList": ["Tiles/Pattern"],
 "categoryIdentifyType": "id"
}

10.9 Upload 3D model

POST /global-team/hs/api/model/three/dimensions

Upload or modify a 3D model.

Implementation note The source document references a category and supported model type table, but the actual values are not complete in the supplied PDF. Confirm category/subType values with the Homestyler API team before production upload.

Request parameters

Parameter Required Type Description
id Yes String Unique model ID.
category Yes String Category ID.
subType Yes String Affects default automatic adsorption behavior of the model.
name Yes String Model name.
brandId Yes String Brand ID.
srcUrl Yes String Supported file types: .zip, .rar, .max, .skp.
srcType Yes String max or skp.
folderNameList Yes List Folder list. For 3D models, Create Folder API folderType should use 3d.
tileLookFilterList No JSON See Update 3D Model Filter API.
brandCollectionEnName No String Brand collection English name; use filter collectionName.
appKey Yes String Application key.
timestamp Yes Long Request timestamp.
sign Yes String Request signature.

Signature string

Code
MD5(category + id + subType + name + timestamp + appSecret)

Example request

Code
{
 "appKey": "appKeyDemo",
 "timestamp": 1680257066155,
 "sign": "<md5(category + id + subType + name + timestamp + appSecret)>",
 "id": "model_001",
 "category": "<category-id>",
 "subType": "<sub-type>",
 "name": "Dining Chair",
 "brandId": "brand_uuid",
 "srcUrl": "https://cdn.example.com/model/chair.zip",
 "srcType": "max",
 "folderNameList": ["Furniture/Chair"]
}