Deals API

A Deal represents an application or contract that is being evaluated—typically one in which multiple parties need to converge on a decision. Credit applications, equipment financing, fleet leasing, and commercial agreements all become Deals when they require coordination between borrowers, co-signers, guarantors, and other participants.

Deals share characteristics with Borrowers—workflow steps, custom fields, tags, and risk ratings. The key difference: a Borrower is an entity (a business or person), whereas a Deal is the specific application or agreement being evaluated, often involving multiple borrowers working toward approval.

A Deal serves as the central record that brings together everything related to that contract:

• Deal Fields: Store the specifics of what's being evaluated—financial terms, asset details, calculated scores, approval conditions
• Deal Contacts: Link the people involved—borrowers, co-signers, guarantors, brokers—each with their role in the application
• Workflow Executions: Track the automated processes that run against the deal—credit checks, valuations, risk calculations, compliance reviews
• Activity History: Record every change, evaluation, and decision made throughout the deal's lifecycle

The Deal Object

The Deal object represents an application or contract that is being evaluated in our system. When a customer applies for financing, leases equipment, or enters into any agreement requiring review and approval, that application becomes a Deal.

The Deal object itself holds identifying information: label, description, tags, and riskRating. The currentStep attribute indicates where the deal is in the process—whether it's under review, approved, requires additional information, or has been declined.

As parties are added or roles change, deal contacts are created or updated. The deal tracks its progression from initial submission through final decision.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "EXT-2024-001",
  "label": "Fleet Financing - ABC Trucking",
  "description": "Equipment financing for 5 Class 8 trucks",
  "tags": ["equipment", "fleet", "priority"],
  "riskRating": "B+",
  "currentStep": {
    "stepId": "step-456",
    "order": 2,
    "key": "credit_review",
    "label": "Credit Review",
    "createdAt": "2024-09-15T14:30:00Z"
  },
  "createdAt": "2024-09-10T10:00:00Z",
  "updatedAt": "2024-09-15T14:30:00Z"
}

Attributes

Nested Objects

Current Step

Deal Fields

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.

For complete documentation on Deal Fields, including detailed API endpoints, data type examples, and the Money data type structure, see the Deal Fields API documentation.

Deal Contacts

Deals often involve multiple parties. A financing application might require a primary borrower, one or more guarantors, co-borrowers, or co-signers. Deal Contacts link borrowers to deals and define each party's role in the transaction.

Each contact has a dealId, a borrowerId, a roleKey, and an isPrimary flag. The roleKey references Data Models with entityType="deal_role", which define the available roles. The isPrimary flag indicates the main contact for the deal.

As a deal progresses through evaluation, new parties can be added—additional guarantors identified during underwriting, co-signers brought in to strengthen the application, or other participants required to close the transaction.

{
  "id": "contact-456",
  "dealId": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "borrower-789",
  "roleKey": "primary_applicant",
  "isPrimary": true,
  "createdAt": "2024-09-10T10:00:00Z",
  "updatedAt": "2024-09-10T10:00:00Z"
}

Attributes

Endpoints

Create a Deal

POST /v1/deals

Input Parameters:

Example Request:

{
  "label": "Fleet Financing - ABC Trucking",
  "description": "Equipment financing for 5 Class 8 trucks",
  "tags": ["equipment", "fleet"]
}

Successful Response:

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

Get a Deal

GET /v1/deals/:deal_id

Returns the complete Deal object.

Update a Deal

PATCH /v1/deals/:deal_id

Input Parameters:

Delete a Deal

DELETE /v1/deals/:deal_id

Returns status code 204 (No Content) if successful.

List Deals

GET /v1/deals

Query Parameters:

Update External ID

PUT /v1/deals/:deal_id/external-id

Input Parameters:

Get Deal Steps

GET /v1/deals/:deal_id/steps

Returns all steps for the deal.

Get Current Step

GET /v1/deals/:deal_id/steps/current

Returns the deal's current step.

Set Current Step

PUT /v1/deals/:deal_id/steps/current

Input Parameters:

Create a Deal Contact

POST /v1/deal-contacts

Input Parameters:

Get a Deal Contact

GET /v1/deal-contacts/:contact_id

Returns the complete DealContact object.

Update a Deal Contact

PATCH /v1/deal-contacts/:contact_id

Input Parameters:

Delete a Deal Contact

DELETE /v1/deal-contacts/:contact_id

Returns status code 204 (No Content) if successful.

List Deal Contacts

GET /v1/deal-contacts

Query Parameters:

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.