Asset Enrichment

The Bluon Asset Enrichment API is a simple way to bulk-enrich assets from a CSV, or to send single one-off assets to the endpoint for enrichment with Bluon data. Submit the model number (and optionally brand and serial number) you already have on file, and Bluon matches each asset to its OEM model and returns the model details, specifications, equipment image, manufacturing date, and warranty status.

How It Works

1. Submit assets

Upload a CSV for bulk enrichment, or POST a single asset as JSON.

2. Bluon enriches

Each asset is queued, matched against the Bluon database, and decoded for age and warranty.

3. Retrieve results

Poll the request for batch progress, then list or fetch assets to read the enriched data.

Base URL

{{base_url}}/enrichment/{{partner}}/...

Asset Enrichment endpoints live under /enrichment/ rather than the /gateway/ path used by the other Bluon API endpoints. Authentication is the same Bearer token described in the API Overview. The optional distributor query parameter is accepted on every endpoint to scope requests to a specific distributor ID.

Endpoints

Method	Path	Purpose
POST	/enrichment/{partner}/requests/upload	Bulk-enrich assets from a CSV file
POST	/enrichment/{partner}/assets	Enrich a single asset
GET	/enrichment/{partner}/requests	List enrichment requests and batch progress
GET	/enrichment/{partner}/assets	List, search, and filter assets
GET	/enrichment/{partner}/assets/{asset}	Get the full enriched record for one asset

1. Bulk Enrichment (CSV Upload)

Upload a CSV of assets to create a single enrichment request. Every row becomes an asset that is enriched asynchronously. Use this for onboarding an existing customer equipment list or syncing a large asset base.

Endpoint

POST {{base_url}}/enrichment/{{partner}}/requests/upload

Request

file (file, required) - CSV file sent as multipart/form-data. Maximum size 100 MB.

Example CSV

Column headers match the single-asset fields below. Only model_number is required; include as many of the other columns as you have.

model_number,brand,serial_number,customer_name,customer_address,unique_id,date_added,type_of_service,notes
CB26UH-042-1,Lennox,5804G12345,Junction City Air,"5th Walk, 5512",EQ-00002,2026-01-01,install,Attic air handler
GSX130301BA,Goodman,0905701775,Joe Peterson,"1200 Main St, Austin TX",EQ-00003,2025-11-14,maintenance_service,
RLMB-A048JK000,Rheem,W391501234,Riverside Dental,"88 Harbor Blvd",EQ-00004,2026-02-20,install,Rooftop package unit

Example Curl

curl -X 'POST' \
  'https://test.hub.bluontoolbox.com/uat/enrichment/partner123/requests/upload' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@assets.csv;type=text/csv'

Response

Returns 201 Created once the file is accepted. Enrichment runs in the background. Track progress with List Enrichment Requests, then read results with List Assets or Get Asset by ID. A 422 is returned if the file is missing or invalid:

{
  "message": "The file field is required.",
  "errors": {
    "file": [
      "The file field is required."
    ]
  }
}

2. Single Asset Enrichment

Send one asset as JSON for enrichment. Ideal for one-off additions from your application, such as when a technician logs a new piece of equipment or a customer record is created.

Endpoint

POST {{base_url}}/enrichment/{{partner}}/assets

Body Parameters

Name	Type	Required	Description
`model_number`	string	required	Equipment model number as it appears on the nameplate
`brand`	string	optional	Manufacturer brand. Improves match confidence.
`serial_number`	string	optional	Serial number. Required for manufacturing date and warranty decoding.
`customer_name`	string	optional	Customer or site name
`customer_address`	string	optional	Installation address
`unique_id`	string	optional	Your own identifier for the asset, for reconciling results with your system
`date_added`	date	optional	Date the asset was added, in YYYY-MM-DD format
`type_of_service`	string	optional	`install` or `maintenance_service`
`notes`	string	optional	Free-text notes

All string fields have a maximum length of 255 characters.

Example Curl

curl -X 'POST' \
  'https://test.hub.bluontoolbox.com/uat/enrichment/partner123/assets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model_number": "CB26UH-042-1",
    "brand": "Lennox",
    "serial_number": "5804G12345",
    "customer_name": "Junction City Air",
    "customer_address": "5th Walk, 5512",
    "unique_id": "EQ-00002",
    "date_added": "2026-01-01",
    "type_of_service": "install"
  }'

Example Response (201 Created)

The asset is created with status: pending and enriched asynchronously. Store the returned id and fetch it with Get Asset by ID to read the results.

{
  "data": {
    "id": "940ca1b1-5a80-4685-aa64-41e335f3f145",
    "status": "pending",
    "match_type": null,
    "model_number": "CB26UH-042-1",
    "brand": "Lennox",
    "serial_number": "5804G12345",
    "customer_name": "Junction City Air",
    "customer_address": "5th Walk, 5512",
    "unique_id": "EQ-00002",
    "date_added": "2026-01-01T00:00:00.000000Z",
    "custom_data": null,
    "notes": null,
    "created_at": "2026-09-01T15:31:20.000000Z",
    "updated_at": "2026-09-01T15:31:20.000000Z",
    "request": {
      "id": "c621a74c-15e0-46cd-98c3-5d575a5ac950",
      "added_from": "manual-entry",
      "added_by": "jane@example.com",
      "status": "pending"
    }
  }
}

