> ## Documentation Index
> Fetch the complete documentation index at: https://help.doozy.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Get introduction details

> Retrieve a specific introduction by ID, including configuration, admin users, opted-out users, and instance/match counts. Only accessible if the user is an admin of the introduction.



## OpenAPI

````yaml /openapi.json get /v1/introductions/{introductionId}
openapi: 3.0.3
info:
  title: Doozy Public API
  version: 1.0.0
  description: >-
    The Doozy Public API allows you to programmatically access your
    organization's data.


    ## Authentication


    All API requests require an API key passed in the `x-api-key` header.


    ```

    x-api-key: dzy_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    ```


    API keys can be generated and managed through the Doozy dashboard. Each key
    is associated with a user account and inherits that user's permissions.


    ## Rate Limiting


    API requests are rate limited. Rate limiting is handled by Cloudflare. If
    you exceed the rate limit, you'll receive a 429 Too Many Requests response.


    ## Pagination


    List endpoints support cursor-based pagination using `limit` and
    `starting_after` query parameters.
  contact:
    name: Doozy Support
    email: support@doozy.live
    url: https://help.doozy.live/api
servers:
  - url: https://api.doozy.live
    description: Production
security:
  - apiKey: []
tags:
  - name: Quizzes
    description: Quiz analytics and reporting endpoints
  - name: Tracks
    description: Track management and analytics endpoints
  - name: Surveys
    description: Survey and poll analytics endpoints
  - name: Introductions
    description: Doozy Roulette and Matchmaking introduction endpoints
paths:
  /v1/introductions/{introductionId}:
    get:
      tags:
        - Introductions
      summary: Get introduction details
      description: >-
        Retrieve a specific introduction by ID, including configuration, admin
        users, opted-out users, and instance/match counts. Only accessible if
        the user is an admin of the introduction.
      parameters:
        - schema:
            type: string
            description: Introduction ID
            example: intro_abc123
          required: true
          description: Introduction ID
          name: introductionId
          in: path
      responses:
        '200':
          description: Introduction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntroductionDetail'
        '401':
          description: Authentication required - missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Introduction not found or user does not have access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKey: []
