MarketConnect-OrderEntry

Market Connect Order Entry API

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

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

Error Responses

  • 400 Bad Request

  • VALIDATION_ERROR - The request failed input validation.

  • INVALID_TRANSACTION_ID - The supplied transaction ID is invalid (less than or equal to zero).

  • 401 Unauthorized

  • UNAUTHORIZED - Authentication failed or the access token is missing, expired, or invalid.

  • 403 Forbidden

  • FORBIDDEN - The authenticated user is not authorized to access the requested transaction.

  • 404 Not Found

  • TRANSACTION_ID_NOT_FOUND - No transaction exists for the specified transaction ID.

  • NOT_FOUND - The requested transaction or blueprint step could not be found.

  • 429 Too Many Requests

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

  • 500 Internal Server Error

  • BUILD_BLUEPRINT_ERROR - An error occurred while generating the order entry blueprint.

  • JSON_PARSE_ERROR - The system encountered an error while parsing the transaction response.

  • UNEXPECTED_ERROR - An unexpected internal system error occurred while processing the request.

  • 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, the API returns a TransactionResponse containing:

  • transactionId - The unique identifier for the transaction.
  • caseId - The identifier for the case created by the upstream product service. This value may be null until the case has been created successfully.
  • data - The current transaction data, with field values keyed by their corresponding question identifiers.
  • blueprint - The complete transaction blueprint, including the sections, fields, validations, conditional behavior, and metadata required to render the application.
  • subscribers - Reactive subscriber definitions used by the client to drive dynamic field behavior, dependent lookups, and dataset updates.
  • errors - Empty or omitted when the request completes successfully. For partial success or recoverable business warnings, this array contains the applicable application-level messages.
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

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
get/market-connect/order-entry/v1/transaction/{transactionId}
 
application/json

Update the Order Entry transaction data for enhanced blueprint (single-blueprint) transactions.

Used for enhanced blueprint (single-blueprint) transactions where no step name is required. The step is automatically resolved from the product type.

Error Responses

  • 400 Bad Request

  • VALIDATION_ERROR - Input validation failed (ModelState errors, or field-level data validation failures such as invalid state/dropdown values or non-string name/address values for AnnuityNet).

  • INVALID_TRANSACTION_ID - Invalid transaction ID provided.

  • Note: for VALIDATION_ERROR responses, transactionId in the response body is populated with the path transaction ID when it was successfully parsed; if the transaction ID itself could not be parsed (INVALID_TRANSACTION_ID), transactionId is returned as an empty string since there is no valid ID to echo back.

  • 401 Unauthorized

  • UNAUTHORIZED - Authentication failed or token is invalid.

  • 403 Forbidden

  • FORBIDDEN - User does not have permission to update this transaction.

  • 404 Not Found

  • TRANSACTION_ID_NOT_FOUND - No transaction exists for the specified transaction ID.

  • NOT_FOUND - The requested transaction could not be found.

  • 422 Unprocessable Entity

  • Upstream business validation failed after save — response includes validationErrors and a validation-messages blueprint section.

  • 429 Too Many Requests

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

  • 500 Internal Server Error

  • SAVE_TRANSACTION_ERROR - Save operation failed at service level.

  • SAVE_TRANSACTION_FAILED - Save operation not successful.

  • INVALID_RESPONSE_FORMAT - Invalid response format from service.

  • EMPTY_BLUEPRINT - Empty blueprint returned after save.

  • BUILD_BLUEPRINT_ERROR - Error building blueprint for next step.

  • 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.
put

Path Parameters

transactionIdstringrequired

The unique identifier for the transaction

Body

application/json

The input data for updating the transaction (data object matching GET/Create response shape)

TransactionDataQuestionRowsMap

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.

259726array[object]

One row of captured or echoed answer data. Must include id, type, and value (the JSON property value must be present on each row; use JSON null for an empty optional answer when applicable). On PUT, id must match the enclosing data field key (or the leaf key inside a collection item’s data). type must be a QuestionData storage type (see QuestionDataStorageTypes); collection value rows use collectionItem on each CollectionItem.

* Additional properties are NOT allowed.
Show Child Parameters

Response

application/json

Returns the updated Order Entry blueprint or success status

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
put/market-connect/order-entry/v1/transaction/{transactionId}

Body

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

Submit an order entry transaction for processing.

Error Responses

  • 400 Bad Request

  • VALIDATION_ERROR - Request body is not allowed (endpoint does not accept a body, including empty {}).

  • INVALID_TRANSACTION_ID - The supplied transaction ID is invalid.

  • VALIDATION_ERROR - The upstream order entry service rejected the submission due to validation failures.

  • 401 Unauthorized

  • UNAUTHORIZED - Authentication failed or the access token is missing, expired, or invalid.

  • 403 Forbidden

  • FORBIDDEN - The authenticated user is not authorized to submit this transaction.

  • 404 Not Found

  • TRANSACTION_ID_NOT_FOUND - No transaction exists for the specified transaction ID.

  • 409 Conflict

  • DUPLICATE_SUBMISSION - The transaction has already been submitted to the upstream order-entry service. The response includes confirmationNumber when the upstream service supplied one.

  • 429 Too Many Requests

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

  • 500 Internal Server Error

  • UNEXPECTED_ERROR - An unexpected internal system error occurred while submitting the transaction.

  • 502 Bad Gateway

  • UPSTREAM_SERVICE_ERROR - The upstream product service returned an error while processing the submit request.

  • 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.
post

Path Parameters

transactionIdstringrequired

The unique identifier for the transaction

Response

application/json

Transaction submitted successfully. Includes confirmationNumber from the upstream order-entry service when supplied.

SubmitTransactionResponse

* Additional properties are NOT allowed.
transactionIdstringrequired

The unique identifier for the submitted transaction. Echoed back from the request.

>= 1 characters

confirmationNumberstring | null

The confirmation number returned by the upstream order-entry service for this submission. Omitted when not supplied.

messagestringrequired

Human-readable confirmation that the submit request was accepted.

>= 1 characters

post/market-connect/order-entry/v1/transaction/{transactionId}/submit
 
application/json