Lead Creation Guide

Submit and progressively update Personal Loan Application leads from external platforms into Biz Core.

ℹ️ Scope: Currently, only Personal Loan Application leads are supported. Support for additional lead types is on the roadmap.

Endpoint

📘

One endpoint for both creating and updating leads

The Submit Lead endpoint creates new lead records. Include an existing leadId in the payload to update a draft instead — useful for multi-page intake forms. See API reference →

The base URL depends on environment — see Getting Started — Base URLs.

Overview

The Leads Module exposes a single endpoint used to create a lead and update it incrementally until it is ready for processing. This supports step-by-step intake flows — for example, a multi-page web form where the customer can pause and resume — by allowing partial submissions to be stored progressively.

When the lead is complete, set isReadyForProcessing: true in the payload to mark it as finalised.

Lead Lifecycle

Lead records progress through the following statuses:

flowchart TD
    A([Initial POST]) --> B[Incomplete]
    B -->|isReadyForProcessing = true| C[Completed]
    C -->|Auto-process enabled<br/>+ canBeAutoProcessed = true| D([Application created])
    C -->|Manual review| E{Subscriber<br/>decision in portal}
    E -->|CREATE| D
    E -->|DISMISS| F([Dismissed])

    style A fill:#e6f1fb,stroke:#185fa5,color:#0c447c
    style D fill:#eaf3de,stroke:#3b6d11,color:#173404
    style F fill:#fcebeb,stroke:#a32d2d,color:#501313

Processing rules:

• Auto-processing requires both the API key to be configured for auto-processing and the per-lead canBeAutoProcessed flag to be true. If either is false, the lead remains in Completed until a subscriber processes it manually via the portal.
• When a subscriber clicks CREATE (or auto-processing triggers), Biz Core runs Customer Matching Rules before the lead is converted — linking it to an existing customer or creating a new one. The lead only transitions to Converted once this process completes. See Lead Management — Customer Matching Rules for the full matching logic.
• Status changes throughout the lifecycle can be received via Status Change Webhooks.

Authentication

The Leads Module uses HAWK authentication — see Getting Started — HAWK Authentication for implementation details, API key generation, and library recommendations. Once a key is generated, complete the activation step below.

Activating a key for Leads access

Leads Module keys require an additional activation step after generation:

1. In the portal, navigate to Settings → Advanced → Leads Settings.
2. Locate the relevant API key and toggle Active.

Invalid, disabled, or unrecognised keys return 401 Unauthorized.

Request

Minimum required payload

The example below contains the minimum fields required to submit a complete lead and immediately create an Application:

{
  "firstName": "Jane",
  "familyName": "Smith",
  "dateOfBirth": "1990-07-24T12:00:00.000Z",
  "nationality": 0,
  "gender": 1,
  "maritalStatus": 0,
  "occupation": "Software Engineer",
  "employmentIncome": 6000,
  "subscriptionId": "c08f84dc-840a-47eb-a27e-ddab42bedc6f",
  "leadSource": "Example Provider",
  "loanProduct": "SMACC",
  "amount": 4300,
  "paymentFrequency": 2,
  "lengthInWeeks": 52,
  "loanReason": 0,
  "emailContacts": [
    { "emailAddress": "[email protected]" }
  ],
  "phoneContacts": [
    { "phoneTypeId": 1, "phoneNumber": "0400000000", "countryId": 0 }
  ],
  "addressContacts": [
    {
      "premise": "46",
      "streetAddress": "46 Rita Street",
      "postalCode": "4883",
      "locality": "Atherton",
      "administrativeArea": "QLD",
      "country": "Australia"
    }
  ],
  "isReadyForProcessing": true,
  "canBeAutoProcessed": true
}

For the complete field schema including all optional properties, refer to the API Reference.

⚠️ Bank statement provider validation: If bankStatementProviderId is set to Illion (0), the fields bankStatementsCustomerId and bankStatementsEncryptionKey are required. If set to CreditSense (1), CS_App_ID must be present in identifiers. Missing these returns 400 Bad Request with field-level errors.

Progressive intake pattern

To save a partial lead and continue later:

1. Submit with isReadyForProcessing: false and leadId: null. The response returns a leadId.
2. On subsequent POSTs, include the returned leadId along with the complete payload — all fields must be resubmitted. This is not a partial update; fields omitted from the request will not be preserved.
3. When complete, submit with isReadyForProcessing: true.

Enum values used in the example above

For the complete enumeration of every coded field (employment type, vehicle type, etc.), refer to the API reference schema.

For lookups that may change over time, fetch them at runtime from the resource endpoints documented in Reference Data Endpoints and cache locally.

Response

Success

200 OK with the full lead record echoed back, including the generated leadId and reference:

{
  "result": {
    "lead": {
      "leadId": "2c197e13-4377-4096-8d8f-2ec260dc80e0",
      "reference": "BCB001730A",
      "...": "all submitted fields"
    }
  },
  "statusCode": 200
}

The full response schema is documented in the API Reference.