Search
K
MarketConnect-OrderEntry

Market Connect Order Entry API

1.0OAS 3.0

Zinnia Market Connect Order Entry API - server-driven order entry for life and annuity products.

Overview

The API exposes the order entry blueprint (sections, subsections, fields, validation, visibility) and the data captured against it. Clients render the blueprint with the Zinnia Form Engine SDK and submit answers back through the Transaction endpoints.

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

Errors follow the ErrorResponse schema with a stable code (see ErrorInfo.code enum), a human-readable description, optional details, and a timestamp. Application-level failures are also surfaced in the errors array of TransactionResponse for endpoints that return 200 with partial success.

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}/{stepName} to save answers and advance.
  5. POST /market-connect/order-entry/v1/transaction/{transactionId}/submit to submit the completed transaction.
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
bearerAuth (http)

JWT bearer token issued by Auth0. Send as: ‘Authorization: Bearer {token}’.

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

Transaction

Transaction management operations

Retrieves the order entry blueprint and its associated responses for a created life or annuity transaction

This endpoint reopens an existing transaction and returns the order entry blueprint along with any previously saved responses, allowing the user to resume where they left off

Error Scenarios

  • 400 Bad Request:

  • VALIDATION_ERROR - Input validation failed

  • INVALID_TRANSACTION_ID - Transaction ID is less than or equal to 0

  • 401 Unauthorized:

  • UNAUTHORIZED - Authentication failed or token is invalid

  • 403 Forbidden:

  • FORBIDDEN - User does not have permission to access this resource

  • 404 Not Found:

  • TRANSACTION_ID_NOT_FOUND - Transaction not found in the system

  • NOT_FOUND - Transaction or step not found

  • 500 Internal Server Error:

  • BUILD_BLUEPRINT_ERROR - Error building the blueprint

  • JSON_PARSE_ERROR - Error parsing JSON response

  • UNEXPECTED_ERROR - Unexpected system error

Success Response

On success, returns a TransactionResponse with:

  • TransactionId: The transaction ID
  • Data: Transaction field data
  • Blueprint: Complete section and field definitions
  • Error: null (no error)
get

Path Parameters

transactionIdstringrequired

Unique identifier assigned when an order entry transaction is created

Response

application/json

Returns a product’s order entry blueprint with associated answer data

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

Dictionary of question data keyed by question ID

blueprintobjectrequired

The blueprint containing section and field definitions

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

Subscribers defining dataset dependency actions

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

Collection of errors if the operation failed

Example:{"code":"VALIDATION_ERROR","description":"Input validation failed","details":"One or more input fields are invalid","timestamp":"2024-01-15T10:30:00.000Z"}

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

Collection of validation errors when transaction validation fails. Includes transaction ID, field ID, and error messages.

Example:{"answerNodeId":"Transaction.PrimaryOwner.FirstName","message":"First name is required","sectionName":"PersonalInformation"}

* Additional properties are NOT allowed.
Show Child Parameters
get/market-connect/order-entry/v1/transaction/{transactionId}
 
application/json

Update transaction data (enhanced blueprint)

Updates transaction data for enhanced blueprint transactions without providing a step name. When validation fails, returns 200 with a blueprint containing a validation-messages section and a validationErrors array listing field-level validation errors.

put

Path Parameters

transactionIdstringrequired

Body

application/json
object

Transaction update request - a dictionary keyed by question ID whose values are QuestionData objects.

Response

application/json

OK

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

Dictionary of question data keyed by question ID

blueprintobjectrequired

The blueprint containing section and field definitions

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

Subscribers defining dataset dependency actions

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

Collection of errors if the operation failed

Example:{"code":"VALIDATION_ERROR","description":"Input validation failed","details":"One or more input fields are invalid","timestamp":"2024-01-15T10:30:00.000Z"}

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

Collection of validation errors when transaction validation fails. Includes transaction ID, field ID, and error messages.

Example:{"answerNodeId":"Transaction.PrimaryOwner.FirstName","message":"First name is required","sectionName":"PersonalInformation"}

* Additional properties are NOT allowed.
Show Child Parameters
put/market-connect/order-entry/v1/transaction/{transactionId}

Body

{ "259726": { "id": "259726", "type": "dropdown", "questionText": "Account designation", "questionSubText": "Account designation", "displayValue": "Owner", "value": "Owner" }, "486958": { "id": "486958", "type": "date", "questionText": "Date of birth", "questionSubText": "", "displayValue": "1989-10-13", "value": "1989-10-13" }, "488043": { "id": "488043", "type": "radio", "questionText": "Gender", "questionSubText": "", "displayValue": "Male", "value": "Male" }, "489353": { "id": "489353", "type": "collection", "questionText": "Name", "questionSubText": "", "displayValue": "", "value": [ { "surrogateId": "489353_1", "type": "collectionItem", "data": { "489353_FirstName_Main": { "id": "489353_FirstName_Main", "type": "input", "questionText": "First Name", "questionSubText": "", "displayValue": "John", "value": "John" }, "489353_LastName_Main": { "id": "489353_LastName_Main", "type": "input", "questionText": "Last Name", "questionSubText": "", "displayValue": "Doe", "value": "Doe" } } } ] } }
 
application/json

Retrieves the order entry blueprint and its associated responses for a created life or annuity transaction on a specific step.

In a multi-blueprint setup, this endpoint allows navigation to a specific section within the blueprint structure and returns the blueprint for the selected section for rendering

Error Scenarios

  • 400 Bad Request:

  • VALIDATION_ERROR - Input validation failed

  • INVALID_TRANSACTION_ID - Transaction ID is less than or equal to 0

  • INVALID_STEP_NAME - Step name is null or whitespace

  • 401 Unauthorized:

  • UNAUTHORIZED - Authentication failed or token is invalid

  • 403 Forbidden:

  • FORBIDDEN - User does not have permission to access this resource

  • 404 Not Found:

  • TRANSACTION_ID_NOT_FOUND - Transaction not found in the system

  • NOT_FOUND - Transaction or step not found

  • 500 Internal Server Error:

  • BUILD_BLUEPRINT_ERROR - Error building the blueprint

  • JSON_PARSE_ERROR - Error parsing JSON response

  • UNEXPECTED_ERROR - Unexpected system error

Success Response

On success, returns a TransactionResponse with:

  • TransactionId: The transaction ID
  • Data: Transaction field data
  • Blueprint: Complete section and field definitions
  • Error: null (no error)
get

Path Parameters

transactionIdstringrequired

Unique identifier assigned when an order entry transaction is created

stepNamestringrequired

PascalCase step identifier matching the section ID in the blueprint (e.g. CarrierProductSelection, EntityOwners). Values are returned verbatim from the backend blueprint - do not lowercase or transform them.

Response

application/json

Returns a product’s order entry blueprint with associated answer data

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

Dictionary of question data keyed by question ID

blueprintobjectrequired

The blueprint containing section and field definitions

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

Subscribers defining dataset dependency actions

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

Collection of errors if the operation failed

Example:{"code":"VALIDATION_ERROR","description":"Input validation failed","details":"One or more input fields are invalid","timestamp":"2024-01-15T10:30:00.000Z"}

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

Collection of validation errors when transaction validation fails. Includes transaction ID, field ID, and error messages.

Example:{"answerNodeId":"Transaction.PrimaryOwner.FirstName","message":"First name is required","sectionName":"PersonalInformation"}

* Additional properties are NOT allowed.
Show Child Parameters
get/market-connect/order-entry/v1/transaction/{transactionId}/{stepName}
 
application/json