Guides
  1. api-guides

Deals Guide

Understand when API workflows create dashboard deals and how to retrieve them.

A deal is the dashboard record your team can review and continue inside B2 Systems.

Create it directly with the Deal API, or let InFlow or TrueSight create it when create_deal is true.

The organization associated with the API key owns the created deal. Broker API keys create broker-owned deals, while funder API keys create funder-owned deals.

When to Create a Deal

Set create_deal to true when:

  • Your team wants to review the application in the B2 Systems dashboard.
  • You want the parsed or matched data tied to a dashboard record.
  • You expect later workflow steps to happen inside B2 Systems.

Keep create_deal as false when:

  • You only need parsing results.
  • You only need matching results.
  • Your CRM remains the primary system of record.

Create a Deal Directly

Use POST /v1/deals when your CRM or another parser already has the application or financial data and your team wants a dashboard record.

curl https://api.b2systems.io/v1/deals \
  -H "Authorization: Bearer $B2_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-deal-10044-create-v1" \
  -d '{
    "external_id": "crm-deal-10044",
    "auto_submit": "auto",
    "application": {
      "trade_name": "Main Street Pizza",
      "legal_name": "Main Street Pizza LLC",
      "business_tax_id": "12-3456789",
      "business_tax_id_country": "US",
      "business_tax_id_type": "EIN",
      "state_region": "NY",
      "country": "United States"
    },
    "financials": {
      "avg_monthly_true_revenue": 79000,
      "avg_daily_balance": 18440.11
    }
  }'

Provide application, financials, or both. The response returns the new deal_id. Use InFlow instead when B2 Systems needs to parse PDFs.

Tax IDs are format-validated. For United States businesses, business_tax_id_type accepts EIN, SSN, or ITIN; personal applicant IDs accept SSN or ITIN. For Canada, business IDs accept BN, SIN, CANADIAN_ITN, or TTN, while personal IDs accept the latter three. B2 Systems accepts values without separators only when their type can be determined unambiguously. Otherwise, include the country and type explicitly. Invalid or ambiguous tax IDs return 422 Unprocessable Entity with the validation_failed code and do not create or update a deal.

For broker deals, auto_submit defaults to auto and follows the same dashboard setting and entitlement as a dashboard-created deal. Use disabled to prevent auto-submit for this deal. The API does not force-enable auto-submit. Funder-owned deals do not auto-submit.

Deal Creation From InFlow

When create_deal is true on POST /v1/inflow/parsing, B2 Systems creates a dashboard deal and returns deal_id.

After parsing completes, the deal is updated with parsed application and financial data.

Deal Creation From TrueSight

When create_deal is true on POST /v1/truesight/matching, B2 Systems creates or updates a dashboard deal with the supplied application, financials, and matching results.

If matching is run from a parsing_id that already created a deal, the existing deal is updated.

Matching results are stored separately from the deal record and linked to the deal as the active match run. That lets the dashboard and public API return the latest completed matching results without requiring the full deal record to carry every historical match payload.

Retrieve a Deal

curl https://api.b2systems.io/v1/deals/6f0d7a53-4d45-4ebf-b7ac-6439f3388a1f \
  -H "Authorization: Bearer $B2_API_KEY"

The deal response includes:

  • deal_id
  • external_id
  • stage
  • auto_submit
  • application
  • financials
  • funder_results
  • created_at
  • updated_at

funder_results reflects the deal's latest active matching results. It can be empty when no matching run has completed for the deal yet.

The response includes the full stored application and applicant fields supplied by your organization, including sensitive merchant and applicant fields. Treat it as confidential server-side data.

Link to the Dashboard

Use the returned deal_id to construct a direct dashboard link:

  • Broker-owned deal: https://dashboard.b2systems.io/deals/{deal_id}
  • Funder-owned deal: https://funders.b2systems.io/deals/{deal_id}

The user opening the link must be signed in and have access to the organization that owns the deal. A broker-owned deal_id identifies the broker's deal; it is not the id of a separate funder-owned copy created through submission.

Update a Deal

Use PATCH /v1/deals/{deal_id} to change application, financial, reconciliation, or auto-submit data. Omitted top-level fields remain unchanged. When supplied, collection fields such as applicants, months, and positions replace that collection.

curl -X PATCH https://api.b2systems.io/v1/deals/6f0d7a53-4d45-4ebf-b7ac-6439f3388a1f \
  -H "Authorization: Bearer $B2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application": {
      "requested_amount": 85000
    },
    "auto_submit": "disabled"
  }'

Once API-triggered auto-submit is disabled for a deal, later API operations do not silently re-enable it.

Deal Stages

The public stage field describes the deal's general dashboard stage. Possible values are:

  • Potential
  • New submission
  • ISO review
  • Processing
  • Underwriting
  • Closed

The stage is intentionally broader than the funder-specific workflow shown in the dashboard. It does not identify an individual offer, information request, contract, or final-and-stips action.

Access Rules

An API key can only retrieve deals owned by the same organization as the key.

Broker API keys can retrieve broker-owned deals for their organization. Funder API keys can retrieve funder-owned deals for their organization.

If a deal is not visible to the organization, the API returns not_found.

Dashboard Workflow Boundary

Creating a deal through the public API does not create a linked deal for another organization. A broker deal is considered for submission only through the existing dashboard auto-submit rules when auto_submit is auto.

Funder submission and the following funder-specific actions are managed in the B2 Systems dashboards and are not public API operations in this version:

  • Offers and offer acceptance
  • Information requests
  • Contract requests
  • Final and stips
  • External action links
  • Deal notes and supporting documents

GET /v1/deals/{deal_id} returns the general deal stage, application, financials, and latest matching results. It does not return the complete per-funder dashboard workflow.

Updated 18 days ago

Did this page help you?