3. List Enrichment Requests

Every CSV upload and single-asset POST creates an enrichment request. This endpoint lists those requests with a count of assets in each status, so you can track batch progress without polling individual assets.

Endpoint

GET {{base_url}}/enrichment/{{partner}}/requests

Example Curl

curl -X 'GET' \
  'https://test.hub.bluontoolbox.com/uat/enrichment/partner123/requests' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]'

Example Response

{
  "data": [
    {
      "id": "429a4183-4b3f-4a09-9fe5-d4a624f6cec5",
      "added_from": "batch-import",
      "added_by": "jane@example.com",
      "status": "processing",
      "asset_status": {
        "failed": 0,
        "incomplete": 3,
        "completed": 412,
        "not_found": 9,
        "pending": 76,
        "processing": 0
      }
    },
    {
      "id": "c621a74c-15e0-46cd-98c3-5d575a5ac950",
      "added_from": "manual-entry",
      "added_by": "jane@example.com",
      "status": "completed",
      "asset_status": {
        "failed": 0,
        "incomplete": 0,
        "completed": 1,
        "not_found": 0,
        "pending": 0,
        "processing": 0
      }
    }
  ],
  "links": {
    "first": "https://test.hub.bluontoolbox.com/uat/enrichment/partner123/requests?page=1",
    "last": "https://test.hub.bluontoolbox.com/uat/enrichment/partner123/requests?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://test.hub.bluontoolbox.com/uat/enrichment/partner123/requests",
    "per_page": 15,
    "to": 2,
    "total": 2
  }
}

4. List Assets

Paginated list of your assets with a summary of each enrichment. Supports search, sorting, and a rich set of filters for status, match quality, equipment age, and warranty position.

Endpoint

GET {{base_url}}/enrichment/{{partner}}/assets

Query Parameters

Name	Type	Description
`search_string`	string	Free-text search across assets
`page` / `per_page`	integer	Pagination. Default 15 per page.
`sort_criteria`	string	`model_number` (default), `customer_name`, `updated_at`
`sort_order`	string	`asc` (default) or `desc`
`status`	string	Filter by asset status (see Asset Status below)
`match_type[]`	array	Filter by match quality (see Match Types below)
`added_from[]`	array	`manual-entry`, `batch-import`, `nameplate-scan`, `app-search`
`added_by`	string	User ID or email of the user who added the asset
`date_added_preset`	string	`today`, `last_7_days`, `last_30_days`
`date_modified_preset`	string	`today`, `last_7_days`, `last_30_days`
`equipment_age_min_years` / `equipment_age_max_years`	number	Filter by decoded equipment age. Min must be less than or equal to max.
`warranty_basis`	string	`registered` or `not_registered`. Must be sent together with `warranty_expiration_tier[]`.
`warranty_expiration_tier[]`	array	`in_warranty`, `expiring_within_3_months`, `expiring_within_6_months`, `expiring_within_1_year`, `expiring_within_2_years`, `expired_past_12_months`, `expired_over_1_year`
`type_of_service[]`	array	`install`, `maintenance_service`
`type`	string	Filter by matched equipment type (e.g. Furnaces, Air Handlers)
`unique_id`	string	Look up an asset by the unique_id you supplied

Example Curl

Completed assets whose registered warranty expires within the next 6 months, newest first:

curl -X 'GET' \
  'https://test.hub.bluontoolbox.com/uat/enrichment/partner123/assets?status=completed&warranty_basis=registered&warranty_expiration_tier[]=expiring_within_6_months&sort_criteria=updated_at&sort_order=desc&per_page=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]'

Example Response

