Zinnia Market Connect Order Entry API

Headless order entry API that lets external distribution platforms, banks, broker-dealers and IMOs electronically initiate, save-and-resume, validate and submit life insurance and annuity applications, with ACORD-aligned prefill from existing quotes and suitability assessments, dataset-driven form rendering and real-time application status tracking.

Operations 19

GET /market-connect/order-entry/v1/attachment/{transactionId} Retrieves the attachment payload (documents, required documents and rules) for a transaction. #
POST /market-connect/order-entry/v1/attachment Ingests an EDS document attachment notification for a transaction. #
POST /market-connect/order-entry/v1/comments Saves a comment against the specified transaction. #
DELETE /market-connect/order-entry/v1/comments Deletes a comment from a transaction. #
GET /market-connect/order-entry/v1/comments/{transactionId} Retrieves the comments for a transaction. #
POST /market-connect/order-entry/v1/dataset Gets dataset values for a dependent control based on the provided payload. #
GET /market-connect/order-entry/v1/esignature/{transactionId} Retrieves the e-signature signer list for a transaction. #
GET /market-connect/order-entry/v1/esignature/{transactionId}/signer-status Retrieves DocuSign signer status for each recipient on a transaction. #
POST /market-connect/order-entry/v1/esignature Submits the Order Entry case for e-signature with the configured signer roster. #
POST /market-connect/order-entry/v1/esignature/cancel-ceremony Cancels the e-signature ceremony for a case (voids the DocuSign envelope and returns the case to Pending upstream). #
POST /market-connect/order-entry/v1/esignature/retrigger-email-notification Retriggers the DocuSign e-signature email notification for a case (only when e-signature is in progress upstream). #
POST /market-connect/order-entry/v1/esignature/update-signer Updates signer email or phone for a case while e-signature is pending upstream. #
GET /market-connect/order-entry/v1/health Returns a simple health status indicating the API process is running. #
GET /market-connect/order-entry/v1/productpricing/{transactionId} Retrieves the product pricing payload for a transaction. #
POST /market-connect/order-entry/v1/revieweraction Executes a reviewer action for the given transaction (forwards to the product order-entry service). #
POST /market-connect/order-entry/v1/transaction Create the Order Entry transaction. Routes to appropriate service based on CUSIP. #
GET /market-connect/order-entry/v1/transaction/{transactionId} Retrieves the order entry blueprint and its associated responses for a created life or annuity transaction #
PUT /market-connect/order-entry/v1/transaction/{transactionId} Update the Order Entry transaction data for enhanced blueprint (single-blueprint) transactions. #
POST /market-connect/order-entry/v1/transaction/{transactionId}/submit Submit an order entry transaction for processing. #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/zinnia-market-connect-order-entry-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

