Search
K
MarketConnect-OrderEntry

Market Connect Order Entry API

1.0.3OAS 3.0

The Market Connect – Order Entry API enables external distribution platforms and partner systems to electronically initiate, manage, and submit life insurance and annuity applications through a unified digital workflow. Leveraging pre-populated data from existing quotes and suitability assessments, the API supports progressive save-and-resume capabilities, end-to-end order capture, automated validation, real-time application status tracking, robust error handling, and streamlined processing.

Version History

  • 1.0.3 (Latest)
    • Added optional ACORD-aligned prefill node to the create-transaction request, enabling pre-population of party and product fields.
    • Added optional illustrationId, accountNumber, and externalTransactionId fields to the create-transaction request.
  • 1.0.2
    • Added signer-status, signer-update, cancel-ceremony, and e-signature email-retrigger capabilities.
    • Added reviewer approval, decline, and termination actions, plus enhanced attachment metadata and upload/delete handling.
    • Added HTTP 422 business-validation responses, stricter request/control-type validation, optional opportunity IDs, and cache reliability fixes.
  • 1.0.1
    • Expanded the OpenAPI specification with environment URLs, OpenID Connect security, and Kong integration metadata.
    • Added attachment, comments, and product-pricing operations.
    • Added e-signature recipient and submission workflows and full-blueprint transaction updates.
  • 1.0.0
    • Added transaction submission and Life product blueprint processing.
    • Enabled the enhanced single-blueprint workflow without requiring a client-provided step name.
    • Expanded validation errors, conditional visibility, nested sections, custom controls, and bearer-token forwarding.
  • 0.9.0
    • Added authorization checks through FGA and refined the Market Connect Order Entry route structure.
    • Introduced create, retrieve, and progressive-save support for single-blueprint transactions.
    • Improved life and annuity transaction identification and service architecture.
  • 0.8.0
    • Introduced transaction creation and the initial server-driven order-entry workflow.
    • Added blueprint and question-data schemas for beneficiary, payment, visibility, and optional-condition use cases.
    • Standardized validation and enterprise error-response structures in the API specification.

Overview

The API provides a single workflow for creating and processing life insurance and annuity applications. Clients can start a transaction using quote and suitability data, retrieve the application blueprint along with any saved responses, capture and update applicant information, validate the application, submit it for processing, and track its status. The blueprint defines the application structure, including sections, fields, validation rules, conditional logic, and navigation, so clients can build the application experience without hardcoding these elements.

Headless Support

The API is designed to support headless integrations and is independent of any specific user interface. Distribution platforms can use the server-provided blueprint to build their own web, mobile, or advisor experiences without embedding a Zinnia-hosted UI. The client is responsible for how the application is presented to the user, while the API manages the transaction state, saved responses, business validations, submission, and status updates. For clients that prefer a prebuilt experience, Zinnia UI components are also available.

Authentication

All endpoints require a JWT bearer token in the Authorization header (Authorization: Bearer {token}). Tokens are issued by Auth0; contact your Zinnia onboarding representative for credentials.

Base URLs

  • Development: https://dev.api.zinnia.io
  • QA: https://qa.api.zinnia.io
  • UAT: https://uat.api.zinnia.io
  • Production: provided per integration agreement

Versioning

The API is versioned in the path (/market-connect/order-entry/v1/...). Breaking changes are released under a new major version segment; non-breaking additions ship within the existing version.

Error Handling

Error responses conform to the standard ErrorResponse schema and include a stable error code (ErrorInfo.code enum), a human-readable message, optional diagnostic details, and a timestamp. For endpoints that return HTTP 200 with partial success, application-level issues are reported in the errors array of the TransactionResponse. For transaction update requests that fail upstream business validation, the API returns HTTP 422 (Unprocessable Entity) with detailed validation errors in the validationErrors array.