{
  "data": [
    {
      "id": "1e58a657-d771-4c08-b985-6d1a540c7149",
      "status": "completed",
      "match_type": "exact_match",
      "model_number": "CB26UH-042-1",
      "brand": "Lennox",
      "serial_number": "5804G12345",
      "customer_name": "Junction City Air",
      "customer_address": "5th Walk, 5512",
      "unique_id": "EQ-00002",
      "date_added": "2026-01-01T00:00:00.000000Z",
      "extra_data": null,
      "notes": null,
      "created_at": "2026-08-27T12:52:07.000000Z",
      "updated_at": "2026-08-27T14:20:36.000000Z",
      "request": {
        "id": "429a4183-4b3f-4a09-9fe5-d4a624f6cec5",
        "added_from": "batch-import",
        "added_by": "jane@example.com",
        "status": "completed"
      },
      "enrichment": {
        "id": "82aa1448-2f17-4944-a93f-215a995050dd",
        "source": "search",
        "confidence_score": 1,
        "model": "CB26UH-042-1",
        "model_notes": "Air Handler, 3.5 Ton, R-410A, Upflow/Horizontal",
        "type": "Air Handlers",
        "brand": "Lennox",
        "image": "https://assets-bluon-prod.sfo3.cdn.digitaloceanspaces.com/oems/unit_image/LX_CB26UH.png"
      },
      "warranty": {
        "manufacturing_date": "2004-01"
      }
    }
  ],
  "links": {
    "first": "https://test.hub.bluontoolbox.com/uat/enrichment/partner123/assets?page=1",
    "last": "https://test.hub.bluontoolbox.com/uat/enrichment/partner123/assets?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://test.hub.bluontoolbox.com/uat/enrichment/partner123/assets",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

5. Get Asset by ID

Returns the complete enriched record for one asset: the matched OEM model, free-form specifications, equipment image, decoded manufacturing date, and full warranty status for both registered and unregistered policies.

Endpoint

GET {{base_url}}/enrichment/{{partner}}/assets/{{asset}}

Example Curl

curl -X 'GET' \
  'https://test.hub.bluontoolbox.com/uat/enrichment/partner123/assets/1e58a657-d771-4c08-b985-6d1a540c7149' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]'

Example Response

{
  "id": "1e58a657-d771-4c08-b985-6d1a540c7149",
  "status": "completed",
  "match_type": "exact_match",
  "model_number": "CB26UH-042-1",
  "brand": "Lennox",
  "serial_number": "5804G12345",
  "customer_name": "Junction City Air",
  "customer_address": "5th Walk, 5512",
  "unique_id": "EQ-00002",
  "date_added": "2026-01-01T00:00:00.000000Z",
  "extra_data": null,
  "notes": null,
  "created_at": "2026-08-27T12:52:07.000000Z",
  "updated_at": "2026-08-27T14:20:36.000000Z",
  "request": {
    "id": "429a4183-4b3f-4a09-9fe5-d4a624f6cec5",
    "added_from": "batch-import",
    "added_by": "jane@example.com",
    "status": "completed"
  },
  "enrichment": {
    "id": "82aa1448-2f17-4944-a93f-215a995050dd",
    "source": "search",
    "confidence_score": 1,
    "model": "CB26UH-042-1",
    "model_notes": "Air Handler, 3.5 Ton, R-410A, Upflow/Horizontal",
    "type": "Air Handlers",
    "brand": "Lennox",
    "image": "https://assets-bluon-prod.sfo3.cdn.digitaloceanspaces.com/oems/unit_image/LX_CB26UH.png",
    "oem_id": "3AABC50C-73A4-49AF-AABD-8732B4872692",
    "specifications": {
      "model_data": {
        "nominal_tons": "3.5",
        "refrigerant": "R-410A",
        "voltage": "208/230",
        "phase": "1",
        "configuration": "Upflow/Horizontal"
      },
      "part_data": null
    },
    "warranty": {
      "manufacturing_date": "2004-01"
    }
  },
  "warranty": {
    "detail": "Comprehensive 10-year warranty on all parts for registered products, 5 years for all parts when unregistered.",
    "manufacturing_date": "2004-01",
    "registered_warranty_active": false,
    "registered_warranty_expiration_date": "2014-01-01",
    "standard_warranty_registered": 10,
    "standard_warranty_unregistered": 5,
    "unregistered_warranty_active": false,
    "unregistered_warranty_expiration_date": "2009-01-01"
  }
}

Response Fields

status / match_type - Where the asset is in the pipeline and how confident the match is
enrichment - The matched Bluon model: oem_id, canonical model, type, brand, image, and confidence_score (0 to 1)
enrichment.specifications.model_data - Free-form key/value specifications from the matched model. part_data is populated when the match came from a part.
warranty - Manufacturing date (YYYY-MM), standard warranty terms in years, and whether each policy is still active with its expiration date
enrichment and warranty are null until the asset has been processed, or when no match could be made

Asset Status

Each asset moves through these statuses. Request-level asset_status counts use the same values.

Status	Meaning
`pending`	Accepted and queued for enrichment
`processing`	Currently being matched and decoded
`completed`	Matched to a Bluon model with enrichment data available
`incomplete`	Partially enriched. Typically a model match without a decodable serial number, or vice versa.
`not_found`	No matching model in the Bluon database
`failed`	Enrichment could not be run, usually due to invalid input

Match Types

exact_match

The submitted model number matched a Bluon model exactly.

likely_match

High-confidence match after normalizing the model number (e.g. revision suffixes).

possible_match

A candidate model was found but confidence is lower. Review before relying on specifications.

nameplate_only

Nameplate data was captured but no model match was made.

Notes

Enrichment is asynchronous. Both the CSV upload and the single-asset POST return immediately; poll for results.
Include serial_number whenever you have it. Without it, manufacturing date and warranty cannot be decoded.
Use unique_id to carry your own asset identifier through the pipeline and reconcile results with your records.
CSV uploads are limited to 100 MB per file. Split larger asset lists into multiple uploads.
List endpoints are paginated and return standard links and meta objects.
Age and warranty decoding uses the same engine as the Age & Warranty endpoint, so the same brand coverage applies.