Deal Fields API

Deal Fields store the actual data of the deal. When you need to know what a deal is about—the loan amount, asset details, applicant income, evaluation scores—you'll find that information in deal fields. When workflows execute against a deal, they write their results as deal fields.

Each field has a key, a label, a value, and a dataType. Fields are defined through Data Models with entityType="deal_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 five data types: string, number, date, boolean, and money.

Money Data Type

The money data type represents monetary values with an amount and currency. The amount is stored as a string to maintain precision and avoid floating-point rounding errors. The currency must be a 3-letter ISO currency code (e.g., "USD", "EUR", "MXN").

When creating or updating a money field, you can provide the amount as either a number or a string—the API will automatically convert numeric amounts to strings. The value structure is:

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

The DealField Object

The DealField object represents a custom field associated with a deal in the system.

{
  "id": "field-789",
  "dealId": "123e4567-e89b-12d3-a456-426614174000",
  "key": "loan_amount",
  "label": "Loan Amount",
  "value": {
    "amount": "25000.00",
    "currency": "USD"
  },
  "dataType": "money",
  "tags": ["financial", "terms"],
  "history": [
    {
      "referenceId": "workflow-exec-001",
      "value": {
        "amount": "20000.00",
        "currency": "USD"
      },
      "updatedAt": "2024-09-10T10:30:00Z"
    },
    {
      "referenceId": "manual-update-analyst",
      "value": {
        "amount": "25000.00",
        "currency": "USD"
      },
      "updatedAt": "2024-09-12T15:45:00Z"
    }
  ],
  "createdAt": "2024-09-10T10:30:00Z",
  "updatedAt": "2024-09-12T15:45:00Z"
}

Attributes

Nested Objects

Money

When dataType is money, the value field contains a Money object:

The amount is stored as a string to maintain precision. Numeric amounts provided in API requests are automatically converted to strings.

Historic Value

Endpoints

Create a Deal Field

Creates a new deal field in the system.

POST /v1/deal-fields

Input Parameters:

Example Request - Money Field:

{
  "dealId": "123e4567-e89b-12d3-a456-426614174000",
  "key": "loan_amount",
  "value": {
    "amount": 25000.00,
    "currency": "USD"
  },
  "dataType": "money",
  "referenceId": "workflow-exec-001",
  "tags": ["financial"]
}

Note: The amount can be provided as a number or string—both are accepted and converted to string for storage.

Example Request - Money Field (Type Inferred):

{
  "dealId": "123e4567-e89b-12d3-a456-426614174000",
  "key": "loan_amount",
  "value": {
    "amount": "25000.00",
    "currency": "USD"
  },
  "referenceId": "workflow-exec-001"
}

If dataType is omitted, the API will infer it as money based on the value structure.

Successful Response:

{
  "id": "field-789"
}

Status code: 201 (Created)

Get a Deal Field

Retrieves information of a specific deal field.

GET /v1/deal-fields/:field_id

Path Parameters:

Successful Response:

The response will be the complete DealField object.

Update a Deal Field

Updates an existing deal field.

PATCH /v1/deal-fields/:field_id

Path Parameters:

Input Parameters:

Example Request - Update Money Field:

{
  "dealId": "123e4567-e89b-12d3-a456-426614174000",
  "value": {
    "amount": 30000.00,
    "currency": "USD"
  },
  "referenceId": "manual-update-analyst",
  "tags": ["financial", "updated"]
}

The update will create a new history entry unless the referenceId matches the most recent history entry, in which case it updates that entry.

Successful Response:

The response will be the updated DealField object.

Delete a Deal Field

Deletes a deal field from the system.

DELETE /v1/deal-fields/:field_id

Path Parameters:

Successful Response:

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

List Deal Fields

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

GET /v1/deal-fields

Query Parameters:

Successful Response:

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

Data Type Examples

String Type

{
  "dealId": "deal-123",
  "key": "applicant_name",
  "value": "John Doe",
  "dataType": "string"
}

Number Type

{
  "dealId": "deal-123",
  "key": "credit_score",
  "value": 750,
  "dataType": "number"
}

Date Type

{
  "dealId": "deal-123",
  "key": "application_date",
  "value": "2024-01-15T00:00:00Z",
  "dataType": "date"
}

Boolean Type

{
  "dealId": "deal-123",
  "key": "is_approved",
  "value": true,
  "dataType": "boolean"
}

Money Type

{
  "dealId": "deal-123",
  "key": "loan_amount",
  "value": {
    "amount": "25000.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.