{
  "openapi": "3.1.0",
  "info": {
    "title": "AIB life Proposed Partner Sandbox API",
    "version": "0.1.0-proposed",
    "description": "Non-operational design contract for approved-partner discussion and interface prototyping. It does not provide live financial services.",
    "contact": {
      "name": "Saol Assurance",
      "url": "https://saol.sandbox.codebridge.io/contact-us"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.api.aiblife.example",
      "description": "Illustrative non-routable sandbox host"
    }
  ],
  "tags": [
    {
      "name": "Product discovery",
      "description": "Proposed sandbox endpoints for approved partner product journeys."
    },
    {
      "name": "Applications",
      "description": "Proposed consented application journeys for approved partners."
    },
    {
      "name": "Policies and servicing",
      "description": "Proposed customer-authorised policy management endpoints."
    },
    {
      "name": "Events and webhooks",
      "description": "Proposed signed notifications for partner systems."
    }
  ],
  "paths": {
    "/v1/products": {
      "get": {
        "tags": [
          "Product discovery"
        ],
        "operationId": "listProducts",
        "summary": "List partner products",
        "description": "Returns products enabled for the authenticated partner and distribution channel.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/products/{productId}": {
      "get": {
        "tags": [
          "Product discovery"
        ],
        "operationId": "getProduct",
        "summary": "Get product details",
        "description": "Returns current product metadata, journey requirements and authoritative document references.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/products/{productId}/documents": {
      "get": {
        "tags": [
          "Product discovery"
        ],
        "operationId": "listProductDocuments",
        "summary": "List product documents",
        "description": "Returns brochures, terms, disclosures and other documents required for the product journey.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/prsa/applications": {
      "post": {
        "tags": [
          "Applications"
        ],
        "operationId": "createPrsaApplication",
        "summary": "Start a PRSA application",
        "description": "Creates a draft Personal Retirement Savings Account application after required partner and customer context is supplied.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.write"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/v1/policy-applications": {
      "post": {
        "tags": [
          "Applications"
        ],
        "operationId": "createPolicyApplication",
        "summary": "Start a policy application",
        "description": "Creates a draft application for an eligible protection, pension or investment product.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.write"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/v1/applications/{applicationId}": {
      "get": {
        "tags": [
          "Applications"
        ],
        "operationId": "getApplication",
        "summary": "Get application status",
        "description": "Returns the application state, outstanding requirements and next permitted actions.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/applications/{applicationId}/submit": {
      "post": {
        "tags": [
          "Applications"
        ],
        "operationId": "submitApplication",
        "summary": "Submit an application",
        "description": "Submits a completed application after all required consent, advice and validation controls have passed.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/v1/customers/{customerId}/policies": {
      "get": {
        "tags": [
          "Policies and servicing"
        ],
        "operationId": "listCustomerPolicies",
        "summary": "List customer policies",
        "description": "Returns policies the authenticated and consented customer is permitted to view through the partner.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/policies/{policyId}": {
      "get": {
        "tags": [
          "Policies and servicing"
        ],
        "operationId": "getPolicy",
        "summary": "Get policy details",
        "description": "Returns a policy summary, current servicing options and authoritative document links.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/policies/{policyId}/top-ups": {
      "post": {
        "tags": [
          "Policies and servicing"
        ],
        "operationId": "createPolicyTopUp",
        "summary": "Create a policy top-up",
        "description": "Creates an eligible additional pension or investment contribution following validation and customer confirmation.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/v1/policies/{policyId}/documents": {
      "get": {
        "tags": [
          "Policies and servicing"
        ],
        "operationId": "listPolicyDocuments",
        "summary": "List policy documents",
        "description": "Returns metadata and time-limited retrieval links for documents the customer is authorised to access.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    },
    "/v1/policies/{policyId}/service-requests": {
      "post": {
        "tags": [
          "Policies and servicing"
        ],
        "operationId": "createServiceRequest",
        "summary": "Create a service request",
        "description": "Creates an auditable request for a supported policy change or customer service action.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/v1/webhook-endpoints": {
      "post": {
        "tags": [
          "Events and webhooks"
        ],
        "operationId": "createWebhookEndpoint",
        "summary": "Register a webhook endpoint",
        "description": "Registers a sandbox callback URL and its subscribed event types.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.write"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/v1/events/{eventId}": {
      "get": {
        "tags": [
          "Events and webhooks"
        ],
        "operationId": "getEvent",
        "summary": "Retrieve an event",
        "description": "Retrieves an auditable event such as application.updated, policy.document.created or top_up.completed.",
        "x-saol-status": "proposed-non-operational",
        "security": [
          {
            "oauth2": [
              "partner.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "eventId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful sandbox response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Consent, scope or partner permission is insufficient"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Proposed OAuth 2.1 partner and customer-authorisation model.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://identity.aiblife.example/oauth2/authorize",
            "tokenUrl": "https://identity.aiblife.example/oauth2/token",
            "scopes": {
              "partner.read": "Read approved partner resources",
              "partner.write": "Create approved partner actions"
            }
          }
        }
      }
    }
  },
  "x-saol-status": "proposed-non-operational"
}