Asset Fields API

Asset Fields store the data associated with assets in a deal. When you need to know about asset details—the equipment specifications, vehicle information, property characteristics, valuation results—you'll find that information in asset fields. When workflows execute against assets, they write their results as asset fields.

Each field has a key, a label, a value, and a dataType. Fields are defined through Data Models with entityType="asset_field", where you specify the field's type, label, and path. The path determines how fields are grouped and allows you to subcategorize fields into segments.

Each field tracks its value history. When updated, the system records a referenceId identifying the source of the change.

Fields support multiple data types: string, number, date, boolean, money, and money_array.

The AssetField Object

The AssetField object represents a custom field associated with an asset in the system.

{
  "id": "field-789",
  "assetId": "asset-123e4567-e89b-12d3-a456-426614174000",
  "key": "equipment_value",
  "label": "Equipment Value",
  "value": {
    "amount": "50000.00",
    "currency": "USD"
  },
  "dataType": "money",
  "tags": ["valuation", "equipment"],
  "history": [
    {
      "referenceId": "workflow-exec-001",
      "value": {
        "amount": "45000.00",
        "currency": "USD"
      },
      "updatedAt": "2024-09-10T10:30:00Z"
    },
    {
      "referenceId": "manual-update-analyst",
      "value": {
        "amount": "50000.00",
        "currency": "USD"
      },
      "updatedAt": "2024-09-12T15:45:00Z"
    }
  ],
  "createdAt": "2024-09-10T10:30:00Z",
  "updatedAt": "2024-09-12T15:45:00Z"
}

Attributes

Nested Objects

Historic Value

Money Type

When using the money data type, the value must be an object with the following structure:

Example:

{
  "amount": "50000.00",
  "currency": "USD"
}

Money Array Type

When using the money_array data type, the value must be an array of objects with the following structure:

Example:

[
  {
    "key": "principal",
    "label": "Principal Amount",
    "value": {
      "amount": "50000.00",
      "currency": "USD"
    }
  },
  {
    "key": "interest",
    "label": "Interest Amount",
    "value": {
      "amount": "5000.00",
      "currency": "USD"
    }
  }
]

Endpoints

Create an Asset Field

Creates a new asset field in the system.

POST /v1/asset-fields

Input Parameters:

*If dataType is not provided, the system will attempt to infer it from the value.

Example Request:

{
  "assetId": "asset-123e4567-e89b-12d3-a456-426614174000",
  "key": "equipment_value",
  "value": {
    "amount": "50000.00",
    "currency": "USD"
  },
  "dataType": "money",
  "tags": ["valuation", "equipment"]
}

Successful Response:

{
  "id": "field-789"
}

Get an Asset Field

Retrieves information of a specific asset field.

GET /v1/asset-fields/:field_id

Path Parameters:

Successful Response:

The response will be the complete AssetField object.

Update an Asset Field

Updates an existing asset field.

PATCH /v1/asset-fields/:field_id

Path Parameters:

Input Parameters:

Example Request:

{
  "assetId": "asset-123e4567-e89b-12d3-a456-426614174000",
  "value": {
    "amount": "55000.00",
    "currency": "USD"
  },
  "dataType": "money",
  "referenceId": "manual-update-analyst",
  "tags": ["valuation", "equipment", "updated"]
}

Successful Response:

The response will be the updated AssetField object.

Delete an Asset Field

Deletes an asset field from the system.

DELETE /v1/asset-fields/:field_id

Path Parameters:

Successful Response:

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

List Asset Fields

Retrieves a paginated list of asset fields with filtering and sorting options.

GET /v1/asset-fields

Query Parameters:

Successful Response:

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

Data Type Examples

String Type

{
  "assetId": "asset-123",
  "key": "make",
  "value": "Caterpillar",
  "dataType": "string"
}

Number Type

{
  "assetId": "asset-123",
  "key": "year",
  "value": 2020,
  "dataType": "number"
}

Date Type

{
  "assetId": "asset-123",
  "key": "purchase_date",
  "value": "2020-01-15T00:00:00Z",
  "dataType": "date"
}

Boolean Type

{
  "assetId": "asset-123",
  "key": "is_operational",
  "value": true,
  "dataType": "boolean"
}

Money Type

{
  "assetId": "asset-123",
  "key": "purchase_price",
  "value": {
    "amount": "125000.00",
    "currency": "USD"
  },
  "dataType": "money"
}

Money Array Type

{
  "assetId": "asset-123",
  "key": "cost_breakdown",
  "value": [
    {
      "key": "equipment",
      "label": "Equipment Cost",
      "value": {
        "amount": "100000.00",
        "currency": "USD"
      }
    },
    {
      "key": "installation",
      "label": "Installation Cost",
      "value": {
        "amount": "25000.00",
        "currency": "USD"
      }
    }
  ],
  "dataType": "money_array"
}

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.