---
title: "Receives policyholder authorization status from MPV and updates the status"
url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/operations/updateAuthorizationStatus"
---

> Full API specification: https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84.md

# Receives policyholder authorization status from MPV and updates the status

`PUT` `/bpm/v1/policies/{planCode}/{policyNumber}/authorization/status`

Operation ID: `updateAuthorizationStatus`

## Path parameters

- `planCode` (string, required) - The plan code for the policy number
- `policyNumber` (string, required) - Policy Number

## Request body (required)

Content types: `application/json`

## Responses

- `200` - OK - Callback processed successfully
- `400` - Bad Request - Missing or invalid parameters
- `401` - Unauthorized - Missing or invalid JWT token
- `403` - Forbidden - Insufficient permissions or invalid scope
- `404` - Not Found - Transaction not found or correlationId unknown
- `409` - Conflict - Duplicate callback or status already updated
- `422` - Unprocessable Entity - Validation failed or inconsistent data
- `500` - Internal Server Error - Unexpected system failure

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Zinnia Policy Transactions API.
  version: 1.0.8
servers:
  - url: https://dev.api.zinnia.io
    description: DEV Environment
  - url: https://qa.api.zinnia.io
    description: QA Environment
paths:
  /bpm/v1/policies/{planCode}/{policyNumber}/authorization/status:
    put:
      x-internal: true
      tags:
        - Authorization Status Update
      summary: Receives policyholder authorization status from MPV and updates the
        status
      operationId: updateAuthorizationStatus
      parameters:
        - name: planCode
          in: path
          required: true
          description: The plan code for the policy number
          schema:
            type: string
            example: planCode
        - name: policyNumber
          in: path
          required: true
          description: Policy Number
          schema:
            type: string
            example: policyNumber
      requestBody:
        description: Policyholder Authorization request
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthorizationStatusRequest"
      responses:
        "200":
          description: OK - Callback processed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthorizationStatusResponse"
              example:
                status: 200
        "400":
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 400
                message: "Invalid or missing request field: correlationId"
        "401":
          description: Unauthorized - Missing or invalid JWT token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: "Authentication failed: missing or invalid bearer token."
        "403":
          description: Forbidden - Insufficient permissions or invalid scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: "Access denied: client does not have permission to invoke this API."
        "404":
          description: Not Found - Transaction not found or correlationId unknown
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 404
                message: "Transaction not found for correlationId:
                  468cd184-fb43-4a20-aa8c-23df99c0a353"
        "409":
          description: Conflict - Duplicate callback or status already updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 409
                message: "Duplicate callback detected for correlationId:
                  468cd184-fb43-4a20-aa8c-23df99c0a353"
        "422":
          description: Unprocessable Entity - Validation failed or inconsistent data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 422
                message: AuthorizationStatus value DENIED is not valid for this transaction
                  state.
        "500":
          description: Internal Server Error - Unexpected system failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 500
                message: An unexpected error occurred while processing the callback request.
      security:
        - Auth0: []
security:
  - Auth0: []
components:
  schemas:
    AuthorizationStatusRequest:
      type: object
      required:
        - recordId
        - correlationId
        - caseId
        - policyNumber
        - authorizationStatus
        - actionTimestamp
      properties:
        recordId:
          type: string
          description: Unique record ID (maps to transactionID)
          example: 546bed32-a8b6-43dc-8772-cefb1d469b1d
        correlationId:
          type: string
          description: Correlation ID linking BPM - MPV transaction
          example: 468cd184-fb43-4a20-aa8c-23df99c0a353
        caseId:
          type: string
          description: Case identifier within BPM
          example: CA0000487609
        policyNumber:
          type: string
          description: Policy Number associated with the transaction
          example: FM00000001
        authorizationStatus:
          type: string
          enum:
            - APPROVED
            - DENIED
          description: Policy Holder Authorization Status
          example: APPROVED
        actionTakenBy:
          type: string
          description: Name of Policy Holder
          example: Flora Anderson
        actionTimestamp:
          type: string
          format: date-time
          description: Generated at Time
          example: 2025-06-02T10:45:00Z
        source:
          type: string
          description: Source system sending the callback
          default: MPV
          example: My Policy View
    AuthorizationStatusResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          example: 404
        message:
          type: string
          example: "Invalid or missing request field: correlationId"
  securitySchemes:
    Auth0:
      type: openIdConnect
      openIdConnectUrl: https://login.qa.zinnia.com/.well-known/openid-configuration
      x-kong-security-openid-connect:
        config:
          run_on_preflight: true
          scopes_claim:
            - https://qa.api.zinnia.io/permissions
          audience_claim:
            - aud
          audience_required:
            - https://qa.api.zinnia.io
          client_id:
            - client_id
          auth_methods:
            - bearer
        enabled: true
        protocols:
          - grpc
          - grpcs
          - http
          - https
```