--- title: "Retrieves the order entry blueprint and its associated responses for a created life or annuity transaction" url: "https://developers.zinnia.com/apis/market-connect-order-entry/versions/50f981c3-db50-4358-884f-31eb427255ec/operations/getTransaction" --- > Full API specification: https://developers.zinnia.com/apis/market-connect-order-entry/versions/50f981c3-db50-4358-884f-31eb427255ec.md # Retrieves the order entry blueprint and its associated responses for a created life or annuity transaction `GET` `/market-connect/order-entry/v1/transaction/{transactionId}` Operation ID: `getTransaction` #### 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. ## Path parameters - `transactionId` (string, required) - Unique identifier assigned when an order entry transaction is created ## Responses - `200` - Returns a product's order entry blueprint with associated answer data - `400` - `VALIDATION_ERROR` - The request failed input validation. `INVALID_TRANSACTION_ID` - The supplied transaction ID is invalid (less than or equal to zero). - `401` - `UNAUTHORIZED` - Authentication failed or the access token is missing, expired, or invalid. - `403` - `FORBIDDEN` - The authenticated user is not authorized to access the requested transaction. - `404` - `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` - `RATE_LIMIT_EXCEEDED` - The client has exceeded the permitted request rate or quota. - `500` - `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` - `UPSTREAM_SERVICE_ERROR` - An upstream dependency returned an invalid or unsuccessful response. - `503` - `SERVICE_UNAVAILABLE` - The service or a required dependency is temporarily unavailable. - `504` - `UPSTREAM_TIMEOUT` - A required downstream service did not respond within the configured timeout. ## OpenAPI definition ````yaml openapi: 3.0.1 info: title: Market Connect Order Entry API version: 1.0.3 servers: - url: https://dev.api.zinnia.io - url: https://qa.api.zinnia.io - url: https://uat.api.zinnia.io paths: /market-connect/order-entry/v1/transaction/{transactionId}: get: tags: - Transaction summary: Retrieves the order entry blueprint and its associated responses for a created life or annuity transaction description: >- #### 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. operationId: getTransaction parameters: - name: transactionId in: path description: Unique identifier assigned when an order entry transaction is created required: true schema: type: string responses: "200": description: Returns a product's order entry blueprint with associated answer data content: application/json: schema: $ref: "#/components/schemas/TransactionResponse" "400": description: >- `VALIDATION_ERROR` - The request failed input validation. `INVALID_TRANSACTION_ID` - The supplied transaction ID is invalid (less than or equal to zero). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: VALIDATION_ERROR description: Validation failed for field '$.unknownField' details: The request contains an unrecognized property. Only documented fields are allowed. timestamp: 2025-01-16T13:21:19.4355657Z "401": description: "`UNAUTHORIZED` - Authentication failed or the access token is missing, expired, or invalid." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UNAUTHORIZED description: Unauthorized access details: The request requires authentication timestamp: 2025-01-16T13:21:19.4355657Z "403": description: "`FORBIDDEN` - The authenticated user is not authorized to access the requested transaction." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: FORBIDDEN description: Access denied details: You do not have permission to access this resource timestamp: 2025-01-16T13:21:19.4355657Z "404": description: >- `TRANSACTION_ID_NOT_FOUND` - No transaction exists for the specified transaction ID. `NOT_FOUND` - The requested transaction or blueprint step could not be found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: NOT_FOUND description: Resource not found details: The requested resource could not be found timestamp: 2025-01-16T13:21:19.4355657Z "429": description: "`RATE_LIMIT_EXCEEDED` - The client has exceeded the permitted request rate or quota." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: RATE_LIMIT_EXCEEDED description: Request rate limit exceeded details: The client has exceeded the permitted request rate or quota. timestamp: 2025-01-16T13:21:19.4355657Z "500": description: >- `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. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UNEXPECTED_ERROR description: An unexpected error occurred details: An internal error occurred. Please contact support if the problem persists. timestamp: 2025-01-16T13:21:19.4355657Z "502": description: "`UPSTREAM_SERVICE_ERROR` - An upstream dependency returned an invalid or unsuccessful response." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UPSTREAM_SERVICE_ERROR description: Upstream service error details: An upstream dependency returned an invalid or unsuccessful response. timestamp: 2025-01-16T13:21:19.4355657Z "503": description: "`SERVICE_UNAVAILABLE` - The service or a required dependency is temporarily unavailable." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: SERVICE_UNAVAILABLE description: Service unavailable details: The service or a required dependency is temporarily unavailable. timestamp: 2025-01-16T13:21:19.4355657Z "504": description: "`UPSTREAM_TIMEOUT` - A required downstream service did not respond within the configured timeout." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UPSTREAM_TIMEOUT description: Upstream timeout details: A required downstream service did not respond within the configured timeout. timestamp: 2025-01-16T13:21:19.4355657Z security: - openIdConnect: [] components: schemas: TransactionResponse: required: - blueprint - data - transactionId type: object properties: transactionId: minLength: 1 type: string description: The unique identifier for the created transaction caseId: type: string description: The case identifier returned by the product service nullable: true data: $ref: "#/components/schemas/TransactionDataQuestionRowsMap" blueprint: $ref: "#/components/schemas/Blueprint" subscribers: type: array items: $ref: "#/components/schemas/Subscriber" description: "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)." nullable: true errors: type: array items: $ref: "#/components/schemas/ErrorInfo" description: Collection of errors if the operation failed nullable: true validationErrors: type: array items: $ref: "#/components/schemas/ValidationErrors" description: Collection of validation errors when transaction validation fails. Includes transaction ID, field ID, and error messages. nullable: true additionalProperties: false example: transactionId: "12345" caseId: CASE-12345 data: "259726": - type: dropdown displayValue: Owner id: "259726" value: Owner index: 0 489444_Line1: - type: input displayValue: 12108 Jefferson CT id: 489444_Line1 value: 12108 Jefferson CT index: 0 489444_City: - type: input displayValue: Alpharetta id: 489444_City value: Alpharetta index: 0 blueprint: sectionBlueprints: - id: section1 partName: PersonalInformation title: en: Personal Information modules: - personal isCustom: false subsections: - id: 489363-SubSection partName: partName-489363 text: en: "" title: en: "" isCustom: true fieldGroups: - id: "489363" partName: partName-489363 text: en: "" title: en: Name isCustom: true fields: - fieldType: dropdown text: en: "" title: en: Prefix answerNodeId: Transaction.PrimaryOwner.PersonName.Prefix renderOn: [] platforms: [] copyable: none triggerStepNavigation: false layout: size: 12 displayInCardPreview: false applicationModes: - digital - paper placeholder: en: "" id: 489363_Prefix partName: partName-489363_Prefix validateAs: string selectOptions: - text: en: Mr value: "1" - text: en: Mrs value: "2" - text: en: Ms value: "3" - text: en: Dr value: "4" - text: en: Atty value: "5" - text: en: Rev value: "6" - text: en: Miss value: "7" visible: null optional: false repeatable: repeatableAnswerNodeId: "489363" minRepeatable: 1 maxRepeatable: 15 addButtonText: en: Add removeButtonText: en: Remove repeatable: repeatableAnswerNodeId: 489363-SubSection minRepeatable: 1 maxRepeatable: 15 addButtonText: en: Add removeButtonText: en: Remove copyable: "" renderOn: [] pdfDocuments: [] platforms: [] sectionGroupBlueprints: insuredPeople: id: insuredPeople title: en: "" partName: "" subscribers: - triggers: - Transaction.SolicitationState actions: - type: http verb: post url: /market-connect/order-entry/v1/dataset token: OEToken payload: type: basic payload: transactionId: "1064187" stepName: CarrierProductSelection fieldId: "504436" Transaction.Parameters["CarrierID"].Value: blueprint-id:504435 Transaction.SolicitationState: blueprint-id:504440 responseHandlers: - type: context-modification action: update-namespace namespace: "504436" value: type: response-query kind: json-path value: $.data errors: [] ErrorResponse: required: - errors - transactionId type: object properties: transactionId: minLength: 1 type: string errors: type: array items: $ref: "#/components/schemas/ErrorInfo" additionalProperties: false example: transactionId: "12345" errors: - code: UNAUTHORIZED description: Unauthorized access details: The request requires authentication timestamp: 2025-01-16T13:21:19.4355657Z TransactionDataQuestionRowsMap: title: TransactionDataQuestionRowsMap type: object properties: "259726": $ref: "#/components/schemas/QuestionDataRows" additionalProperties: $ref: "#/components/schemas/QuestionDataRows" description: 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 Blueprint: required: - sectionBlueprints - sectionGroupBlueprints type: object properties: sectionBlueprints: type: array items: $ref: "#/components/schemas/SectionBlueprint" description: An array of sections representing the hierarchical structure of an order entry blueprint, nested from sections to subsections, field groups, and individual fields sectionGroupBlueprints: type: object additionalProperties: $ref: "#/components/schemas/SectionGroupBlueprint" description: Map of section groups keyed by group identifier. Each value assigns sections to their corresponding group. additionalProperties: false Subscriber: type: object properties: triggers: type: array items: type: string description: NamedItem identifiers of the form fields whose value change fires this subscriber. nullable: true conditions: type: array items: {} description: Optional conditions that must hold for the subscriber to execute. Omitted when not used. nullable: true actions: type: array items: $ref: "#/components/schemas/SubscriberAction" description: Actions executed when any of the triggers fire. Each action declares an HTTP call plus one or more response handlers. nullable: true additionalProperties: false 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 ErrorInfo: required: - code - timestamp type: object properties: code: enum: - VALIDATION_ERROR - INVALID_TRANSACTION_ID - INVALID_STEP_NAME - TRANSACTION_CREATION_FAILED - TRANSACTION_ID_NOT_FOUND - SAVE_TRANSACTION_ERROR - SAVE_TRANSACTION_FAILED - INVALID_RESPONSE_FORMAT - BUILD_BLUEPRINT_ERROR - JSON_PARSE_ERROR - TRANSFORMER_NULL_RESPONSE - EMPTY_BLUEPRINT - UNEXPECTED_ERROR - SERVICE_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - RATE_LIMIT_EXCEEDED - UPSTREAM_SERVICE_ERROR - SERVICE_UNAVAILABLE - UPSTREAM_TIMEOUT - FIRST_STEP_SETUP_FAILED - METHOD_NOT_ALLOWED type: string description: Backend error codes returned by the Order Entry API indicating validation failures, transaction issues, blueprint generation errors, authorization errors, or unexpected system failures. description: type: string nullable: true details: type: string nullable: true timestamp: type: string format: date-time additionalProperties: false 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 ValidationErrors: type: object properties: fieldId: type: string description: ControlID as a string (numeric ids appear quoted). Omitted when fieldId is 0. nullable: true answerNodeId: type: string description: Answer node path from annuity NamedItem; matches FieldBlueprint.AnswerNodeId. nullable: true message: type: string description: The validation error message nullable: true sectionName: type: string description: The section/step name where the error occurred nullable: true additionalProperties: false description: 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 QuestionDataRows: title: QuestionDataRows type: array items: $ref: "#/components/schemas/QuestionData" description: All answer rows for one question or composite collection field id. Use `index` on each row for repeatable collection instances. Each row must include `id`, `type`, and `value` (see QuestionData schema). SectionBlueprint: required: - id - partName - title type: object properties: id: minLength: 1 type: string description: The unique identifier for the section sectionGroupKey: type: string description: A key used to group related sections within the blueprint nullable: true partName: minLength: 1 type: string description: An identifier (partName) for the section title: allOf: - $ref: "#/components/schemas/LocalizedText" description: The section title in multiple languages. Supports localization through language codes (e.g., en, fr) modules: type: array items: type: string description: An array of module names associated with this section nullable: true isCustom: type: boolean description: Indicates whether this section is custom subsections: type: array items: $ref: "#/components/schemas/SubsectionBlueprint" description: Array of subsections within this section nullable: true copyable: type: string description: Role identifier controlling copy behavior. Use 'none' to disable copying, or a role name (e.g., 'owner', 'annuitant', 'insured', 'payor'). Multiple roles may be comma-separated. nullable: true renderOn: type: array items: type: string description: An array of conditions that determine when a section is rendered nullable: true pdfDocuments: type: array items: type: string description: An array of PDF document identifiers where this section appears nullable: true platforms: type: array items: type: string description: An array of platforms where this section is available (e.g., D2C-only versus advisor-driven experiences) nullable: true visible: allOf: - $ref: "#/components/schemas/VisibilitySettings" description: 'Visibility conditions for the section. When present, the section is only visible when all conditions are met. Example: { "booleanOperator": "AND", "conditions": [ { "type": "equality", "isEqual": true, "value": "NY", "targetNodeId": "SolicitationStateCode" } ] }' example: booleanOperator: AND conditions: - type: equality isEqual: true value: Yes targetNodeId: Transaction.SolicitationState repeatable: allOf: - $ref: "#/components/schemas/RepeatableBlueprint" description: Repeat-instance metadata when the wizard section declares IsRepeated. additionalProperties: false SectionGroupBlueprint: required: - id - title type: object properties: id: minLength: 1 type: string description: The unique identifier for the section group title: allOf: - $ref: "#/components/schemas/LocalizedText" description: The section group title in multiple languages. Supports localization through language codes (e.g., en, fr) partName: type: string description: An identifier (partName) for the section group nullable: true additionalProperties: false SubscriberAction: type: object properties: type: type: string description: The action transport. Currently always "http". nullable: true verb: type: string description: HTTP verb to use (e.g., "get", "post"). nullable: true url: type: string description: "Relative URL of the OE endpoint to call when the trigger fires. Three shapes are emitted: '/market-connect/order-entry/v1/dataset' (dataset refresh); '/market-connect/order-entry/v1/transaction/{transactionId}/{stepNa\ me}' (multi-step blueprint refresh); '/market-connect/order-entry/v1/transaction/{transactionId}' (single/enhanced blueprint refresh)." nullable: true token: type: string description: Bearer-token alias forwarded by the UI on the call. Always "OEToken" today. nullable: true payload: allOf: - $ref: "#/components/schemas/SubscriberActionPayload" description: Request payload envelope. Use type "none" when no body is required. example: type: basic payload: transactionId: "1125715" stepName: MCDPS fieldId: "531783" responseHandlers: type: array items: $ref: "#/components/schemas/SubscriberResponseHandler" description: One or more handlers that apply the upstream response back to the form. nullable: true additionalProperties: false example: type: http verb: get url: /market-connect/order-entry/v1/transaction/1064727 token: OEToken payload: type: none responseHandlers: - type: blueprint-modification action: replace-whole value: type: response-query kind: json-path value: $.data QuestionData: required: - id - type - value type: object properties: id: minLength: 1 type: string description: Must match the field key under `data` for this row (case-insensitive); inside collection rows, must match the leaf key in the item's `data` map. type: minLength: 1 enum: - input - dropdown - radio - checkbox - checkboxgroup - date - phone - email - money - number - label - information - collection - Person - Address - Hidden type: string description: "Data-storage type for the question row. Must match the corresponding blueprint field type and be one of: input, dropdown, radio, checkbox, checkboxgroup, date, phone, email, money, number, label, information, collection, Person, Address, Hidden. Values are case-sensitive." example: input questionText: type: string description: The title of the question shown to the user. This value should be kept in sync with the title property of the associated field nullable: true questionSubText: type: string description: The subtext shown to the user below the question title. This value should be kept in sync with the text property of the associated field nullable: true displayValue: type: string description: The display text representing the user's selected answer. For example, a country dropdown may display 'United States of America' to the user, while the blueprint stores the value as 'USA' nullable: true value: anyOf: - type: string description: String value for simple fields example: PrimaryBeneficiary - type: integer description: Integer value for numeric fields example: 123 - type: number description: Float value for decimal fields format: float example: 123.45 - type: string description: Date value for date fields (YYYY-MM-DD format) format: date example: 2024-01-15 - type: string description: DateTime value for date-time fields (ISO 8601 format) format: date-time example: 2024-01-15T10:30:00Z - type: boolean description: Boolean value for true/false fields example: true - type: array items: type: string example: Income_Replacement description: Array of selected option codes for checkboxgroup fields - type: array items: required: - surrogateId - type - data type: object properties: surrogateId: type: string description: "The surrogate identifier for each set of answers in a collection. Example: a repeatable beneficiary collection with two beneficiaries will have two surrogate IDs." example: 504490-1 type: enum: - collectionItem type: string description: Must be `collectionItem` for each element of a collection value array. example: collectionItem data: type: object additionalProperties: required: - id - type - value type: object properties: id: type: string description: Must match the leaf property name under this collection item's `data` object (case-insensitive). example: 504490_FirstName type: enum: - input - dropdown - radio - checkbox - checkboxgroup - date - phone - email - money - number - label - information - collection - Person - Address - Hidden type: string description: "Data-storage type for the question row. Must match the corresponding blueprint field type and be one of: input, dropdown, radio, checkbox, checkboxgroup, date, phone, email, money, number, label, information, collection, Person, Address, Hidden. Values are case-sensitive." example: input questionText: type: string description: The title of the question shown to the user. This value should be kept in sync with the title property of the associated field example: First Name questionSubText: type: string description: The subtext shown to the user below the question title. This value should be kept in sync with the text property of the associated field example: "" displayValue: type: string description: The display text representing the user's selected answer. For example, a country dropdown may display 'United States of America' to the user, while the blueprint stores the value as 'USA' example: "" value: anyOf: - type: string description: String value for simple fields example: "" - type: integer description: Integer value for numeric fields example: 123 - type: number description: Float value for decimal fields example: 123.45 - type: string description: Date value for date fields (YYYY-MM-DD format) format: date example: 2024-01-15 - type: string description: DateTime value for date-time fields (ISO 8601 format) format: date-time example: 2024-01-15T10:30:00.000Z - type: boolean description: Boolean value for true/false fields example: true description: The actual value of the question (required on each nested question row; JSON null allowed when applicable). description: Dictionary containing question data for this collection item description: Array of CollectionItem for collection type fields description: The actual value of the question (required on each QuestionData row in `data`; JSON null is allowed for an empty optional answer). Can be a string, integer, number, float, date, date-time, boolean, or array of CollectionItem objects depending on the field type. index: type: integer description: Zero-based row index for repeatable collection rows in transaction data lists; 0 for single-value fields. format: int32 prefilled: type: boolean description: True when value is a prefill; omitted in JSON when false. additionalProperties: false description: 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. LocalizedText: type: object properties: en: type: string description: English text content nullable: true additionalProperties: false SubsectionBlueprint: required: - id - partName - title type: object properties: id: minLength: 1 type: string description: The unique identifier for the subsection partName: minLength: 1 type: string description: The part name for the subsection text: allOf: - $ref: "#/components/schemas/LocalizedText" description: Text content for the subsection title: allOf: - $ref: "#/components/schemas/LocalizedText" description: The title of the subsection isCustom: type: boolean description: Indicates if this is a custom subsection fieldGroups: type: array items: $ref: "#/components/schemas/FieldGroupBlueprint" description: Array of field groups within this subsection nullable: true subsections: type: array items: $ref: "#/components/schemas/SubsectionBlueprint" description: Array of nested subsections within this subsection nullable: true showInNavigation: type: boolean description: Indicates if this subsection should be shown in navigation copyable: type: string description: Role identifier controlling copy behavior. Use 'none' to disable copying, or a role name (e.g., 'owner', 'annuitant', 'insured', 'payor'). Multiple roles may be comma-separated. nullable: true visible: allOf: - $ref: "#/components/schemas/VisibilitySettings" description: 'Visibility conditions for the subsection. When present, the subsection is only visible when all conditions are met. Example: { "booleanOperator": "AND", "conditions": [ { "type": "equality", "isEqual": true, "value": "NY", "targetNodeId": "SolicitationStateCode" } ] }' example: booleanOperator: AND conditions: - type: equality isEqual: true value: Yes targetNodeId: Transaction.SolicitationState repeatable: allOf: - $ref: "#/components/schemas/RepeatableBlueprint" description: Repeat-instance metadata when the wizard subsection or custom control declares IsRepeated. additionalProperties: false VisibilitySettings: type: object properties: booleanOperator: type: string description: The boolean operator for combining conditions nullable: true conditions: type: array items: $ref: "#/components/schemas/VisibilityCondition" description: Array of visibility conditions with varying structures per condition type nullable: true additionalProperties: false example: booleanOperator: AND conditions: - type: equality isEqual: true value: Yes targetNodeId: Transaction.SolicitationState RepeatableBlueprint: type: object properties: repeatableAnswerNodeId: type: string description: Blueprint id this repeat block is bound to (matches SubsectionBlueprint.id or FieldGroupBlueprint.id). nullable: true addButtonText: allOf: - $ref: "#/components/schemas/LocalizedText" description: Localized label for the control that adds another row. removeButtonText: allOf: - $ref: "#/components/schemas/LocalizedText" description: Localized label for removing a row. minRepeatable: type: integer description: Minimum number of instances. format: int32 maxRepeatable: type: integer description: Maximum number of instances. format: int32 outputPath: type: string description: Optional binding path for persisted repeat instances. nullable: true additionalProperties: false SubscriberActionPayload: type: object properties: type: type: string description: Payload kind. "basic" includes a key/value map in the "payload" field; "none" omits the body. nullable: true payload: type: object additionalProperties: type: string description: Inner payload key/value map. Omitted from the JSON envelope when type is "none". nullable: true additionalProperties: false example: type: basic payload: transactionId: "1125715" stepName: MCDPS fieldId: "531783" SubscriberResponseHandler: type: object properties: type: type: string description: Handler kind. "context-modification" updates a context namespace; "blueprint-modification" applies the response to the rendered blueprint. nullable: true action: type: string description: 'Action to perform within the chosen handler kind. Examples: "update-namespace", "replace-whole".' nullable: true namespace: type: string description: Namespace to update for context-modification handlers. Omitted for handler types that do not use a namespace. nullable: true value: allOf: - $ref: "#/components/schemas/SubscriberResponseValue" description: How to extract the value to apply from the upstream response. example: type: response-query kind: json-path value: $.data additionalProperties: false example: type: blueprint-modification action: replace-whole value: type: response-query kind: json-path value: $.data FieldGroupBlueprint: required: - id - partName type: object properties: id: minLength: 1 type: string description: The unique identifier for the field group partName: minLength: 1 type: string description: An identifier (partName) for the field group text: allOf: - $ref: "#/components/schemas/LocalizedText" description: The text associated with a field group, such as descriptions or related notes. Supports localization through language codes (e.g., en, fr). title: allOf: - $ref: "#/components/schemas/LocalizedText" description: The title of the field group in multiple languages. Supports localization through language codes (e.g., en, fr). isCustom: type: boolean description: Indicates whether this is a custom field group fields: type: array items: $ref: "#/components/schemas/FieldBlueprint" description: Array of fields (questions) within this field group nullable: true displayAsCard: type: boolean description: Indicates if this field group should be displayed as a card copyable: type: string description: Role identifier controlling copy behavior. Use 'none' to disable copying, or a role name (e.g., 'owner', 'annuitant', 'insured', 'payor'). Multiple roles may be comma-separated. nullable: true repeatable: allOf: - $ref: "#/components/schemas/RepeatableBlueprint" description: Repeat-instance metadata when the wizard field element or custom control declares IsRepeated. additionalProperties: false VisibilityCondition: required: - type - targetNodeId type: object properties: type: enum: - equality - range - presence type: string description: Kind of comparison performed by the condition. example: equality isEqual: type: boolean description: When true the condition passes if the target value equals 'value'; when false the condition passes if it differs. example: true value: type: string description: The value to compare against the resolved target answer. example: NY targetNodeId: type: string description: The answer node identifier whose value is evaluated by this condition. example: SolicitationStateCode description: Single condition controlling whether a field/section is visible at runtime. SubscriberResponseValue: type: object properties: type: type: string description: Value source kind. "response-query" extracts via a query expression on the response body. nullable: true kind: type: string description: Query language used to evaluate the value expression. Currently always "json-path". nullable: true value: type: string description: The query expression itself (e.g., "$.data" to grab the response's data branch). nullable: true additionalProperties: false example: type: response-query kind: json-path value: $.data FieldBlueprint: required: - fieldType - id - partName - text - title type: object properties: fieldType: enum: - money - date - information - radio - input - email - dropdown - phone - checkboxgroup - number - checkbox type: string description: |- The type of field displayed for collecting response values: money - Currency input field date - Date selection input field information - Read-only informational text display field radio - Single-selection radio button field input - Free-form text input field email - Email address input field dropdown - Selection field with predefined options phone - Phone number input field checkboxgroup - Checkbox group field for multiple selections number - Number input field for numeric values checkbox - Checkbox field for single selection (value is string) text: allOf: - $ref: "#/components/schemas/LocalizedText" description: The text associated with a field title, such as descriptions or related notes. Supports localization through language codes (e.g., en, fr) title: allOf: - $ref: "#/components/schemas/LocalizedText" description: The field title in multiple languages. Supports localization through language codes (e.g., en, fr) answerNodeId: type: string description: A unique identifier used to store and infer a field's answer, and to build validation and visibility conditions across the order entry blueprint nullable: true renderOn: type: array items: $ref: "#/components/schemas/RenderCondition" description: An array of conditions that determine when a field is rendered nullable: true platforms: type: array items: type: string description: An array of platforms where this field is available (e.g., D2C-only versus advisor-driven experiences) nullable: true copyable: type: string description: A comma-separated list of roles (e.g., annuitant, insured, owner, payor) that are allowed to copy this field. nullable: true triggerStepNavigation: type: boolean description: Indicates whether the field triggers step navigation layout: allOf: - $ref: "#/components/schemas/LayoutSettings" description: Layout options for the field. Used to define the field's rendered width in the 12-column grid. displayInCardPreview: type: boolean description: Indicates whether this field should be displayed in card preview mode applicationModes: type: array items: type: string description: Array of application modes where this field is available. Helper for filtering what is shown in different modes or channels nullable: true placeholder: allOf: - $ref: "#/components/schemas/LocalizedText" description: List of localized default text values for the field. When rendered, the appropriate localized text is displayed as the field's initial answer until modified. id: minLength: 1 type: string description: The unique identifier for the field partName: minLength: 1 type: string description: An identifier (partName) for the field. validateAs: type: string description: Validation type applied to fields such as phone numbers, where the value must contain digits only. These validations exist and are managed through Zinnia UI nullable: true selectOptions: type: array items: $ref: "#/components/schemas/SelectOption" description: Array of options (answers) that can be selected for dropdown, radio, checkbox, or checkboxgroup fields nullable: true selectOptionsApplicationContext: allOf: - $ref: "#/components/schemas/SelectOptionsApplicationContext" description: Application context for select options sourced from subscriber dataset example: tag: "507602" labelKey: en: Name valuePath: Value visible: allOf: - $ref: "#/components/schemas/VisibilitySettings" description: Visibility settings containing a boolean operator and an array of conditions that determine when the field is visible. example: booleanOperator: AND conditions: - type: equality isEqual: true value: Yes targetNodeId: Transaction.SolicitationState valid: type: array items: $ref: "#/components/schemas/FieldValidationRule" description: An array of validation rules applied to the field (e.g., regex, number range, character count) nullable: true example: - message: en: Please enter valid email address conditions: conditions: - type: matchesRegexCondition targetNodeId: Transaction.Beneficiaries[0].EmailAddresses["Home"].Address regex: ^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$ - message: en: Please enter value greater than or equal to 1 and less than or equal to 9999999999 conditions: booleanOperator: and conditions: - type: numberComparisonCondition targetNodeId: Transaction.Payments[0].MonetaryAmounts["PaymentAmount"].CurrencyAmount value: 9999999999 operator: lessThanOrEqual - type: numberComparisonCondition targetNodeId: Transaction.Payments[0].MonetaryAmounts["PaymentAmount"].CurrencyAmount value: 1 operator: greaterThanOrEqual - message: en: Please enter no more than 128 characters conditions: conditions: - type: characterCountInBetween targetNodeId: PhysicalAddress.Line1 value: minLength: 0 maxLength: 128 optional: type: boolean description: Indicates if this field is optional (not required) disabled: type: boolean description: "Indicates whether the field is rendered as disabled (read-only) in the form. Emitted when the upstream control carries ReadOnly: 1 / ReadOnly: true. Omitted when the field is not disabled." nullable: true example: true hidden: type: boolean description: Indicates the field is not displayed in the UI but is still present in the blueprint and data. Emitted as true when upstream BaseControlType is 15 (Hidden). Omitted for all other field types. nullable: true additionalProperties: false RenderCondition: required: - type - targetNodeId type: object properties: type: enum: - equality - range - presence type: string description: Kind of comparison performed by the condition. example: equality isEqual: type: boolean description: When true the condition passes if the target value equals 'value'; when false the condition passes if it differs. example: true value: type: string description: The value to compare against the resolved target answer. example: NY targetNodeId: type: string description: The answer node identifier whose value is evaluated by this condition. example: SolicitationStateCode description: Single condition controlling whether a field/section is rendered. LayoutSettings: type: object properties: size: type: integer description: The size of the field in a 12-column HTML grid that determines its rendered width (12 = full-width, 6 = half-width, 4 = one-third, 3 = quarter-width). Field column widths sum to 12 per row - e.g., two fields of 6 sit side-by-side, three fields of 4 share a row, four fields of 3 share a row. format: int32 additionalProperties: false SelectOption: required: - text - value type: object properties: text: allOf: - $ref: "#/components/schemas/LocalizedText" description: The display text representing the user's selected answer. For example, a country dropdown may display 'United States of America' to the user, while the blueprint stores the value as 'USA' value: minLength: 1 type: string description: The value representing the user's selected answer. For example, a country dropdown may display 'United States of America' to the user, while the blueprint stores the value as 'USA' additionalProperties: false SelectOptionsApplicationContext: type: object properties: tag: type: string description: Tag used to associate dataset values with a field nullable: true labelKey: allOf: - $ref: "#/components/schemas/LocalizedText" description: Localized label key for dataset items valuePath: type: string description: Dataset value path nullable: true additionalProperties: false example: tag: "507602" labelKey: en: Name valuePath: Value FieldValidationRule: required: - conditions - message type: object properties: message: allOf: - $ref: "#/components/schemas/LocalizedText" description: Localized message displayed to the user when validation fails conditions: allOf: - $ref: "#/components/schemas/ValidationConditionGroup" description: The validation conditions wrapper containing an optional booleanOperator and an array of individual conditions example: booleanOperator: and conditions: - type: numberComparisonCondition targetNodeId: Transaction.Payments[0].MonetaryAmounts["PaymentAmount"].CurrencyAmount value: 9999999999 operator: lessThanOrEqual - type: numberComparisonCondition targetNodeId: Transaction.Payments[0].MonetaryAmounts["PaymentAmount"].CurrencyAmount value: 1 operator: greaterThanOrEqual additionalProperties: false example: message: en: Please enter valid email address conditions: conditions: - type: matchesRegexCondition targetNodeId: Transaction.Beneficiaries[0].EmailAddresses["Home"].Address regex: ^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$ ValidationConditionGroup: type: object properties: booleanOperator: type: string description: The boolean operator used to combine multiple conditions (e.g., "and"). Omitted when there is only one condition. nullable: true conditions: type: array items: $ref: "#/components/schemas/ValidationCondition" description: Array of validation conditions with varying structures per condition type nullable: true additionalProperties: false example: booleanOperator: and conditions: - type: numberComparisonCondition targetNodeId: Transaction.Payments[0].MonetaryAmounts["PaymentAmount"].CurrencyAmount value: 9999999999 operator: lessThanOrEqual - type: numberComparisonCondition targetNodeId: Transaction.Payments[0].MonetaryAmounts["PaymentAmount"].CurrencyAmount value: 1 operator: greaterThanOrEqual ValidationCondition: required: - type - targetNodeId type: object properties: type: enum: - matchesRegexCondition - numberComparisonCondition - characterCountInBetween type: string description: The kind of validation this condition performs. example: matchesRegexCondition targetNodeId: type: string description: The answer node identifier this condition evaluates. example: Transaction.Beneficiaries[0].EmailAddresses["Home"].Address regex: type: string description: Regex pattern. Only used when `type` is `matchesRegexCondition`. nullable: true example: ^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$ operator: enum: - lessThan - lessThanOrEqual - greaterThan - greaterThanOrEqual - equal - notEqual type: string description: Comparison operator. Only used when `type` is `numberComparisonCondition`. nullable: true example: lessThanOrEqual value: anyOf: - type: number example: 9999999999 - type: integer example: 1 - type: object properties: minLength: type: integer example: 0 maxLength: type: integer example: 128 description: Condition-specific value. Number for `numberComparisonCondition`; object `{ minLength, maxLength }` for `characterCountInBetween`. Absent for `matchesRegexCondition`. description: "Single validation condition inside a FieldValidationRule. The shape varies by `type`: `matchesRegexCondition` uses `regex`; `numberComparisonCondition` uses `value` + `operator`; `characterCountInBetween` uses `value: { minLength, maxLength }`." securitySchemes: openIdConnect: type: openIdConnect description: "OpenID Connect via Auth0. Clients present a JWT bearer token issued by the tenant in the `Authorization: Bearer ` header." openIdConnectUrl: https://login.qa.zinnia.com/.well-known/openid-configuration x-kong-security-openid-connect: config: auth_methods: - bearer verify_signature: true ignore_signature: [] consumer_claim: - sub consumer_optional: true ````