Getting Started

  1. Acquire a JWT token from Auth0.
  2. POST /market-connect/order-entry/v1/transaction with state and cusip to create a transaction.
  3. GET /market-connect/order-entry/v1/transaction/{transactionId} to fetch the blueprint and data.
  4. PUT /market-connect/order-entry/v1/transaction/{transactionId} to save answers; the API determines the step from the blueprint state.
  5. POST /market-connect/order-entry/v1/transaction/{transactionId}/submit to submit the completed transaction.
  6. POST /market-connect/order-entry/v1/ReviewerAction with action and transactionId when a reviewer approves, declines, or terminates a case in the Zinnia UI.
API Base URL
  • Server 1:https://dev.api.zinnia.io
  • Server 2:https://qa.api.zinnia.io
  • Server 3:https://uat.api.zinnia.io
Security
openIdConnect (openIdConnect)

OpenID Connect via Auth0. Clients present a JWT bearer token issued by the tenant in the Authorization: Bearer <token> header.

Additional Information
Contact API Support (orderentrysupport@zinnia.com)
Proprietary License

Transaction

Transaction management operations

Create the Order Entry transaction. Routes to appropriate service based on CUSIP.

Error Responses

  • 400 Bad Request

  • VALIDATION_ERROR - Input validation failed (ModelState errors).

  • INVALID - Invalid input parameters.

  • 401 Unauthorized

  • UNAUTHORIZED - Authentication failed or token is invalid.

  • 403 Forbidden

  • FORBIDDEN - User does not have permission to create transactions.

  • 429 Too Many Requests

  • RATE_LIMIT_EXCEEDED - The client has exceeded the permitted request rate or quota.

  • 500 Internal Server Error

  • TRANSACTION_CREATION_FAILED - Transaction creation failed at service level.

  • TRANSACTION_ID_NOT_FOUND - Service did not return a transaction ID.

  • FIRST_STEP_SETUP_FAILED - First step initialization failed (breadcrumb, payload creation, or save).

  • JSON_PARSE_ERROR - Failed to parse service response.

  • BUILD_BLUEPRINT_ERROR - Error building blueprint after creation.

  • UNEXPECTED_ERROR - Unexpected system error.

  • 502 Bad Gateway

  • UPSTREAM_SERVICE_ERROR - An upstream dependency returned an invalid or unsuccessful response.

  • 503 Service Unavailable

  • SERVICE_UNAVAILABLE - The service or a required dependency is temporarily unavailable.

  • 504 Gateway Timeout

  • UPSTREAM_TIMEOUT - A required downstream service did not respond within the configured timeout.

Standard Error Response

All error responses conform to the standard ErrorResponse schema and include:

  • A stable error code from ErrorInfo.code.
  • A human-readable error message.
  • Optional diagnostic details, when applicable.
  • A timestamp indicating when the error occurred.
    This consistent format enables clients to implement standardized error processing, logging, and troubleshooting across all Order Entry API endpoints.

Success Response

On success, returns a TransactionResponse with:

  • TransactionId: The newly created transaction ID
  • CaseId: The case identifier returned by the upstream product service (may be null until the case is fully created)
  • Data: Initial transaction field data keyed by question ID
  • Blueprint: Complete section and field definitions for the new transaction
  • Subscribers: Reactive subscriber definitions consumed by the UI to drive dependent dataset lookups
  • Errors: Empty array on success (or absent)

Input Validation

The following fields are validated:

  • State: Required two-letter uppercase code from the documented US state, territory, and military mail code enum
  • CUSIP: Required configured product identifier containing exactly nine uppercase alphanumeric characters; pattern ^[0-9A-Z]{9}$
  • OpportunityId: Optional UUID used to associate the transaction with a sales opportunity

Service Routing

The API automatically routes to the appropriate service based on CUSIP:

  • Annuity Service: Configured Annuity CUSIPs
  • Life Service: Configured Life CUSIPs

Transaction Creation Flow

The transaction creation process includes:

  • Validate input parameters
  • Determine service routing based on CUSIP
  • Create transaction via appropriate service (Life or Annuity)
  • Get breadcrumb to determine first step
  • Retrieve order entry values for first step
  • Create and save first step payload
  • Build complete blueprint for the transaction