zinnia-market-connect-order-entry-openapi.yml Raw ↑
openapi: 3.0.1
info:
  title: Market Connect Order Entry API
  description: "**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.\n\n## Version History\n- **`1.0.3` (Latest)**\n  - Added optional ACORD-aligned `prefill` node to the create-transaction\
    \ request, enabling pre-population of party and product fields.\n  - Added optional `illustrationId`, `accountNumber`,\
    \ and `externalTransactionId` fields to the create-transaction request.\n- **`1.0.2`**\n  - Added signer-status, signer-update,\
    \ cancel-ceremony, and e-signature email-retrigger capabilities.\n  - Added reviewer approval, decline, and termination\
    \ actions, plus enhanced attachment metadata and upload/delete handling.\n  - Added HTTP 422 business-validation responses,\
    \ stricter request/control-type validation, optional opportunity IDs, and cache reliability fixes.\n- **`1.0.1`**\n  -\
    \ Expanded the OpenAPI specification with environment URLs, OpenID Connect security, and Kong integration metadata.\n\
    \  - Added attachment, comments, and product-pricing operations.\n  - Added e-signature recipient and submission workflows\
    \ and full-blueprint transaction updates.\n- **`1.0.0`**\n  - Added transaction submission and Life product blueprint\
    \ processing.\n  - Enabled the enhanced single-blueprint workflow without requiring a client-provided step name.\n  -\
    \ Expanded validation errors, conditional visibility, nested sections, custom controls, and bearer-token forwarding.\n\
    - **`0.9.0`**\n  - Added authorization checks through FGA and refined the Market Connect Order Entry route structure.\n\
    \  - Introduced create, retrieve, and progressive-save support for single-blueprint transactions.\n  - Improved life and\
    \ annuity transaction identification and service architecture.\n- **`0.8.0`**\n  - Introduced transaction creation and\
    \ the initial server-driven order-entry workflow.\n  - Added blueprint and question-data schemas for beneficiary, payment,\
    \ visibility, and optional-condition use cases.\n  - Standardized validation and enterprise error-response structures\
    \ in the API specification.\n\n## Overview\nThe 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.\n\n## Headless Support\nThe 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.\n\n## Authentication\n\
    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.\n\n## Base URLs\n- Development: `https://dev.api.zinnia.io`\n\
    - QA: `https://qa.api.zinnia.io`\n- UAT: `https://uat.api.zinnia.io`\n- Production: provided per integration agreement\n\
    \n## Versioning\nThe 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.\n\n## Error Handling\nError\
    \ 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.\n\n## Getting Started\n1. Acquire a JWT token from Auth0.\n2. `POST /market-connect/order-entry/v1/transaction`\
    \ with `state` and `cusip` to create a transaction.\n3. `GET /market-connect/order-entry/v1/transaction/{transactionId}`\
    \ to fetch the blueprint and data.\n4. `PUT /market-connect/order-entry/v1/transaction/{transactionId}` to save answers;\
    \ the API determines the step from the blueprint state.\n5. `POST /market-connect/order-entry/v1/transaction/{transactionId}/submit`\
    \ to submit the completed transaction.\n6. `POST /market-connect/order-entry/v1/ReviewerAction` with `action` and `transactionId`\
    \ when a reviewer approves, declines, or terminates a case in the Zinnia UI."
  termsOfService: https://zinnia.com/terms
  contact:
    name: API Support
    email: orderentrysupport@zinnia.com
  license:
    name: Proprietary
    url: https://zinnia.com/terms
  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/attachment/{transactionId}:
    get:
      tags:
      - Attachment
      summary: Retrieves the attachment payload (documents, required documents and rules) for a transaction.
      description: "#### Error Responses\n\n- **400 Bad Request**\n    \n- ```VALIDATION_ERROR``` - The request failed input\
        \ validation.\n\n- **401 Unauthorized**\n    \n- ```UNAUTHORIZED``` - Authentication failed or the access token is\
        \ missing, expired, or invalid.\n\n- **403 Forbidden**\n    \n- ```FORBIDDEN``` - The authenticated user is not authorized\
        \ to access this resource.\n\n- **404 Not Found**\n    \n- ```NOT_FOUND``` - No attachments were found for the specified\
        \ transaction.\n\n- **429 Too Many Requests**\n    \n- ```RATE_LIMIT_EXCEEDED``` - The client has exceeded the permitted\
        \ request rate or quota.\n\n- **500 Internal Server Error**\n    \n- ```UNEXPECTED_ERROR``` - An unexpected internal\
        \ system error occurred while processing the request.\n\n- **502 Bad Gateway**\n    \n- ```UPSTREAM_SERVICE_ERROR```\
        \ - An upstream dependency returned an invalid or unsuccessful response.\n\n- **503 Service Unavailable**\n    \n\
        - ```SERVICE_UNAVAILABLE``` - The service or a required dependency is temporarily unavailable.\n\n- **504 Gateway\
        \ Timeout**\n    \n- ```UPSTREAM_TIMEOUT``` - A required downstream service did not respond within the configured\
        \ timeout.\n\n#### Standard Error Response\n\nAll error responses conform to the standard ```ErrorResponse``` schema\
        \ and include:\n\n- A stable error code from ```ErrorInfo.code```.\n- A human-readable error message.\n- Optional\
        \ diagnostic details, when applicable.\n- A timestamp indicating when the error occurred.\nThis consistent format\
        \ enables clients to implement standardized error processing, logging, and troubleshooting across all Order Entry\
        \ API endpoints."
      operationId: getAttachment
      parameters:
      - name: transactionId
        in: path
        description: Unique identifier assigned when the Order Entry transaction is created. Resolves to the internal transaction;
          caller must be authorized for this transaction.
        required: true
        schema:
          type: string
        example: '1125715'
      responses:
        '200':
          description: Returns the attachment payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentResponse'
              examples:
                with-documents:
                  summary: Attachments with uploaded files
                  description: Includes documents array entries with documentId (EDS) and documentSize in bytes.
                  value:
                    transactionId: '1125715'
                    distributorCode: ABCD
                    carrierCode: ABCD
                    sourceSystem: AnnuityNet
                    caseId: CA0000188538
                    data:
                      additionalDocumentTypes:
                      - attachmentType: []
                        documentType:
                        - Wet-signed Paperwork
                        - Supporting Documents
                        - Trust Certification
                        - Green Card
                        - Driver License – Proof of Age
                        - Illustration
                        - POA Paperwork
                        - Check Deposit Form
                        formType: []
                      documentRules:
                      - conditions: Owner age < 65
                        key: PROOF_OF_AGE
                        message: Proof of age documentation may be required.
                        value: optional
                      documents:
                      - documentType: ESIGNATURE
                        fileName: NAICBuyerGuideFixedDeferredAnnuitiesMTNM.pdf
                        uploadDate: 04/06/2026 11:22:05 PM
                        documentId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        documentSize: 9000000
                        attachmentType: null
                        formType: null
                      - documentType: DRIVER LICENSE – PROOF OF AGE
                        fileName: NAICBuyerGuideFixedDeferredAnnuitiesMTNM1.pdf
                        uploadDate: 04/06/2026 11:26:07 PM
                        documentId: b2c3d4e5-f6a7-8901-bcde-f12345678901
                        documentSize: 10000000
                        attachmentType: null
                        formType: null
                      requiredDocuments:
                      - attachmentType: APP
                        displayName: Signed application
                        documentType: APPLICATION
                        formType: APP_FULL
                        message: Upload the fully signed application prior to submission.
        '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: abc
                errors:
                - code: INVALID_TRANSACTION_ID
                  description: Invalid transaction ID provided
                  details: Transaction ID abc is not valid
                  timestamp: '2026-05-18T14:30:00.0000000Z'
        '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: '1125715'
                errors:
                - code: NOT_FOUND
                  description: Attachments not found
                  details: The requested attachments could not be found
                  timestamp: '2026-05-18T14:30:00.0000000Z'
        '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: '1125715'
                errors:
                - code: UPSTREAM_SERVICE_ERROR
                  description: Attachment service error
                  details: Failed to get attachments
                  timestamp: '2026-05-18T14:30:00.0000000Z'
        '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'
  /market-connect/order-entry/v1/attachment:
    post:
      tags:
      - Attachment
      summary: Ingests an EDS document attachment notification for a transaction.
      description: "#### Error Responses\n\n- **400 Bad Request**\n    \n- ```VALIDATION_ERROR``` - The request failed input\
        \ validation.\n\n- **401 Unauthorized**\n    \n- ```UNAUTHORIZED``` - Authentication failed or the access token is\
        \ missing, expired, or invalid.\n\n- **403 Forbidden**\n    \n- ```FORBIDDEN``` - The authenticated user is not authorized\
        \ to access this resource.\n\n- **404 Not Found**\n    \n- ```NOT_FOUND``` - The specified transaction was not found.\n\
        \n- **429 Too Many Requests**\n    \n- ```RATE_LIMIT_EXCEEDED``` - The client has exceeded the permitted request rate\
        \ or quota.\n\n- **500 Internal Server Error**\n    \n- ```UNEXPECTED_ERROR``` - An unexpected internal system error\
        \ occurred while processing the request.\n\n- **502 Bad Gateway**\n    \n- ```UPSTREAM_SERVICE_ERROR``` - An upstream\
        \ dependency returned an invalid or unsuccessful response.\n\n- **503 Service Unavailable**\n    \n- ```SERVICE_UNAVAILABLE```\
        \ - The service or a required dependency is temporarily unavailable.\n\n- **504 Gateway Timeout**\n    \n- ```UPSTREAM_TIMEOUT```\
        \ - A required downstream service did not respond within the configured timeout.\n\n#### Standard Error Response\n\
        \nAll error responses conform to the standard ```ErrorResponse``` schema and include:\n\n- A stable error code from\
        \ ```ErrorInfo.code```.\n- A human-readable error message.\n- Optional diagnostic details, when applicable.\n- A timestamp\
        \ indicating when the error occurred.\nThis consistent format enables clients to implement standardized error processing,\
        \ logging, and troubleshooting across all Order Entry API endpoints."
      operationId: ingestAttachmentDocument
      requestBody:
        description: The document ingestion payload.
        content:
          application/json:
            schema:
              required:
              - transactionId
              - documentId
              - sourceSystem
              - action
              allOf:
              - $ref: '#/components/schemas/IngestAttachmentDocumentRequest'
              example:
                transactionId: '123456'
                documentId: 6a3c4358bd44a9000c8d140e
                sourceSystem: AnnuityNet
                action: added
            examples:
              document-added:
                summary: Document added
                description: A new EDS document was added for the transaction.
                value:
                  transactionId: '123456'
                  documentId: 6a3c4358bd44a9000c8d140e
                  sourceSystem: AnnuityNet
                  action: added
              document-deleted:
                summary: Document deleted
                description: An EDS document was removed from the transaction.
                value:
                  transactionId: '123456'
                  documentId: 6a3c4358bd44a9000c8d140e
                  sourceSystem: LifeSpeed
                  action: deleted
        required: true
      responses:
        '200':
          description: Returns the ingestion result envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestAttachmentDocumentResponse'
              example:
                caseId: CA0000188538
                isSuccess: true
                message: Attachment document ingested successfully.
                status: Success
        '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: '123456'
                errors:
                - code: VALIDATION_ERROR
                  description: Invalid source system provided
                  details: sourceSystem must be AnnuityNet or LifeSpeed
                  timestamp: '2026-05-18T14:30:00.0000000Z'
        '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: '123456'
                errors:
                - code: UPSTREAM_SERVICE_ERROR
                  description: Attachment service error
                  details: Failed to ingest attachment document
                  timestamp: '2026-05-18T14:30:00.0000000Z'
        '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'
  /market-connect/order-entry/v1/comments:
    post:
      tags:
      - Comments
      summary: Saves a comment against the specified transaction.
      description: "#### Error Responses\n\n- **400 Bad Request**\n    \n- ```VALIDATION_ERROR``` - The request body failed\
        \ validation or required fields are missing.\n- ```INVALID_TRANSACTION_ID``` - The supplied transaction ID is invalid\
        \ (not a positive integer).\n\n- **401 Unauthorized**\n    \n- ```UNAUTHORIZED``` - Authentication failed or the access\
        \ token is missing, expired, or invalid.\n\n- **403 Forbidden**\n    \n- ```FORBIDDEN``` - The authenticated user\
        \ is not authorized to access this resource.\n\n- **404 Not Found**\n    \n- ```NOT_FOUND``` - No transaction exists\
        \ for the specified transaction ID.\n\n- **429 Too Many Requests**\n    \n- ```RATE_LIMIT_EXCEEDED``` - The client\
        \ has exceeded the permitted request rate or quota.\n\n- **500 Internal Server Error**\n    \n- ```UNEXPECTED_ERROR```\
        \ - An unexpected internal system error occurred while processing the request.\n\n- **502 Bad Gateway**\n    \n- ```UPSTREAM_SERVICE_ERROR```\
        \ - An upstream dependency returned an invalid or unsuccessful response.\n\n- **503 Service Unavailable**\n    \n\
        - ```SERVICE_UNAVAILABLE``` - The service or a required dependency is temporarily unavailable.\n\n- **504 Gateway\
        \ Timeout**\n    \n- ```UPSTREAM_TIMEOUT``` - A required downstream service did not respond within the configured\
        \ timeout.\n\n#### Standard Error Response\n\nAll error responses conform to the standard ```ErrorResponse``` schema\
        \ and include:\n\n- A stable error code from ```ErrorInfo.code```.\n- A human-readable error message.\n- Optional\
        \ diagnostic details, when applicable.\n- A timestamp indicating when the error occurred.\nThis consistent format\
        \ enables clients to implement standardized error processing, logging, and troubleshooting across all Order Entry\
        \ API endpoints."
      operationId: saveComment
      requestBody:
        description: The comment payload to save.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SaveCommentRequest'
              example:
                appSubIndicator: App
                commentSource: OrderEntryUI
                commentText: Customer requested a follow-up call before submission.
                statusAtStep: InProgress
                statusDisplayName: In Progress
                stepTitle: Owner Information
                transactionId: '1125715'
        required: true
      responses:
        '200':
          description: Returns the save comment envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveCommentResponse'
        '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 occ

# --- truncated at 32 KB (298 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zinnia/refs/heads/main/openapi/zinnia-market-connect-order-entry-openapi.yml