Assets API

An Asset represents any physical or financial item being evaluated, financed, or managed as part of a deal. Whether it's equipment, vehicles, real estate, machinery, or inventory, Assets provide structured tracking of items that require evaluation, valuation, and documentation.

Assets are always linked to a Deal through the dealId field. Just as a Deal can involve multiple parties (through Deal Contacts), a Deal can involve multiple Assets—each representing a distinct item being financed or managed.

Each Asset serves as a container for:

• Asset Fields: Store the specifics about the asset—make, model, year, condition, valuation, serial numbers, location
• Attachments: Link supporting documents—photos, appraisals, inspection reports, title documents, certificates
• Activity History: Track every change and evaluation made to the asset throughout its lifecycle

The Asset Object

The Asset object represents a physical or financial item associated with a deal in our system. When equipment financing, vehicle leasing, or property-backed lending requires tracking specific items, each item becomes an Asset.

The Asset object holds core identifying information: label, description, and an optional externalId for integration with external systems. The dealId links the asset to its parent deal.

{
  "id": "asset-123e4567-e89b-12d3-a456-426614174000",
  "dealId": "deal-789e4567-e89b-12d3-a456-426614174001",
  "externalId": "VIN-1HGBH41JXMN109186",
  "label": "2022 Caterpillar 320 Excavator",
  "description": "Heavy equipment excavator with 500 hours, excellent condition",
  "group": "heavy_equipment",
  "hasAttachments": true,
  "createdAt": "2024-09-10T10:00:00Z",
  "updatedAt": "2024-09-15T14:30:00Z"
}

Attributes

Endpoints

Create an Asset

Creates a new asset associated with a deal.

POST /v1/assets

Input Parameters:

Example Request:

{
  "dealId": "deal-789e4567-e89b-12d3-a456-426614174001",
  "label": "2022 Caterpillar 320 Excavator",
  "description": "Heavy equipment excavator with 500 hours, excellent condition",
  "externalId": "VIN-1HGBH41JXMN109186",
  "group": "heavy_equipment"
}

Successful Response:

{
  "id": "asset-123e4567-e89b-12d3-a456-426614174000"
}

Status code: 201 (Created)

Get an Asset

Retrieves information of a specific asset.

GET /v1/assets/:asset_id

Path Parameters:

Successful Response:

The response will be the complete Asset object.

Update an Asset

Updates an existing asset's label or description.

PATCH /v1/assets/:asset_id

Path Parameters:

Input Parameters:

Example Request:

{
  "label": "2022 Caterpillar 320 Excavator - Refurbished",
  "description": "Heavy equipment excavator with 500 hours, excellent condition, recently serviced"
}

Successful Response:

The response will be the updated Asset object.

Delete an Asset

Deletes an asset from the system.

DELETE /v1/assets/:asset_id

Path Parameters:

Successful Response:

Status code 204 (No Content) if the deletion was successful.

List Assets

Retrieves a paginated list of assets with filtering and sorting options.

GET /v1/assets

Query Parameters:

Successful Response:

The response will be a paginated list of Asset objects with an X-Total-Count header indicating the total number of matching assets.

Special Case - External ID Lookup:

When the external-id query parameter is provided, the API performs an exact match lookup and returns either:

• A single-item array containing the matching asset (with X-Total-Count: 1)
• An empty array if no match is found (with X-Total-Count: 0)

This behavior bypasses pagination and other filters.

Update External ID

Updates or sets the external ID for an asset.

PUT /v1/assets/:asset_id/external-id

Path Parameters:

Input Parameters:

Example Request:

{
  "externalId": "VIN-1HGBH41JXMN109186"
}

Successful Response:

Status code 204 (No Content) if successful.

Asset Attachments

Assets support file attachments for storing supporting documents such as photos, appraisals, inspection reports, and title documents.

Add Attachment by URL

Attach a document to an asset using a URL.

POST /v1/assets/:asset_id/attachments

Path Parameters:

Input Parameters:

Example Request:

{
  "url": "https://example.com/documents/appraisal-report.pdf",
  "label": "Equipment Appraisal",
  "metadata": {
    "appraiser": "ABC Valuation Services",
    "date": "2024-09-10"
  }
}

Successful Response:

Returns the created attachment object with its ID.

Upload Attachment

Upload a file directly to attach to an asset.

POST /v1/assets/:asset_id/attachments/upload

Path Parameters:

Input Parameters (multipart/form-data):

Successful Response:

Returns the created attachment object with its ID.

List Attachments

Retrieve all attachments for an asset.

GET /v1/assets/:asset_id/attachments

Path Parameters:

Successful Response:

Returns an array of attachment objects.

Delete Attachment

Remove an attachment from an asset.

DELETE /v1/assets/:asset_id/attachments/:attachment_id

Path Parameters:

Successful Response:

Status code 204 (No Content) if successful.

Asset Groups

Asset Groups allow you to categorize assets into logical categories for better organization and filtering. Before assigning assets to a group, you must first create the group as a Data Model with entityType: "asset_group".

Creating an Asset Group

First, create the asset group using the Data Models API:

POST /v1/data-models
{
  "entityType": "asset_group",
  "key": "vehicles",
  "label": "Vehicles"
}

POST /v1/data-models
{
  "entityType": "asset_group",
  "key": "heavy_equipment",
  "label": "Heavy Equipment"
}

Using Asset Groups

Once the group exists, you can assign assets to it:

POST /v1/assets
{
  "dealId": "deal-001",
  "label": "2024 Ford F-150",
  "group": "vehicles"
}

And filter assets by group:

GET /v1/assets?group=vehicles

Common Use Cases

Equipment Financing

Track multiple pieces of equipment in a single deal:

// Create assets for each piece of equipment
{
  "dealId": "deal-001",
  "label": "2022 Caterpillar 320 Excavator",
  "description": "Primary excavator",
  "externalId": "SN-CAT320-2022-001"
}
 
{
  "dealId": "deal-001",
  "label": "2023 John Deere 624L Loader",
  "description": "Front-end loader",
  "externalId": "SN-JD624L-2023-045"
}

Vehicle Fleet

Track a fleet of vehicles with consistent structure:

{
  "dealId": "deal-002",
  "label": "2024 Ford F-150 XLT",
  "description": "Fleet vehicle #12",
  "externalId": "VIN-1FTFW1E84NFA12345"
}

Then add asset fields for detailed specifications:

{
  "assetId": "asset-123",
  "key": "vin",
  "value": "1FTFW1E84NFA12345",
  "dataType": "string"
}
 
{
  "assetId": "asset-123",
  "key": "mileage",
  "value": 15000,
  "dataType": "number"
}
 
{
  "assetId": "asset-123",
  "key": "market_value",
  "value": {
    "amount": "45000.00",
    "currency": "USD"
  },
  "dataType": "money"
}

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.