Neuron Broker Experience API

✅ Neuron Broker Experience API

The Neuron Broker Experience API provides brokers with a secure, real-time interface for submission lifecycle management, including carrier options, quotes, proposals, policies, and product discovery within Neuron's digital trading platform.

This API enables brokers to create opportunities, collaborate with carriers, track quote progress, select placements, and manage policy lifecycle activities efficiently.

Base URL

https://api.{env}neurondigitaltrading.com/broker/{region}/v2

Protocol: HTTPS only.

Authentication

All endpoints are secured via JWT validation (Authorization: Bearer <token>).

Every request must also include a correlation header for traceability (provided by the correlatable trait).

✅ What This API Enables

The Broker Experience API allows brokers to manage the end-to-end submission lifecycle, from opportunity creation through quote selection and policy management.

✅ Core Capabilities

Submission Management

Create, update, and submit insurance opportunities for carrier evaluation.

Carrier Assignment Management

Associate or replace carrier identifiers for a submission prior to processing.

Submission Status Management

Update submission status throughout the placement lifecycle.

Quote Retrieval & Decisioning

Retrieve quotes from carriers, compare responses, and manage the quote lifecycle.

Proposal Management

Create proposals by combining multiple quotes and present them for client selection.

Policy Management

Create, retrieve, renew, and manage policies based on accepted proposals.

Product Discovery

Retrieve available products and lines of business used for opportunity creation and validation.

Filter Value Retrieval

Retrieve pre-computed filter dropdown values (e.g. broker pipeline filters).

Insured / Client Lookup

Look up insured/client details via ECS to validate and enrich submissions and policies.

Operational Monitoring

Verify API availability using the health-check endpoint.

✅ Key Concepts

Submission

Represents an insurance opportunity initiated by a broker.

Option

Represents a carrier-specific opportunity within a submission.

Quote

Represents a carrier's response (quoted or declined) for a submission option.

Proposal

Represents a consolidated broker-facing view of quotes for client decisioning.

Policy

Represents a bound insurance contract following final selection.

Product

Represents available insurance products and lines of business used for submission creation and validation.

✅ Business Flow: Broker Journey

1. Create Submission Draft

🏢 Broker → 📥 POST /submissions/draft

Creates a draft opportunity submission. The system validates input against JSON schema, performs ECS insured lookup, and enriches with GCID.

Outcome:

• Draft submission created with submissionId

2. Manage Carrier Assignments

🏢 Broker → 🔗 PUT /submissions/{submissionId}/carriers

Assigns or replaces carrier identifiers for the submission.

Outcome:

• Carrier identifiers assigned or replaced

3. Manage Carrier Options

🏢 Broker → 📥 POST /submissions/{submissionId}/options

🏢 Broker → 🔄 PUT /submissions/{submissionId}/options/{optionId}

🏢 Broker → 🗑️ DELETE /submissions/{submissionId}/options/{optionId}

Defines, replaces, or removes carrier options on the submission.

Outcome:

• Carrier options created, updated, or removed

• Example optionId: "CORUUID|OPT001"

4. Submit Submission to Carriers

🏢 Broker → 🚀 POST /submissions/{submissionId}/submit

Sends the submission to carriers for processing.

Outcome:

• Submission dispatched to all selected carriers

5. Update Submission Status

🏢 Broker → 🔄 PATCH /submissions/{submissionId}/status

Updates the submission status throughout the placement lifecycle.

Outcome:

• Submission status updated

6. Retrieve Quotes

🏢 Broker → 📊 GET /quotes

Possible States:

• PENDING_SUBMISSION

• AWAITING_RESPONSE

• QUOTED_DECLINED

Query Parameters:

• submissionId — filter by submission

• view — summary or extended

• version — latest or all

Outcome:

• Broker receives quotes for each carrier option

7. Manage Quotes

🏢 Broker → 📥 /quotes/{quoteId}

• Update quote → PATCH /quotes/{quoteId}
• Issue documents to broker → POST /quotes/{quoteId}/documents/issue
• Publish documents to client → POST /quotes/{quoteId}/documents/publish

Outcome:

• Quotes updated

• Documents issued or published

8. Create Proposal

🏢 Broker → 📥 POST /proposals

Combines selected quotes into a proposal for client review.

Outcome:

• Proposal created with proposalId

• Client receives proposal for selection

9. Confirm Client Selection

🏢 Broker → ✅ POST /proposals/{proposalId}/confirm

Confirms the client's selected quote for the proposal.

Outcome:

• Selection confirmed

• Placement finalised

10. Policy Management

🏢 Broker → 📦 /policies

• Upload existing policy → POST /policies
• Retrieve all policies → GET /policies
• Retrieve policy by ID → GET /policies/{policyId}
• Update policy → PUT /policies/{policyId}
• Trigger renewal → POST /policies/{policyId}/renew

Outcome:

• Policies created, retrieved, updated, and renewed

11. Product Retrieval

🏢 Broker → 📥 GET /products

Retrieves available products and lines of business.

Features:

• Opportunity-specific product retrieval via view=opportunity

• Delegated underwriting type filtering via delegatedUnderwritingType

Outcome:

• Product catalogue available for downstream submission workflows

12. Health Check

🏢 Broker → 🔍 GET /health-check

Outcome:

• Confirms the service is running and reachable

✅ Endpoint Reference

Submissions — /submissions

Quotes — /quotes

Quote States: PENDING_SUBMISSION → AWAITING_RESPONSE → QUOTED_DECLINED

Proposals — /proposals

Policies — /policies

Policy Filter Parameters (GET /policies):

Products — /products

Filters — /filters

Client Details (Insured Lookup) — /configs/client-details

Health Check — /health-check

✅ Quote Handling Rules

Quote Status

• ✅ Quoted
• ❌ Declined

Quote Scope

• Single option per carrier
• Multiple options (multi-carrier response)

Quote Filtering

• Filter by submissionId
• Filter by version (latest / all)
• Filter by view (summary / extended)

✅ Outcome Scenarios

✅ Success

• Submission processed successfully
• Quotes retrieved
• Proposal created
• Policy issued

❌ Failure

• Validation errors (400 Bad Request)
• Missing or invalid JWT (401 Unauthorized)
• Insufficient permissions (403 Forbidden)
• Resource not found (404 Not Found)

⏳ In Progress

• Carrier processing
• Awaiting quote responses (AWAITING_RESPONSE)

✅ Error Handling

All endpoints return standard WTW REST error responses on failure (from wtw-rest-errors-library).

✅ Notes

• Quotes support filtering by submissionId, version, and view
• Submissions support pagination and filtering by opportunityType
• Policies support rich filtering: status, stage, carrier, product, broker owner
• productId in policy filters is comma-separated (supports multiple values)
• API is secured using JWT authentication with correlation header tracing
• ECS insured lookup is performed automatically on draft submission creation and policy creation
• /configs/client-details accepts a single name query parameter (min 3 chars, required)
• All endpoints use HTTPS only

✅ Version History

Breaking changes in v2.0.0: All risk management (/risks) and appetite management (/appetites) functionality was removed, including associated schemas and operations.