Doppel hrm API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Doppel Hrm API
  description: APIs to interface with Doppel's core system for social engineering defense — Brand Protection alerts, URL scanning, reports, protected assets, and Human Risk Management campaigns.
  contact:
    name: Doppel API Support
    url: https://doppel.readme.io/
servers:
- url: https://api.doppel.com/v1
tags:
- name: hrm
paths:
  /hrm/campaigns:
    get:
      description: List phishing simulation campaigns for the authenticated organization. Supports filtering by status, campaign type, date range, and test flag. Returns paginated results.
      summary: List Campaigns
      operationId: list-hrm-campaigns
      tags:
      - hrm
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: status
        in: query
        description: Filter by campaign status (e.g. pending, in_progress, finished)
        schema:
          type: string
      - name: campaign_type
        in: query
        description: Filter by campaign type (e.g. simulation)
        schema:
          type: string
      - name: launch_date_after
        in: query
        description: Filter campaigns launched after this ISO 8601 date
        schema:
          type: string
      - name: launch_date_before
        in: query
        description: Filter campaigns launched before this ISO 8601 date
        schema:
          type: string
      - name: is_test
        in: query
        description: Include test campaigns (defaults to false)
        schema:
          type: boolean
          default: false
      - name: sort_by
        in: query
        description: 'Sort field: launch_date, created_at, or name'
        schema:
          type: string
          default: created_at
      - name: sort_order
        in: query
        description: 'Sort order: asc or desc'
        schema:
          type: string
          default: desc
      - name: limit
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - name: offset
        in: query
        description: Number of results to skip for pagination
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: List of campaigns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCampaignsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
  /hrm/campaigns/{campaign_id}:
    get:
      description: Get a single phishing simulation campaign by ID for the authenticated organization.
      summary: Get Campaign
      operationId: get-hrm-campaign
      tags:
      - hrm
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: campaign_id
        in: path
        required: true
        description: Campaign ID
        schema:
          type: string
      responses:
        '200':
          description: Campaign details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HrmCampaignResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
  /hrm/events:
    get:
      description: List phishing simulation user events (observations) for the authenticated organization. Events track user interactions with phishing campaigns such as email opens, link clicks, data submissions, and reports. Includes joined user context (name, department, email) in each event. Supports filtering by campaign, action type, user attributes, and date range.
      summary: List Events
      operationId: list-hrm-events
      tags:
      - hrm
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: campaign_id
        in: query
        description: Filter events by campaign ID
        schema:
          type: string
      - name: action
        in: query
        description: Filter by event type (e.g. email_opened, link_visited, data_submitted, email_reported)
        schema:
          type: string
      - name: sim_user_id
        in: query
        description: Filter events by sim user ID
        schema:
          type: string
      - name: department
        in: query
        description: Filter events by user department
        schema:
          type: string
      - name: manager_email
        in: query
        description: Filter events by user manager email
        schema:
          type: string
      - name: country
        in: query
        description: Filter events by user country
        schema:
          type: string
      - name: date_after
        in: query
        description: Filter events created after this ISO 8601 date
        schema:
          type: string
      - name: date_before
        in: query
        description: Filter events created before this ISO 8601 date
        schema:
          type: string
      - name: sort_by
        in: query
        description: 'Sort field: created_at'
        schema:
          type: string
          default: created_at
      - name: sort_order
        in: query
        description: 'Sort order: asc or desc'
        schema:
          type: string
          default: desc
      - name: limit
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - name: offset
        in: query
        description: Number of results to skip for pagination
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: List of events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
webhooks:
  hrm_event:
    post:
      operationId: hrm_event
      summary: HRM Campaign Event
      description: 'This webhook is fired when a Human Risk Management (HRM) phishing simulation campaign engagement event is recorded. Events include attack delivery (email_sent), target interactions (email_opened, link_visited, data_submitted), training outcomes (training_accessed, quiz_passed, quiz_failed), reporting (email_reported), voice call results (call_answered, call_missed), and voice behavior analysis labels (refusal, disclosure_full, security_escalation, etc.).

        '
      tags:
      - hrm
      requestBody:
        description: 'Information about the HRM campaign engagement event, including the action type, campaign and user identifiers, and optional context like attack vector and device type. For Splunk integrations, this payload is wrapped in a Splunk HEC envelope with sourcetype "doppel_hrm_events".

          '
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Top-level webhook payload, containing the event type and the event-specific payload.
              required:
              - event_type
              - timestamp
              - payload
              properties:
                event_type:
                  type: string
                  description: The type of event that occurred.
                  enum:
                  - hrm_event
                timestamp:
                  type: string
                  format: date-time
                  description: Timestamp of when the event was recorded.
                  example: '2026-03-12T17:15:00.123456'
                payload:
                  $ref: '#/components/schemas/HrmEventPayload'
      responses:
        '201':
          description: Webhook notification received successfully, and acted upon synchronously.
        '202':
          description: Webhook notification received successfully, but will be acted upon asynchronously.
        '400':
          description: Invalid payload received.
