openapi: 3.1.0
info:
  description: "Adaptive API for external integrations.\n\n## \uD83D\uDCCA API Overview\n\nThe Adaptive API enables organizations to build comprehensive reporting and analytics around their security awareness training programs. This RESTful API provides programmatic access to track employee training progress, monitor compliance, and generate insights about your organization's security training effectiveness.\n\n### Purpose & Use Cases\n\nThis API is designed for:\n- **Compliance Reporting**: Track training completion rates and identify employees with overdue trainings\n- **Progress Monitoring**: Get real-time visibility into individual and team training progress\n- **Data Integration**: Sync training data with your HRIS, BI tools, or custom dashboards\n- **Automated Workflows**: Build alerts and notifications for training milestones or compliance deadlines\n\n### Technical Design\n\nThe API follows REST principles with:\n- Resource-oriented URLs that clearly represent your data\n- Standard HTTP methods (GET for reading data)\n- JSON responses for easy parsing and integration\n- Consistent error handling with detailed error messages\n- Token-based authentication for secure access\n\n### Available Resources\n\n| Resource | Purpose | Common Use Cases |\n|----------|---------|------------------|\n| **Users** | Access employee directory data | • Export user lists for reporting<br>• Track user status changes<br>• Map users to departments |\n| **Training** | Monitor training campaigns and progress | • Track campaign completion rates<br>• Identify at-risk employees<br>• Generate compliance reports |\n\n## \uD83D\uDE80 Quick Start Guide\n\nGet started with the Adaptive API in just 3 steps:\n\n### Step 1: Get Your API Token\nSee [Authentication](#section/Authentication) for more details on how to generate and use API tokens.\n\n### Step 2: Make Your First API Call\n```bash\ncurl -X GET https://api.adaptivesecurity.com/v2/users \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\n### Step 3: Handle the Response\n```json\n{\n  \"users\": [\n    {\n      \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n      \"email\": \"john.smith@example.com\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Smith\",\n      \"status\": \"ACTIVE\"\n    }\n  ],\n  \"page_after\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n## \uD83D\uDD10 Authentication\n\nAll API endpoints require authentication using an API token:\n\n```http\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n**Token Management:**\n- Tokens are generated in the Admin portal under **Settings → API**\n- Tokens have a user-set expiration but can be revoked at any time\n- Store tokens securely - treat them like passwords\n## \uD83C\uDF10 Base URL\n\nAll API endpoints are relative to:\n```\nhttps://api.adaptivesecurity.com\n```\n\n## \uD83D\uDEA8 Error Handling\n\nAll API errors follow a consistent JSON structure:\n\n### Standard Error Response\n```json\n{\n  \"error_code\": \"RESOURCE_NOT_FOUND\",\n  \"message\": \"The requested user was not found\",\n  \"status_code\": 404,\n  \"request_id\": \"3e502c09-4fd3-42d3-8b3a-4e2f08de0bbf\"\n}\n```\n\n### Validation Error Response\n```json\n{\n  \"error_code\": \"VALIDATION_ERROR\",\n  \"message\": \"Request validation failed\",\n  \"status_code\": 400,\n  \"request_id\": \"1d7c1712-2b8e-43f4-90c6-1185e249bdf0\",\n  \"details\": [\n    {\n      \"field\": \"page\",\n      \"message\": \"Page must be a non-negative integer\"\n    }\n  ]\n}\n```\n\n### Error Code Reference\n| Code | Status | Description | Action |\n|------|--------|-------------|--------|\n| `INVALID_TOKEN` | 401 | Token is invalid or expired | Check token validity |\n| `RESOURCE_NOT_FOUND` | 404 | Resource doesn't exist | Verify resource ID |\n| `VALIDATION_ERROR` | 400 | Request validation failed | Check field errors |\n| `INTERNAL_SERVER_ERROR` | 500 | Server error | Contact support |\n\n## \uD83D\uDCCB Request & Response Headers\n\n### Required Request Headers\n```http\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n### Optional Request Headers\n```http\nAccept: application/json\nContent-Type: application/json  # Required for POST/PUT\n```\n\n### Response Headers\n```http\nX-Request-ID: 6acb3ce1-672a-4a49-8fa1-f1a994eef9fd\nContent-Type: application/json\n```\n\n## \uD83D\uDCC4 Pagination\n\nList endpoints return paginated results for optimal performance:\n\n- **Page cursor**: `page_after` field in the response to get the next page\n- **Default sorting**: By creation date (newest first)\n\n### Pagination Example\n```bash\n# Get the next page of users\ncurl -X GET \"https://api.adaptivesecurity.com/v2/users?page_after=5a6dce1e-8d0f-46b1-b263-50b6adca62da\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\n### Pagination Response\n```json\n{\n  \"users\": [...],\n  \"page_after\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n## \uD83D\uDD50 Timestamps\n\nAll timestamps use ISO 8601 format in UTC:\n```\n2024-12-10T15:30:45.402Z\n```"
  title: Adaptive Audit Logs Phishing API
  version: v2