First Step Setup Failures

The FIRST_STEP_SETUP_FAILED error can occur when:

  • No breadcrumb steps are found
  • First step name is null or empty
  • Order entry values are null or empty
  • First step payload creation fails
  • First step data save operation fails
  • First step save response indicates failure
post

Body

application/json

The input data for creating a new transaction

* Additional properties are NOT allowed.
statestringrequired

US state, territory, or military mail code (2 characters). Uppercase letters only.

Allowed values:ALAKAZARAAAEAPCACOCTDEDCFLGAGUHIIDILINIAKSKYLAMEMDMAMIMNMSMOMTNENVNHNJNMNYNCNDOHOKORPAPRRISCSDTNTXUTVTVIVAWAWVWIWY

Match pattern:^[A-Z]{2}$

Example:NC

cusipstringrequired

Configured product CUSIP (9 characters). Uppercase letters and digits only.

Match pattern:^[0-9A-Z]{9}$

Example:90353U115

opportunityIdstring | null(uuid)

Optional opportunity identifier in UUID format.

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

illustrationIdstring | null

Optional illustration identifier to associate the new transaction with a prior illustration.

Example:ILL-2024-00001

accountNumberstring | null

Optional account number to associate with the new transaction.

Example:BR-9876543210

externalTransactionIdstring | null

Optional external transaction identifier from the originating system.

Example:TXN-2024-00001

prefillobject

Optional ACORD-aligned prefill data to pre-populate party and product fields in the new transaction.

* Additional properties are NOT allowed.
Show Child Parameters

Response

application/json

Returns the Order Entry blueprint for the created transaction

TransactionResponse

* Additional properties are NOT allowed.
transactionIdstringrequired

The unique identifier for the created transaction

>= 1 characters

caseIdstring | null

The case identifier returned by the product service

dataobjectrequired

Answers keyed by blueprint question id or composite collection field id. Named properties below are representative examples (same keys as the default example); any other field id is valid and uses the same value shape (see additionalProperties → QuestionDataRows → QuestionData). Each array entry is one row; use index for repeatable collection instances.

Example:{"259726":[{"id":"259726","type":"dropdown","questionText":"Account designation","questionSubText":"Account designation","displayValue":"Owner","value":"Owner","index":0}]}

Show Child Parameters
blueprintobjectrequired
* Additional properties are NOT allowed.
Show Child Parameters
subscribersarray | null[object]

Reactive subscriber definitions consumed by the UI. Each subscriber declares trigger fields, an HTTP action to run on change, and a response handler. Two flavors are emitted: dataset-dependency (context-modification) and blueprint-modification (replace-whole).

Example:{"triggers":["FirstName"],"actions":[{"type":"http","verb":"get","url":"/market-connect/order-entry/v1/transaction/1125715/MCDPS","token":"OEToken","payload":{"type":"none"},"responseHandlers":[{"type":"blueprint-modification","action":"replace-whole","value":{"type":"response-query","kind":"json-path","value":"$.data"}}]}]}

* Additional properties are NOT allowed.
Show Child Parameters
errorsarray | null[object]

Collection of errors if the operation failed

Example:{"code":"VALIDATION_ERROR","description":"Validation failed for field '$.fieldName'","details":"The request contains an unrecognized property. Only documented fields are allowed.","timestamp":"2024-01-15T10:30:00.000Z"}

* Additional properties are NOT allowed.
Show Child Parameters
validationErrorsarray | null[object]

One validation message in API shape. Optional properties are omitted in JSON when null (e.g. fieldId is missing or 0).

Example:{"fieldId":"BeneficiaryAddress","answerNodeId":"Transaction.PrimaryOwner.PersonName.Prefix","message":"First name is required","sectionName":"EntityOwners"}

* Additional properties are NOT allowed.
Show Child Parameters
post/market-connect/order-entry/v1/transaction

Body

{ "state": "NC", "cusip": "90353U115" }
 
application/json