components:
  schemas:
    HrmEventResponse:
      type: object
      required:
      - id
      - campaign_id
      - action
      properties:
        id:
          type: string
          description: Event ID
        campaign_id:
          type: string
          description: Campaign ID this event belongs to
        action:
          type: string
          description: Event type (e.g. email_opened, link_visited, data_submitted, email_reported)
        created_at:
          type: string
          description: ISO 8601 timestamp
        sim_user_id:
          type: string
          description: Sim user ID
        user_email:
          type: string
          description: User email address
        user_first_name:
          type: string
          description: User first name
        user_last_name:
          type: string
          description: User last name
        department:
          type: string
          description: User department
        manager_email:
          type: string
          description: User manager email address
        country:
          type: string
          description: User country
        device_type:
          type: string
          description: Device type (e.g. desktop, mobile)
        source:
          type: string
          description: Event source
    HrmEventPayload:
      type: object
      description: Payload type for the "HRM Event" webhook. Fired when a phishing simulation campaign engagement event is recorded (e.g., a target opens an attack email, clicks a link, submits data, completes training, or answers a vishing call).
      required:
      - action
      - campaign_id
      properties:
        action:
          type: string
          description: 'The engagement action that was recorded. Values come from the SimCampaignActions enum (e.g., email_opened, link_visited, data_submitted, quiz_passed) or voice behavior labels (e.g., refusal, disclosure_full, security_escalation).

            '
          example: link_visited
        campaign_id:
          type: string
          format: uuid
          description: ID of the phishing simulation campaign.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        sim_user_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the simulated user (target) who performed the action.
          example: 12345678-abcd-ef01-2345-6789abcdef01
        sim_attack_instance_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the specific attack instance (email, SMS, voice call, etc.) the action relates to.
          example: abcdef01-2345-6789-abcd-ef0123456789
        source:
          type: string
          nullable: true
          description: Attack vector or source context (e.g., "qr_code", "link", "voice_followup_email", "voice_followup_sms").
          example: link
        device_type:
          type: string
          nullable: true
          description: Device type of the target user when the action was recorded.
          enum:
          - Desktop
          - Mobile
          - Tablet
          example: Mobile
    ListEventsResponse:
      type: object
      required:
      - data
      - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/HrmEventResponse'
        count:
          type: integer
          description: Total number of matching events
    ErrorResponse:
      title: ErrorResponse
      description: Standard error response returned for all non-2xx responses. Contains a single `message` field with a human-readable error description.
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error description.
          example: This is an error message
    HrmCampaignResponse:
      type: object
      required:
      - id
      - name
      - status
      - campaign_type
      - is_test
      properties:
        id:
          type: string
          description: Campaign ID
        name:
          type: string
          description: Campaign name
        status:
          type: string
          description: Campaign status (e.g. pending, in_progress, finished)
        campaign_type:
          type: string
          description: Campaign type (e.g. simulation)
        launch_date:
          type: string
          description: ISO 8601 launch date
        end_date:
          type: string
          description: ISO 8601 end date
        created_at:
          type: string
          description: ISO 8601 creation timestamp
        is_test:
          type: boolean
          description: Whether this is a test campaign
    ListCampaignsResponse:
      type: object
      required:
      - data
      - count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/HrmCampaignResponse'
        count:
          type: integer
          description: Total number of matching campaigns
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
      description: API key from Doppel Vision API settings. Required for gateway authentication and quota.
    user_api_key:
      type: apiKey
      name: x-user-api-key
      in: header
      description: User API key from Doppel Vision API settings. Required together with x-api-key for authenticated requests.
x-readme:
  parameter-ordering:
  - path
  - header
  - query
  - body
  - cookie
  - form