servers:
- url: https://api.adaptivesecurity.com
  description: Production API
security:
- bearer-token: []
tags:
- description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Phishing campaign and simulation management endpoints'
  name: Phishing
paths:
  /v2/phishing/campaigns:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve a paginated list of phishing campaigns'
      operationId: listPhishingCampaigns
      parameters:
      - description: Page cursor
        example: b2c3d4e5-f6a7-8901-bcde-f23456789012
        in: query
        name: page_after
        required: false
        schema:
          type: string
      - description: Page size
        example: 50
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          default: 50
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    campaigns:
                    - campaign_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: Quarterly Phish Test
                      target: GROUPS
                      groups:
                      - group_id: f6a7b8c9-d0e1-2345-fabc-d67890123456
                        name: All Users
                      scenarios:
                      - scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                        name: Zoom Deepfake
                        sender: Zoom
                        difficulty: Hard
                        spoofPageType: DEEPFAKE_SPOOF_PAGE
                        channel: EMAIL
                        attackVector: LINK_CLICKED
                      - scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                        name: Google Account Compromise
                        sender: Google
                        difficulty: Easy
                        spoofPageType: null
                        channel: EMAIL
                        attackVector: LINK_CLICKED
                      - scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                        name: Internal Audit Feedback
                        sender: Executive
                        difficulty: Medium
                        spoofPageType: null
                        channel: EMAIL
                        attackVector: QR_CODE_SCANNED
                      mode: RECURRING
                      status: IN_PROGRESS
                      created_date: '2025-06-01T13:19:13.402Z'
                      start_date: '2025-06-10T13:19:13.402Z'
                      end_date: '2025-08-10T13:19:13.402Z'
                      distribution_interval: TWO_WEEKS
                      recurring_interval: MONTH
                      simulations:
                      - simulation_id: c18f4e0b-5678-9abc-def0-123456789abc
                        start_date: '2025-06-10T13:19:13.402Z'
                        end_date: '2025-07-10T13:19:13.402Z'
                        status: COMPLETED
                      - simulation_id: e9a7f2d1-abcd-ef01-2345-6789abcdef01
                        start_date: '2025-07-10T13:19:13.402Z'
                        end_date: '2025-08-10T13:19:13.402Z'
                        status: IN_PROGRESS
                    page_after: f3c7c8f3-1234-5678-9abc-def012345678
              schema:
                $ref: '#/components/schemas/PhishingCampaignListResponseDto'
          description: Successfully retrieved phishing campaigns
        '400':
          content:
            application/json:
              examples:
                Validation Error:
                  description: Validation Error
                  value:
                    error_code: VALIDATION_ERROR
                    message: Request validation failed
                    status_code: 400
                    request_id: 5f8e9a7b-1c2d-3e4f-5a6b-7c8d9e0f1a2b
                    details:
                    - field: page_size
                      message: Page size must be greater than or equal to 1
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
          description: Bad request - Invalid parameters
        '401':
          content:
            application/json:
              examples:
                Unauthorized Error:
                  description: Unauthorized Error
                  value:
                    error_code: INVALID_TOKEN
                    message: The provided authentication token is invalid or expired
                    status_code: 401
                    request_id: dcaf9f7e-6c47-4c93-bb41-0e2d8d9bb0de
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '429':
          content:
            application/json:
              examples:
                Rate Limit Error:
                  description: Rate Limit Error
                  value:
                    error_code: RATE_LIMIT_EXCEEDED
                    message: API rate limit exceeded. Please retry after some time
                    status_code: 429
                    request_id: b7c1196e-2c6e-4d17-8f3c-fcb62d6d27a2
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Too many requests - Rate limit exceeded
        '500':
          content:
            application/json:
              examples:
                Internal Server Error:
                  description: Internal Server Error
                  value:
                    error_code: INTERNAL_SERVER_ERROR
                    message: An unexpected error occurred. Please try again later
                    status_code: 500
                    request_id: f351ac3c-cd5e-4ec7-89dc-191fc40a83f2
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: List phishing campaigns
      tags:
      - Phishing
  /v2/phishing/campaigns/enrollments:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve details about phishing enrollments with campaign, simulation, and user filters'
      operationId: getPhishingEnrollments
      parameters:
      - description: User ID
        example: 123e4567-e89b-12d3-a456-426614174000
        in: query
        name: user_id
        required: false
        schema:
          type: string
      - description: Phishing campaign ID
        example: f3c7c8f3-1234-5678-9abc-def012345678
        in: query
        name: campaign_id
        required: false
        schema:
          type: string
      - description: Simulation execution ID
        example: c18f4e0b-5678-9abc-def0-123456789abc
        in: query
        name: simulation_id
        required: false
        schema:
          type: string
      - description: Page cursor
        example: f248c6c3-9c93-4d62-a41b-9843de18f56b
        in: query
        name: page_after
        required: false
        schema:
          type: string
      - description: Page size
        example: 50
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          default: 50
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    enrollments:
                    - enrollment_id: d0e1f2a3-b4c5-6789-defa-b01234567890
                      campaign_id: c3d4e5f6-a7b8-9012-cdef-a34567890123
                      simulation_id: c18f4e0b-5678-9abc-def0-123456789abc
                      user:
                        id: a3b4c5d6-e7f8-9012-abcd-e34567890123
                        email: john.smith@example.com
                      scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                      scheduled_at: '2025-06-10T15:02:38.000Z'
                      delivered_at: '2025-06-10T15:02:38.000Z'
                      opened_at: '2025-06-10T15:04:38.000Z'
                      clicked_at: '2025-06-10T15:05:38.000Z'
                      replied_at: null
                      attachment_opened_at: null
                      credentials_entered: '2025-06-10T15:07:38.000Z'
                      qr_code_scanned: null
                      reported_at: null
                      failed_at: '2025-06-10T15:07:38.000Z'
                      ip: 192.168.1.100
                      ip_location: Philadelphia, PA
                    - enrollment_id: e1f2a3b4-c5d6-7890-efab-c12345678901
                      campaign_id: d4e5f6a7-b8c9-0123-defa-b45678901234
                      simulation_id: e9a7f2d1-9999-8888-7777-9ac3
                      user:
                        id: a3b4c5d6-e7f8-9012-abcd-e34567890123
                        email: john.smith@example.com
                      scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                      scheduled_at: '2025-07-10T14:30:22.000Z'
                      delivered_at: '2025-07-10T14:30:22.000Z'
                      opened_at: '2025-07-10T14:35:18.000Z'
                      clicked_at: null
                      replied_at: null
                      attachment_opened_at: null
                      credentials_entered: null
                      qr_code_scanned: null
                      reported_at: '2025-07-10T14:36:45.000Z'
                      failed_at: null
                      ip: 192.168.1.100
                      ip_location: Philadelphia, PA
                    - enrollment_id: f2a3b4c5-d6e7-8901-fabc-d23456789012
                      campaign_id: e5f6a7b8-c9d0-1234-efab-c56789012345
                      simulation_id: f1a2b3c4-dddd-eeee-ffff-0ab1
                      user:
                        id: b4c5d6e7-f8a9-0123-bcde-f45678901234
                        email: jane.smith@example.com
                      scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                      scheduled_at: '2025-06-15T10:45:12.000Z'
                      delivered_at: '2025-06-15T10:45:12.000Z'
                      opened_at: '2025-06-15T11:22:33.000Z'
                      clicked_at: '2025-06-15T11:23:11.000Z'
                      replied_at: null
                      attachment_opened_at: null
                      credentials_entered: null
                      qr_code_scanned: null
                      reported_at: null
                      failed_at: '2025-06-15T11:23:38.000Z'
                      ip: 192.168.1.100
                      ip_location: New York, NY
                    page_after: f2a3b4c5-d6e7-8901-fabc-d23456789012
              schema:
                $ref: '#/components/schemas/PhishingEnrollmentListResponseDto'
          description: Successfully retrieved phishing enrollment details
        '401':
          content:
            application/json:
              examples:
                Unauthorized Error:
                  description: Unauthorized Error
                  value:
                    error_code: INVALID_TOKEN
                    message: The provided authentication token is invalid or expired
                    status_code: 401
                    request_id: 5a7384c9-b5de-4aa1-a144-faa0de243ab0
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '429':
          content:
            application/json:
              examples:
                Rate Limit Error:
                  description: Rate Limit Error
                  value:
                    error_code: RATE_LIMIT_EXCEEDED
                    message: API rate limit exceeded. Please retry after some time
                    status_code: 429
                    request_id: 6e9d2fb1-95e2-49e2-ae36-9de6e6f51c25
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Too many requests - Rate limit exceeded
        '500':
          content:
            application/json:
              examples:
                Internal Server Error:
                  description: Internal Server Error
                  value:
                    error_code: INTERNAL_SERVER_ERROR
                    message: An unexpected error occurred. Please try again later
                    status_code: 500
                    request_id: a0a7b8e0-fc0b-46b1-8dbb-0d04872f9678
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: Get phishing enrollments
      tags:
      - Phishing
  /v2/phishing/campaigns/{campaignId}:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve detailed information about a specific phishing campaign including simulation summary'
      operationId: getPhishingCampaign
      parameters:
      - description: Campaign ID
        example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        in: path
        name: campaignId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    campaign_id: f3c7c8f3-1234-5678-9abc-def012345678
                    name: Quarterly Phish Test
                    target: GROUPS
                    groups:
                    - group_id: cf7fc19b-d312-47bb-8289-79774e3218d1
                      name: All Users
                    scenarios:
                    - scenario_id: a7b8c9d0-e1f2-3456-abcd-e78901234567
                      name: Zoom Deepfake
                      sender: Zoom
                      difficulty: Hard
                      spoofPageType: DEEPFAKE_SPOOF_PAGE
                      channel: EMAIL
                      attackVector: LINK_CLICKED
                    - scenario_id: b8c9d0e1-f2a3-4567-bcde-f89012345678
                      name: Google Account Compromise
                      sender: Google
                      difficulty: Easy
                      spoofPageType: LOGIN_SPOOF_PAGE
                      channel: EMAIL
                      attackVector: LINK_CLICKED
                    - scenario_id: c9d0e1f2-a3b4-5678-cdef-a90123456789
                      name: Internal Audit Feedback
                      sender: Executive
                      difficulty: Medium
                      spoofPageType: null
                      channel: EMAIL
                      attackVector: QR_CODE_SCANNED
                    mode: RECURRING
                    status: IN_PROGRESS
                    created_date: '2025-06-01T13:19:13.402Z'
                    start_date: '2025-06-10T13:19:13.402Z'
                    end_date: '2025-08-10T13:19:13.402Z'
                    distribution_interval: TWO_WEEKS
                    recurring_interval: MONTH
                    simulations:
                    - simulation_id: c18f4e0b-5678-9abc-def0-123456789abc
                      start_date: '2025-06-10T13:19:13.402Z'
                      end_date: '2025-07-10T13:19:13.402Z'
                      status: COMPLETED
                    - simulation_id: e9a7f2d1-9999-8888-7777-9ac3
                      start_date: '2025-07-10T13:19:13.402Z'
                      end_date: '2025-08-10T13:19:13.402Z'
                      status: IN_PROGRESS
              schema:
                $ref: '#/components/schemas/PhishingCampaignDto'
          description: Successfully retrieved phishing campaign details
        '401':
          content:
            application/json:
              examples:
                Unauthorized Error:
                  description: Unauthorized Error
                  value:
                    error_code: INVALID_TOKEN
                    message: The provided authentication token is invalid or expired
                    status_code: 401
                    request_id: dcaf9f7e-6c47-4c93-bb41-0e2d8d9bb0de
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '404':
          content:
            application/json:
              examples:
                Not Found Error:
                  description: Not Found Error
                  value:
                    error_code: RESOURCE_NOT_FOUND
                    message: The requested phishing campaign was not found
                    status_code: 404
                    request_id: 2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Phishing campaign not found
        '500':
          content:
            application/json:
              examples:
                Internal Server Error:
                  description: Internal Server Error
                  value:
                    error_code: INTERNAL_SERVER_ERROR
                    message: An unexpected error occurred. Please try again later
                    status_code: 500
                    request_id: f351ac3c-cd5e-4ec7-89dc-191fc40a83f2
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: Get phishing campaign details
      tags:
      - Phishing
  /v2/phishing/campaigns/{campaignId}/simulations:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve a paginated list of simulation executions for a specific campaign'
      operationId: listCampaignSimulations
      parameters:
      - description: Campaign ID
        example: 3d65f3b0-9abc-def0-1234-56789abcdef0
        in: path
        name: campaignId
        required: true
        schema:
          type: string
      - description: Page cursor
        example: c18f4e0b-dddd-eeee-ffff-0fb2
        in: query
        name: page_after
        required: false
        schema:
          type: string
      - description: Page size
        example: 50
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          default: 50
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    simulations:
                    - simulation_id: c18f4e0b-dddd-eeee-ffff-0fb2
                      campaign_id: 3d65f3b0-aaaa-bbbb-cccc-8c1c
                      start_date: '2025-08-10T13:19:13.402Z'
                      end_date: '2025-09-10T13:19:13.402Z'
                      status: IN_PROGRESS
                      distribution_interval: TWO_WEEKS
                      scenarios:
                      - scenario_id: s-zoom-123
                        name: Zoom Deepfake
                        sender: Zoom
                        difficulty: HARD
                        spoofPageType: DEEPFAKE_SPOOF_PAGE
                        channel: EMAIL
                        attackVector: LINK_CLICKED
                    - simulation_id: e9a7f2d1-9999-8888-7777-9ac3
                      campaign_id: 3d65f3b0-aaaa-bbbb-cccc-8c1c
                      start_date: '2025-09-10T13:19:13.402Z'
                      end_date: '2025-10-10T13:19:13.402Z'
                      status: SCHEDULED
                      distribution_interval: TWO_WEEKS
                      scenarios:
                      - scenario_id: s-google-456
                        name: Google Account Compromise
                        sender: Google
                        difficulty: EASY
                        spoofPageType: LOGIN_SPOOF_PAGE
                        channel: EMAIL
                        attackVector: LINK_CLICKED
                    page_after: e9a7f2d1-9999-8888-7777-9ac3
              schema:
                $ref: '#/components/schemas/PhishingSimulationListResponseDto'
          description: Successfully retrieved simulation executions
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '404':
          content:
            application/json:
              examples:
                Not Found Error:
                  description: Not Found Error
                  value:
                    error_code: RESOURCE_NOT_FOUND
                    message: The requested campaign was not found
                    status_code: 404
                    request_id: 2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Campaign not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: List simulations for campaign
      tags:
      - Phishing
  /v2/phishing/simulations/{simulationId}:
    get:
      description: '<span style="background-color: #ff9500; color: white; padding: 2px 6px; border-radius: 3px; font-size: 10px; font-weight: bold; text-transform: uppercase; margin-right: 8px;">BETA</span>Retrieve detailed information about a specific simulation execution'
      operationId: getSimulation
      parameters:
      - description: Simulation Execution ID
        example: c18f4e0b-dddd-eeee-ffff-0fb2
        in: path
        name: simulationId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    simulation_id: c18f4e0b-5678-9abc-def0-123456789abc
                    campaign_id: 3d65f3b0-aaaa-bbbb-cccc-8c1c
                    start_date: '2025-08-10T13:19:13.402Z'
                    end_date: '2025-09-10T13:19:13.402Z'
                    status: IN_PROGRESS
                    distribution_interval: TWO_WEEKS
                    scenarios:
                    - scenario_id: s-zoom-123
                      name: Zoom Deepfake
                      sender: Zoom
                      difficulty: Hard
                      spoofPageType: DEEPFAKE_SPOOF_PAGE
                      channel: EMAIL
                      attackVector: LINK_CLICKED
              schema:
                $ref: '#/components/schemas/PhishingSimulationDto'
          description: Successfully retrieved simulation execution details
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Unauthorized - Invalid or missing authentication token
        '404':
          content:
            application/json:
              examples:
                Not Found Error:
                  description: Not Found Error
                  value:
                    error_code: RESOURCE_NOT_FOUND
                    message: The requested simulation execution was not found
                    status_code: 404
                    request_id: 2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Simulation execution not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          description: Internal server error
      summary: Get simulation execution details
      tags:
      - Phishing