components:
  schemas:
    IntroductionDetail:
      oneOf:
        - $ref: '#/components/schemas/GroupIntroductionDetail'
        - $ref: '#/components/schemas/IndividualIntroductionDetail'
      discriminator:
        propertyName: type
        mapping:
          group:
            $ref: '#/components/schemas/GroupIntroductionDetail'
          individual:
            $ref: '#/components/schemas/IndividualIntroductionDetail'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - api_error
                - authentication_error
                - invalid_request_error
                - rate_limit_error
              description: The type of error returned
              example: invalid_request_error
            code:
              type: string
              nullable: true
              description: Machine-readable error code for specific error conditions
              example: resource_not_found
            message:
              type: string
              description: Human-readable error message
              example: 'No such quiz: quiz_abc123'
            param:
              type: string
              nullable: true
              description: The parameter related to the error, if applicable
              example: id
            doc_url:
              type: string
              format: uri
              description: URL to documentation about this error
              example: https://docs.doozy.live/api/errors#resource_not_found
          required:
            - type
            - code
            - message
      required:
        - error
    GroupIntroductionDetail:
      type: object
      properties:
        object:
          type: string
          enum:
            - introduction
          description: Object type identifier
          example: introduction
        id:
          type: string
          description: Unique introduction identifier
          example: intro_abc123
        status:
          allOf:
            - $ref: '#/components/schemas/IntroductionStatus'
            - description: Current status
              example: active
        frequency:
          allOf:
            - $ref: '#/components/schemas/IntroductionFrequency'
            - description: How often introductions occur
              example: weekly
        intro_message:
          type: string
          nullable: true
          description: Custom introduction message (Markdown)
          example: '**Welcome!** _Meet your new colleague!_'
        destination:
          allOf:
            - $ref: '#/components/schemas/ActivityDestination'
            - description: Where introductions are delivered
        team_algorithm:
          allOf:
            - $ref: '#/components/schemas/TeamAlgorithm'
            - nullable: true
              description: Team matching algorithm
              example: cross_team
        seniority_algorithm:
          allOf:
            - $ref: '#/components/schemas/SeniorityAlgorithm'
            - nullable: true
              description: Seniority matching algorithm
              example: none
        location_algorithm:
          allOf:
            - $ref: '#/components/schemas/LocationAlgorithm'
            - nullable: true
              description: Location matching algorithm
              example: none
        tenure_algorithm:
          allOf:
            - $ref: '#/components/schemas/TenureAlgorithm'
            - nullable: true
              description: Tenure matching algorithm
              example: none
        created_at:
          type: string
          description: ISO 8601 creation timestamp
          example: '2024-01-15T10:30:00.000Z'
        updated_at:
          type: string
          nullable: true
          description: ISO 8601 last updated timestamp
          example: '2024-01-20T14:00:00.000Z'
        next_match_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp of the next scheduled match
          example: '2024-02-01T09:00:00.000Z'
        next_notify_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp of the next notification before match
          example: '2024-01-31T09:00:00.000Z'
        type:
          type: string
          enum:
            - group
          description: Type of introduction - group matches multiple people together
          example: group
        group_size:
          type: integer
          minimum: 2
          maximum: 4
          description: Number of people per group
          example: 2
        next_instance_id:
          type: string
          nullable: true
          description: ID of the next scheduled instance
          example: inst_def456
        remind_matches_to_meet:
          type: boolean
          nullable: true
          description: Whether to send meeting reminders
          example: true
        max_matches_per_user:
          type: integer
          nullable: true
          description: Maximum number of matches per user
          example: 1
        rounds_per_instance:
          type: integer
          nullable: true
          description: Number of introduction rounds per instance
          example: 1
        default_meeting_duration:
          type: integer
          nullable: true
          description: Default meeting duration in minutes
          example: 30
        started_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp when this was first activated
          example: '2024-01-15T10:30:00.000Z'
        end_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp when this will end
          example: null
        instance_count:
          type: integer
          description: Total number of instances
          example: 5
        total_match_count:
          type: integer
          description: Total number of matches across all instances
          example: 25
        opted_out_users:
          type: array
          items:
            $ref: '#/components/schemas/OptedOutUser'
          description: Users who have opted out of this introduction
      required:
        - object
        - id
        - status
        - frequency
        - intro_message
        - destination
        - team_algorithm
        - seniority_algorithm
        - location_algorithm
        - tenure_algorithm
        - created_at
        - updated_at
        - next_match_at
        - next_notify_at
        - type
        - group_size
        - next_instance_id
        - remind_matches_to_meet
        - max_matches_per_user
        - rounds_per_instance
        - default_meeting_duration
        - started_at
        - end_at
        - instance_count
        - total_match_count
        - opted_out_users
    IndividualIntroductionDetail:
      type: object
      properties:
        object:
          type: string
          enum:
            - introduction
          description: Object type identifier
          example: introduction
        id:
          type: string
          description: Unique introduction identifier
          example: intro_abc123
        status:
          allOf:
            - $ref: '#/components/schemas/IntroductionStatus'
            - description: Current status
              example: active
        frequency:
          allOf:
            - $ref: '#/components/schemas/IntroductionFrequency'
            - description: How often introductions occur
              example: weekly
        intro_message:
          type: string
          nullable: true
          description: Custom introduction message (Markdown)
          example: '**Welcome!** _Meet your new colleague!_'
        destination:
          allOf:
            - $ref: '#/components/schemas/ActivityDestination'
            - description: Where introductions are delivered
        team_algorithm:
          allOf:
            - $ref: '#/components/schemas/TeamAlgorithm'
            - nullable: true
              description: Team matching algorithm
              example: cross_team
        seniority_algorithm:
          allOf:
            - $ref: '#/components/schemas/SeniorityAlgorithm'
            - nullable: true
              description: Seniority matching algorithm
              example: none
        location_algorithm:
          allOf:
            - $ref: '#/components/schemas/LocationAlgorithm'
            - nullable: true
              description: Location matching algorithm
              example: none
        tenure_algorithm:
          allOf:
            - $ref: '#/components/schemas/TenureAlgorithm'
            - nullable: true
              description: Tenure matching algorithm
              example: none
        created_at:
          type: string
          description: ISO 8601 creation timestamp
          example: '2024-01-15T10:30:00.000Z'
        updated_at:
          type: string
          nullable: true
          description: ISO 8601 last updated timestamp
          example: '2024-01-20T14:00:00.000Z'
        next_match_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp of the next scheduled match
          example: '2024-02-01T09:00:00.000Z'
        next_notify_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp of the next notification before match
          example: '2024-01-31T09:00:00.000Z'
        type:
          type: string
          enum:
            - individual
          description: Type of introduction - introduces one person to others
          example: individual
        introducee:
          type: object
          nullable: true
          properties:
            user_id:
              type: string
              description: Doozy user ID of the person being introduced
              example: user_xyz789
            display_name:
              type: string
              description: Display name of the person being introduced
              example: John Doe
            email:
              type: string
              description: Email address of the person being introduced
              example: john@example.com
            slack_user_id:
              type: string
              nullable: true
              description: Slack user ID of the person being introduced
              example: U1234567890
          required:
            - user_id
            - display_name
            - email
            - slack_user_id
          description: Profile of the person being introduced
        next_instance_id:
          type: string
          nullable: true
          description: ID of the next scheduled instance
          example: inst_def456
        remind_matches_to_meet:
          type: boolean
          nullable: true
          description: Whether to send meeting reminders
          example: true
        max_matches_per_user:
          type: integer
          nullable: true
          description: Maximum number of matches per user
          example: 1
        rounds_per_instance:
          type: integer
          nullable: true
          description: Number of introduction rounds per instance
          example: 1
        default_meeting_duration:
          type: integer
          nullable: true
          description: Default meeting duration in minutes
          example: 30
        started_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp when this was first activated
          example: '2024-01-15T10:30:00.000Z'
        end_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp when this will end
          example: null
        instance_count:
          type: integer
          description: Total number of instances
          example: 5
        total_match_count:
          type: integer
          description: Total number of matches across all instances
          example: 25
        opted_out_users:
          type: array
          items:
            $ref: '#/components/schemas/OptedOutUser'
          description: Users who have opted out of this introduction
      required:
        - object
        - id
        - status
        - frequency
        - intro_message
        - destination
        - team_algorithm
        - seniority_algorithm
        - location_algorithm
        - tenure_algorithm
        - created_at
        - updated_at
        - next_match_at
        - next_notify_at
        - type
        - introducee
        - next_instance_id
        - remind_matches_to_meet
        - max_matches_per_user
        - rounds_per_instance
        - default_meeting_duration
        - started_at
        - end_at
        - instance_count
        - total_match_count
        - opted_out_users
    IntroductionStatus:
      type: string
      enum:
        - active
        - inactive
    IntroductionFrequency:
      type: string
      enum:
        - once
        - weekly
        - biweekly
        - triweekly
        - monthly
        - daily
        - quarterly
        - semiannually
        - annually
    ActivityDestination:
      oneOf:
        - $ref: '#/components/schemas/ChannelDestination'
        - $ref: '#/components/schemas/ChannelMembersDestination'
        - $ref: '#/components/schemas/GroupsDestination'
        - $ref: '#/components/schemas/IndividualsDestination'
        - $ref: '#/components/schemas/NewHiresDestination'
        - $ref: '#/components/schemas/ManagersDestination'
        - $ref: '#/components/schemas/ManagersDirectReportsDestination'
        - $ref: '#/components/schemas/ManagersAllReportsDestination'
        - $ref: '#/components/schemas/EmailsDestination'
        - $ref: '#/components/schemas/GroupDMDestination'
      discriminator:
        propertyName: type
        mapping:
          slackChannel:
            $ref: '#/components/schemas/ChannelDestination'
          slackChannelMembers:
            $ref: '#/components/schemas/ChannelMembersDestination'
          groups:
            $ref: '#/components/schemas/GroupsDestination'
          individuals:
            $ref: '#/components/schemas/IndividualsDestination'
          newHires:
            $ref: '#/components/schemas/NewHiresDestination'
          managers:
            $ref: '#/components/schemas/ManagersDestination'
          managersDirectReports:
            $ref: '#/components/schemas/ManagersDirectReportsDestination'
          managersAllReports:
            $ref: '#/components/schemas/ManagersAllReportsDestination'
          emails:
            $ref: '#/components/schemas/EmailsDestination'
          groupDM:
            $ref: '#/components/schemas/GroupDMDestination'
    TeamAlgorithm:
      type: string
      enum:
        - cross_team
        - same_team
        - random
        - slack_connect
    SeniorityAlgorithm:
      type: string
      enum:
        - similar_seniority
        - different_seniority
        - none
    LocationAlgorithm:
      type: string
      enum:
        - similar_location
        - different_location
        - none
    TenureAlgorithm:
      type: string
      enum:
        - similar_tenure
        - different_tenure
        - none
    OptedOutUser:
      type: object
      properties:
        user_id:
          type: string
          description: Doozy user ID
          example: user_abc123
        slack_user_id:
          type: string
          description: Slack user ID
          example: U1234567890
        display_name:
          type: string
          nullable: true
          description: User's display name
          example: John Doe
        email:
          type: string
          nullable: true
          description: User's email address
          example: john@example.com
      required:
        - user_id
        - slack_user_id
        - display_name
        - email
    ChannelDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - slackChannel
          description: Destination type
          example: slackChannel
        slackChannelId:
          type: string
          description: Slack channel ID
          example: C1234567890
      required:
        - type
        - slackChannelId
    ChannelMembersDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - slackChannelMembers
          description: Destination type
          example: slackChannelMembers
        slackChannelId:
          type: string
          description: Slack channel ID
          example: C1234567890
      required:
        - type
        - slackChannelId
    GroupsDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - groups
          description: Destination type
          example: groups
        groups:
          type: array
          items:
            type: string
          description: Group IDs
          example:
            - group_abc123
            - group_def456
      required:
        - type
        - groups
    IndividualsDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - individuals
          description: Destination type
          example: individuals
        slackUserIds:
          type: array
          items:
            type: string
          description: Slack user IDs
          example:
            - U1234567890
            - U0987654321
      required:
        - type
        - slackUserIds
    NewHiresDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - newHires
          description: Destination type
          example: newHires
        maxWeeksSinceJoining:
          type: number
          description: Maximum weeks since joining to be considered a new hire
          example: 4
      required:
        - type
        - maxWeeksSinceJoining
    ManagersDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - managers
          description: Destination type
          example: managers
      required:
        - type
    ManagersDirectReportsDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - managersDirectReports
          description: Destination type
          example: managersDirectReports
        doozyUserIds:
          type: array
          items:
            type: string
          description: Doozy user IDs
          example:
            - user_abc123
        slackUserIds:
          type: array
          items:
            type: string
          description: Slack user IDs
          example:
            - U1234567890
      required:
        - type
        - doozyUserIds
        - slackUserIds
    ManagersAllReportsDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - managersAllReports
          description: Destination type
          example: managersAllReports
        doozyUserIds:
          type: array
          items:
            type: string
          description: Doozy user IDs
          example:
            - user_abc123
        slackUserIds:
          type: array
          items:
            type: string
          description: Slack user IDs
          example:
            - U1234567890
      required:
        - type
        - doozyUserIds
        - slackUserIds
    EmailsDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - emails
          description: Destination type
          example: emails
        emailAddresses:
          type: array
          items:
            type: string
          description: Email addresses
          example:
            - john@example.com
            - jane@example.com
      required:
        - type
        - emailAddresses
    GroupDMDestination:
      type: object
      properties:
        type:
          type: string
          enum:
            - groupDM
          description: Destination type
          example: groupDM
        slackUserIds:
          type: array
          items:
            type: string
          description: Slack user IDs in the group DM
          example:
            - U1234567890
            - U0987654321
        slackChannelId:
          type: string
          nullable: true
          description: Slack channel ID if already created
          example: null
      required:
        - type
        - slackUserIds
        - slackChannelId
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Generate keys in the Doozy dashboard.

````