Zinnia Dataset API

openapi: 3.2.0
info:
  title: Market Connect Order Entry Dataset 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.'
  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
security:
- openIdConnect: []
tags:
- name: Dataset
  description: Dataset operations
paths:
  /market-connect/order-entry/v1/dataset:
    post:
      tags:
      - Dataset
      summary: Gets dataset values for a dependent control based on the provided payload
      description: '#### Error Responses


        - **400 Bad Request**


        - ```VALIDATION_ERROR``` - The request failed input validation.


        - **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 this resource.


        - **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 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.'
      operationId: getDataset
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetRequest'
            example:
              transactionId: '1064187'
              stepName: CarrierProductSelection
              fieldId: '504436'
              Transaction.Parameters["CarrierID"].Value: CARRIER-001
              Transaction.SolicitationState: Alabama
        required: true
      responses:
        '200':
          description: Returns the dataset payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetResponse'
              examples:
                success:
                  summary: Successful lookup
                  description: Status = "Success" with Data containing a JSON-encoded array of options.
                  value:
                    Data: '[{"Name":"Protected Deferred Annuity","Value":"223985"}]'
                    InstanceId: 504436
                    Message: DataSet contents retrieved successfully
                    Status: Success
                item-not-found:
                  summary: Dataset item not found
                  description: Business-level failure where the upstream service recognizes the request but has no matching dataset. InstanceId is present; Data is an empty array string.
                  value:
                    Data: '[]'
                    InstanceId: 1064416
                    Message: Error retrieving dataset contents.
                    Status: ItemNotFoundException`2
                null-reference:
                  summary: Backend exception (no dataset context)
                  description: Low-level exception from the upstream service. InstanceId and Data are absent because no dataset context was resolved.
                  value:
                    Message: Object reference not set to an instance of an object.
                    Status: NullReferenceException
        '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'
components:
  schemas:
    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
          - 'null'
        details:
          type:
          - string
          - 'null'
        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'
    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'
    DatasetRequest:
      required:
      - fieldId
      - stepName
      - transactionId
      type: object
      properties:
        transactionId:
          minLength: 1
          type: string
          description: Unique identifier of the transaction (positive integer as a string).
        stepName:
          minLength: 1
          type: string
          description: Name of the wizard step containing the dependent control.
        fieldId:
          minLength: 1
          type: string
          description: Identifier of the field (control) whose dataset is being requested.
      additionalProperties: {}
    DatasetResponse:
      required:
      - Message
      - Status
      type: object
      properties:
        Status:
          minLength: 1
          type: string
          description: Outcome of the dataset lookup. "Success" on success; otherwise the backend exception type name (e.g. "NullReferenceException", "ItemNotFoundException`2").
        Message:
          minLength: 1
          type: string
          description: Human-readable message describing the outcome. On success a confirmation string; on failure the backend error message.
        Data:
          type:
          - string
          - 'null'
          description: Dataset payload serialized as a JSON string. On success, a JSON array of {Name, Value} option objects. On failure, may be "[]" or omitted.
        InstanceId:
          type:
          - integer
          - 'null'
          description: Identifier of the dataset instance returned by the upstream service. Present for success and most failures; absent for low-level exceptions.
          format: int64
      additionalProperties: false
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      description: 'OpenID Connect via Auth0. Clients present a JWT bearer token issued by the tenant in the `Authorization: Bearer <token>` 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