openapi: 3.1.0
info:
  title: Majesco Insurance Policy Administration Billing Policies API
  description: Majesco cloud-based insurance platform API for policy administration, claims management, billing, and distribution. Supports P&C, L&A, and specialty lines with REST interfaces for digital insurance operations.
  version: 1.0.0
  contact:
    name: Majesco Support
    url: https://www.majesco.com/contact/
  license:
    name: Proprietary
    url: https://www.majesco.com/terms
servers:
- url: https://api.majesco.example.com/v1
  description: Majesco API (customer-specific tenant URL)
security:
- OAuth2:
  - read
  - write
tags:
- name: Policies
  description: Insurance policy lifecycle management
paths:
  /policies:
    get:
      operationId: listPolicies
      summary: List policies
      description: Retrieve a paginated list of insurance policies. Supports filtering by product type, effective date, status, and policyholder.
      tags:
      - Policies
      parameters:
      - name: status
        in: query
        description: Filter by policy status
        schema:
          type: string
          enum:
          - active
          - expired
          - cancelled
          - pending
          - lapsed
      - name: productType
        in: query
        description: Filter by insurance product type
        schema:
          type: string
          enum:
          - auto
          - home
          - commercial
          - life
          - health
          - specialty
      - name: policyholderName
        in: query
        schema:
          type: string
      - name: effectiveDateFrom
        in: query
        schema:
          type: string
          format: date
      - name: effectiveDateTo
        in: query
        schema:
          type: string
          format: date
      - name: pageSize
        in: query
        schema:
          type: integer
          default: 50
          maximum: 500
      - name: pageToken
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of policies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createPolicy
      summary: Create a new policy
      description: Initiate a new insurance policy. The system validates underwriting rules and returns a policy number on success.
      tags:
      - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyCreateRequest'
      responses:
        '201':
          description: Policy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Underwriting validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
  /policies/{policyNumber}:
    get:
      operationId: getPolicy
      summary: Get a policy by policy number
      description: Retrieve full details of a single policy including coverage, endorsements, and premium breakdown.
      tags:
      - Policies
      parameters:
      - name: policyNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Policy details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePolicy
      summary: Update (endorse) a policy
      description: Apply mid-term endorsements to an in-force policy such as coverage changes, vehicle additions, or address updates.
      tags:
      - Policies
      parameters:
      - name: policyNumber
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyUpdateRequest'
      responses:
        '200':
          description: Policy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '422':
          description: Endorsement validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
  /policies/{policyNumber}/cancel:
    post:
      operationId: cancelPolicy
      summary: Cancel a policy
      description: Cancel an in-force policy with a cancellation reason and effective date.
      tags:
      - Policies
      parameters:
      - name: policyNumber
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancellationRequest'
      responses:
        '200':
          description: Policy cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
  /policies/{policyNumber}/renew:
    post:
      operationId: renewPolicy
      summary: Renew a policy
      description: Generate a renewal offer for a policy approaching its expiration date.
      tags:
      - Policies
      parameters:
      - name: policyNumber
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                renewalDate:
                  type: string
                  format: date
                premiumChangePct:
                  type: number
                  description: Percentage change in premium for the renewal term
      responses:
        '200':
          description: Renewal offer generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
components:
  schemas:
    Coverage:
      type: object
      properties:
        coverageCode:
          type: string
        coverageDescription:
          type: string
        limit:
          type: number
        deductible:
          type: number
        premium:
          type: number
        status:
          type: string
          enum:
          - active
          - excluded
          - suspended
    Policy:
      type: object
      properties:
        policyNumber:
          type: string
          description: Unique policy number
        status:
          type: string
          enum:
          - active
          - expired
          - cancelled
          - pending
          - lapsed
        productType:
          type: string
          enum:
          - auto
          - home
          - commercial
          - life
          - health
          - specialty
        effectiveDate:
          type: string
          format: date
        expirationDate:
          type: string
          format: date
        cancellationDate:
          type: string
          format: date
        policyholder:
          $ref: '#/components/schemas/Policyholder'
        coverages:
          type: array
          items:
            $ref: '#/components/schemas/Coverage'
        premium:
          $ref: '#/components/schemas/Premium'
        endorsements:
          type: array
          items:
            $ref: '#/components/schemas/Endorsement'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CoverageRequest:
      type: object
      required:
      - coverageCode
      properties:
        coverageCode:
          type: string
        limit:
          type: number
        deductible:
          type: number
    Policyholder:
      type: object
      required:
      - firstName
      - lastName
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        email:
          type: string
          format: email
        phone:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    Endorsement:
      type: object
      properties:
        endorsementNumber:
          type: string
        type:
          type: string
        effectiveDate:
          type: string
          format: date
        description:
          type: string
        premiumChange:
          type: number
    ValidationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        violations:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    CancellationRequest:
      type: object
      required:
      - effectiveDate
      - reason
      properties:
        effectiveDate:
          type: string
          format: date
        reason:
          type: string
          enum:
          - nonpayment
          - insured_request
          - underwriting
          - fraud
          - other
        notes:
          type: string
    Premium:
      type: object
      properties:
        annualPremium:
          type: number
        taxAmount:
          type: number
        feesAmount:
          type: number
        totalPremium:
          type: number
        currency:
          type: string
          default: USD
        billingFrequency:
          type: string
          enum:
          - annual
          - semi_annual
          - quarterly
          - monthly
    PolicyListResponse:
      type: object
      properties:
        policies:
          type: array
          items:
            $ref: '#/components/schemas/Policy'
        totalCount:
          type: integer
        nextPageToken:
          type: string
    Address:
      type: object
      properties:
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
          description: Two-letter US state code
          pattern: ^[A-Z]{2}$
        postalCode:
          type: string
        country:
          type: string
          default: US
    PolicyCreateRequest:
      type: object
      required:
      - productType
      - effectiveDate
      - policyholder
      - coverages
      properties:
        productType:
          type: string
          enum:
          - auto
          - home
          - commercial
          - life
          - health
          - specialty
        effectiveDate:
          type: string
          format: date
        expirationDate:
          type: string
          format: date
        policyholder:
          $ref: '#/components/schemas/Policyholder'
        coverages:
          type: array
          items:
            $ref: '#/components/schemas/CoverageRequest'
        agentCode:
          type: string
        channelCode:
          type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string
    PolicyUpdateRequest:
      type: object
      properties:
        endorsementType:
          type: string
        effectiveDate:
          type: string
          format: date
        changes:
          type: object
          additionalProperties: true
  responses:
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.majesco.example.com/oauth2/token
          scopes:
            read: Read access to policies, claims, and billing
            write: Write access for policy and claim operations
externalDocs:
  description: Majesco Developer Portal
  url: https://www.majesco.com/