External Decision Engine

The External Decision Engine integration allows Biz Core to delegate loan application decisioning to a third-party system. It is a bidirectional B2B integration:

1. Outbound from Biz Core: Biz Core POSTs a comprehensive application snapshot to the third-party endpoint configured in the portal.
2. Inbound to Biz Core: The third-party system POSTs its decision back to a Biz Core API endpoint (see Response Contract).

This is distinct from the simple notification webhooks documented at Status Change Webhooks — those only require acknowledging receipt; this one requires implementing both halves of the contract.

When It Fires

The External Decision Engine push is triggered when an Application enters a status that requires external assessment — typically Processing, when the subscriber has configured a third-party decision engine for that loan product.

sequenceDiagram
    autonumber
    participant BC as Biz Core
    participant DE as External Decision Engine<br/>(your service)

    Note over BC: Application enters Processing
    BC->>DE: POST decision request<br/>(assessmentDetails snapshot)
    DE->>DE: Evaluate application<br/>against your rules / model
    DE->>BC: POST decision response
    Note over BC: Application transitions to<br/>Approved / Conditionally Approved / Declined

Request Payload

Top-level structure

assessmentDetails contents

This object contains everything an external decision engine needs to evaluate the application:

For the complete schema of each sub-object — including all fields elided from the example below with "...":"..." — see the Get Assessment Details reference page.

Example payload (abbreviated)

{
  "decisionRequestId": "fda97686-f8ae-43ac-bca5-7d865da0ddac",
  "decisionRequestTypeId": 0,
  "assessmentDetails": {
    "subscriptionId": "6ca2ff5b-a702-475a-99e3-c42bbb5c149d",
    "applicationId": "022b6321-7654-4451-b35a-efcaaaaaef9b",
    "applicationReference": "BCA056769A",
    "applicationStatus": "Processing",
    "applicationAmount": 3000,
    "lengthInWeeks": 52,
    "applicationFrequency": "Weekly",
    "loanProductName": "Secured Medium Personal Loans",
    "loanProductShortName": "SMACC",
    "customer": {
      "customerId": "699674a0-9d67-4ff6-8125-8c77fd24aac7",
      "customerReference": "BCC030635A",
      "customerFirstName": "Test",
      "customerLastName": "Test",
      "emailAddress": "[email protected]",
      "mobileNumber": "0400000000",
      "gender": "Male",
      "maritalStatus": "Married",
      "...": "additional customer fields"
    },
    "affordabilityDetails": {
      "frequencyName": "Weekly",
      "incomes": 2000,
      "expenses": 500,
      "commitments": 800,
      "netAmountBeforeLoan": 700,
      "newLoanRepayment": 80,
      "netAmount": 620,
      "incomeDetails": ["..."],
      "expenseDetails": ["..."],
      "commitmentDetails": ["..."]
    },
    "approvedLoanFees": [
      { "loanProductFeeName": "Missed Payment Fee", "loanFeeType": "Manual Fee", "amount": 39.95, "...": "..." },
      { "loanProductFeeName": "Interest", "loanFeeType": "Compound Interest", "amount": 47, "...": "..." }
    ],
    "creditCheckHistory": [
      { "creditCheckServiceType": "Equifax", "scores": [{ "scoreCard": "VedaScore Apply", "score": 706 }], "...": "..." },
      { "creditCheckServiceType": "Illion", "scores": [{ "scoreCard": "Illion Consumer Risk Score V2", "score": 686 }], "...": "..." }
    ],
    "documents": ["...array of documents..."],
    "identifications": ["...array of ID documents..."],
    "approvedTransactionSource": { "transactionSourceTypeName": "Bank Account", "...": "..." },
    "disbursementMethodSource": { "transactionSourceTypeName": "PayID", "...": "..." },
    "...": "many more fields — see the Get Assessment Details reference page"
  },
  "userDetails": {
    "userId": "f9e38b96-51a2-46de-8aed-888e553061ee",
    "displayName": "Test User",
    "emailUsername": "[email protected]",
    "givenName": "Test",
    "familyName": "User"
  }
}

Response Contract

📘

Your decision engine POSTs back to a Biz Core endpoint

After evaluating the application, your engine submits its decision to the Submit Application Decision endpoint. Authenticate with HAWK (same as all other Biz Core endpoints). See API reference →

For HAWK setup, see Getting Started — Implement HAWK Authentication.

Typical decision response types include:

• Approved with terms (amount, length, frequency, conditions)
• Conditionally Approved with required conditions to be fulfilled
• Declined with a reason
• Refer for manual review

ℹ️ Current behaviour: Confirm with FSoft how the response is processed in your installation before going live.

Previewing the Payload

📘

Preview the exact payload before going live

Use the Get Assessment Details endpoint with any existing application ID to retrieve the exact JSON your decision engine will receive — no need to wait for a real application to enter the trigger status. See API reference →

This is invaluable for building and testing your integration against real data shapes.

Configuration

Configure External Decision Engine through the Webhooks UI in the same way as status change webhooks — see Setting Up Webhooks — Configuring a Webhook. Select External Decision Engine as the event type.

Implementation Checklist

Before going live:

• Request and response schemas reviewed via the Get Assessment Details and Submit Application Decision reference pages.
• Receiving endpoint implemented and hosted on a stable, monitored URL with valid HTTPS.
• Your endpoint whitelists Biz Core's IP — your decision engine must accept inbound POSTs from Biz Core's IP addresses. Contact FSoft for the current IP range.
• Biz Core whitelists your IP — your engine will POST decisions back to Biz Core's submit-application-decision endpoint. Provide FSoft with your outbound IP address(es) so Biz Core can accept the inbound request.
• Idempotency handling using decisionRequestId to safely process duplicate deliveries.
• Logging and observability set up — decision requests and responses should be auditable.
• Tested in UAT against a sample application flow.
• Failure-mode behaviour agreed (e.g. how Biz Core proceeds if the decision endpoint times out or errors).
• Decision engine response latency benchmarked — extended response times will block the application's progression.