components:
  schemas:
    PhishingCampaignGroupDto:
      type: object
      description: Groups associated with the phishing campaign
      properties:
        group_id:
          type: string
          description: Unique identifier for the group
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: The name of the group
          example: All Users
    PhishingCampaignScenarioDto:
      type: object
      description: Phishing campaign scenario information
      properties:
        attack_vector:
          type: string
          description: User action for the scenario
          enum:
          - LINK_CLICKED
          - TEXT_REPLIED
          - PHONE_NUMBER_CALLED
          example: LINK_CLICKED
        channel:
          type: string
          description: Notification channel for the scenario
          enum:
          - EMAIL
          - TEXT
          - INBOUND_PHONE_CALL
          example: EMAIL
        difficulty:
          type: string
          description: Difficulty level of the scenario
          enum:
          - EASY
          - MEDIUM
          - HARD
          example: HARD
        name:
          type: string
          description: Name of the phishing scenario
          example: Zoom Deepfake
        scenario_id:
          type: string
          description: Unique identifier for the scenario
          example: s-zoom-123
        sender:
          type: string
          description: Sender of the phishing email
          example: Zoom
        spoof_page_type:
          type: string
          description: Spoof page type for the scenario
          enum:
          - LOGIN_SPOOF_PAGE
          - DEEPFAKE_SPOOF_PAGE
          example: DEEPFAKE_SPOOF_PAGE
    PhishingCampaignDto:
      type: object
      description: Phishing campaign information representing the logical campaign configuration
      properties:
        campaign_id:
          type: string
          description: Unique identifier for the campaign
          example: f3c7c8f3-1234-5678-9abc-def012345678
        created_date:
          type: string
          format: date-time
          description: Campaign creation date
          example: '2025-06-01T13:19:13.402Z'
        distribution_interval:
          type: string
          description: Interval between scenario distributions within each simulation
          enum:
          - ALL_AT_ONCE
          - DAY
          - WEEK
          - TWO_WEEKS
          - MONTH
          - THREE_MONTHS
          example: TWO_WEEKS
        end_date:
          type: string
          format: date-time
          description: Campaign end date (null for indefinite campaigns)
          example: '2025-08-10T13:19:13.402Z'
        groups:
          type: array
          description: Groups associated with the campaign
          items:
            $ref: '#/components/schemas/PhishingCampaignGroupDto'
        mode:
          type: string
          description: Campaign mode
          enum:
          - SCHEDULED
          - RECURRING
          example: RECURRING
        name:
          type: string
          description: Name of the phishing campaign
          example: Quarterly Phish Test
        recurring_interval:
          type: string
          description: Interval for recurring campaigns (only present when mode = RECURRING)
          enum:
          - HOUR
          - WEEK
          - TWO_WEEKS
          - MONTH
          - THREE_MONTHS
          example: MONTH
        scenarios:
          type: array
          description: Scenarios included in the campaign
          items:
            $ref: '#/components/schemas/PhishingCampaignScenarioDto'
        simulations:
          type: array
          description: Summary list of simulation executions for this campaign
          items:
            $ref: '#/components/schemas/PhishingSimulationSummaryDto'
        start_date:
          type: string
          format: date-time
          description: Campaign start date
          example: '2025-06-10T13:19:13.402Z'
        status:
          type: string
          description: Current status of the campaign
          enum:
          - DRAFT
          - SCHEDULED
          - IN_PROGRESS
          - COMPLETED
          example: IN_PROGRESS
        target:
          type: string
          description: Target audience for the campaign
          enum:
          - ALL_USERS
          - GROUPS
          example: GROUPS
    PhishingEnrollmentDto:
      type: object
      description: Phishing enrollment details for a user in a specific simulation execution
      properties:
        campaign_id:
          type: string
          description: Campaign identifier
          example: 3d65f3b0-9abc-def0-1234-56789abcdef0
        clicked_at:
          type: string
          format: date-time
          description: When the user clicked a link in the email
          example: '2025-06-10T15:05:38.000Z'
        credentials_entered_at:
          type: string
          format: date-time
          description: When the user entered credentials
          example: '2025-06-10T15:07:38.000Z'
        deep_fake_played_at:
          type: string
          format: date-time
          description: When the user played the deep fake
          example: '2025-06-10T15:08:38.000Z'
        delivered_at:
          type: string
          format: date-time
          description: When the phishing email was delivered
          example: '2025-06-10T15:02:38.000Z'
        enrollment_id:
          type: string
          description: Unique identifier for the enrollment
          example: d0e1f2a3-b4c5-6789-defa-b01234567890
        failed_at:
          type: string
          format: date-time
          description: When the user failed the phishing test
          example: '2025-06-10T15:07:38.000Z'
        ip:
          type: string
          description: IP address from the failure condition
          example: 192.168.1.100
        ip_location:
          type: string
          description: Geographic location of the IP address
          example: Philadelphia, PA
        opened_at:
          type: string
          format: date-time
          description: When the user opened the email
          example: '2025-06-10T15:04:38.000Z'
        phone_number_called_at:
          type: string
          format: date-time
          description: When the user called the phone number
          example: '2025-06-10T15:08:38.000Z'
        qr_code_scanned_at:
          type: string
          format: date-time
          description: When the user scanned a QR code
          example: '2025-06-10T15:08:38.000Z'
        reported_at:
          type: string
          format: date-time
          description: When the user reported the phishing email
          example: '2025-06-10T15:09:38.000Z'
        scenario_id:
          type: string
          description: Scenario identifier
          example: a7b8c9d0-e1f2-3456-abcd-e78901234567
        scheduled_at:
          type: string
          format: date-time
          description: When the phishing email was scheduled to be sent
          example: '2025-06-10T15:02:38.000Z'
        simulation_id:
          type: string
          description: Simulation execution identifier
          example: c18f4e0b-5678-9abc-def0-123456789abc
        text_replied_at:
          type: string
          format: date-time
          description: When the user replied to the text message
          example: '2025-06-10T15:06:38.000Z'
        user:
          $ref: '#/components/schemas/PhishingEnrollmentUserDto'
          description: User information
    PhishingEnrollmentListResponseDto:
      type: object
      description: Paginated list of phishing enrollments
      properties:
        enrollments:
          type: array
          description: List of phishing enrollments
          items:
            $ref: '#/components/schemas/PhishingEnrollmentDto'
        page_after:
          type: string
          description: Cursor for the next page
          example: f2a3b4c5-d6e7-8901-fabc-d23456789012
    ValidationErrorResponseDto:
      type: object
      description: Error response for validation failures with field-level details
      properties:
        details:
          type: array
          description: List of field-level validation error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
        error_code:
          type: string
          description: Machine-readable error code
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: Request validation failed
        request_id:
          type: string
          description: Unique request ID for debugging
          example: 8f03bdf9-ac45-4279-8dbe-f28839c2fed3
        status_code:
          type: integer
          format: int32
          description: HTTP status code
          example: 400
      required:
      - details
      - error_code
      - message
      - request_id
      - status_code
    PhishingEnrollmentUserDto:
      type: object
      description: User information for phishing enrollment
      properties:
        email:
          type: string
          description: User's email address
          example: john.smith@example.com
        id:
          type: string
          description: Unique identifier for the user
          example: 123e4567-e89b-12d3-a456-426614174000
    PhishingSimulationListResponseDto:
      type: object
      description: Paginated list of phishing simulation executions
      properties:
        page_after:
          type: string
          description: Cursor for the next page
          example: c18f4e0b-dddd-eeee-ffff-0fb2
        simulations:
          type: array
          description: List of simulation executions
          items:
            $ref: '#/components/schemas/PhishingSimulationDto'
    PhishingCampaignListResponseDto:
      type: object
      description: Paginated list of phishing campaigns
      properties:
        campaigns:
          type: array
          description: List of phishing campaigns
          items:
            $ref: '#/components/schemas/PhishingCampaignDto'
        page_after:
          type: string
          description: Cursor for the next page
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    ErrorDetail:
      type: object
      description: Field-level validation error details
      properties:
        field:
          type: string
          description: Field name that failed validation
          example: email
        message:
          type: string
          description: Validation error message for this field
          example: Email address is not valid
      required:
      - field
      - message
    PhishingSimulationSummaryDto:
      type: object
      description: Summary information for a phishing simulation execution
      properties:
        end_date:
          type: string
          format: date-time
          description: End date of this simulation execution
          example: '2025-08-10T13:19:13.402Z'
        simulation_id:
          type: string
          description: Unique identifier for the simulation execution
          example: c18f4e0b-5678-9abc-def0-123456789abc
        start_date:
          type: string
          format: date-time
          description: Start date of this simulation execution
          example: '2025-07-10T13:19:13.402Z'
        status:
          type: string
          description: Current status of this simulation execution
          enum:
          - DRAFT
          - SCHEDULED
          - IN_PROGRESS
          - COMPLETED
          example: COMPLETED
    PhishingSimulationDto:
      type: object
      description: Detailed phishing simulation execution information
      properties:
        campaign_id:
          type: string
          description: Campaign identifier
          example: 3d65f3b0-9abc-def0-1234-56789abcdef0
        distribution_interval:
          type: string
          description: Interval between scenario distributions for this simulation
          enum:
          - ALL_AT_ONCE
          - DAY
          - WEEK
          - TWO_WEEKS
          - MONTH
          - THREE_MONTHS
          example: TWO_WEEKS
        end_date:
          type: string
          format: date-time
          description: End date of this simulation execution
          example: '2025-09-10T13:19:13.402Z'
        scenarios:
          type: array
          description: Scenarios snapshot for this specific simulation execution
          items:
            $ref: '#/components/schemas/PhishingCampaignScenarioDto'
        simulation_id:
          type: string
          description: Unique identifier for the simulation execution
          example: c18f4e0b-5678-9abc-def0-123456789abc
        start_date:
          type: string
          format: date-time
          description: Start date of this simulation execution
          example: '2025-08-10T13:19:13.402Z'
        status:
          type: string
          description: Current status of this simulation execution
          enum:
          - DRAFT
          - SCHEDULED
          - IN_PROGRESS
          - COMPLETED
          - PAUSED
          example: IN_PROGRESS
    ErrorResponseDto:
      type: object
      description: Standard error response format for all API errors
      properties:
        error_code:
          type: string
          description: Machine-readable error code
          example: RESOURCE_NOT_FOUND
        message:
          type: string
          description: Human-readable error message
          example: The requested user was not found
        request_id:
          type: string
          description: Unique request ID for debugging
          example: 8f03bdf9-ac45-4279-8dbe-f28839c2fed3
        status_code:
          type: integer
          format: int32
          description: HTTP status code
          example: 404
      required:
      - error_code
      - message
      - request_id
      - status_code
  securitySchemes:
    bearer-token:
      description: 'API authentication token obtained from the Adaptive Admin portal (Settings → API Tokens). Include the token in the Authorization header as: Bearer YOUR_TOKEN'
      scheme: bearer
      type: http