> ## 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.

# List introductions

> List all introductions (Doozy Roulette and Matchmaking) accessible to the authenticated user. Results are paginated and sorted by creation date (newest first). Supports filtering by type and status.



## OpenAPI

````yaml /openapi.json get /v1/introductions
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:
    get:
      tags:
        - Introductions
      summary: List introductions
      description: >-
        List all introductions (Doozy Roulette and Matchmaking) accessible to
        the authenticated user. Results are paginated and sorted by creation
        date (newest first). Supports filtering by type and status.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
            description: 'Maximum number of results to return (default: 25, max: 100)'
            example: 25
          required: false
          description: 'Maximum number of results to return (default: 25, max: 100)'
          name: limit
          in: query
        - schema:
            type: string
            description: Cursor for pagination
            example: intro_abc123
          required: false
          description: Cursor for pagination
          name: starting_after
          in: query
        - schema:
            type: string
            description: Cursor for pagination (backward)
          required: false
          description: Cursor for pagination (backward)
          name: ending_before
          in: query
        - schema:
            allOf:
              - $ref: '#/components/schemas/IntroductionType'
              - description: Filter by introduction type
                example: group
          required: false
          description: Filter by introduction type
          name: type
          in: query
        - schema:
            allOf:
              - $ref: '#/components/schemas/IntroductionStatus'
              - description: Filter by status
                example: active
          required: false
          description: Filter by status
          name: status
          in: query
      responses:
        '200':
          description: List of introductions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntroductionListResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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'
      security:
        - apiKey: []
components:
  schemas:
    IntroductionType:
      type: string
      enum:
        - group
        - individual
    IntroductionStatus:
      type: string
      enum:
        - active
        - inactive
    IntroductionListResponse:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: String representing the object type
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/IntroductionSummary'
          description: Array of introduction objects
        has_more:
          type: boolean
          description: Whether there are more results available beyond this page
          example: true
        url:
          type: string
          description: The URL for accessing this list endpoint
          example: /v1/introductions
        next_cursor:
          type: string
          nullable: true
          description: >-
            Cursor to fetch the next page of results. Pass as starting_after in
            subsequent requests.
          example: intro_xyz789
        previous_cursor:
          type: string
          nullable: true
          description: >-
            Cursor to fetch the previous page of results. Pass as ending_before
            in subsequent requests.
          example: intro_abc123
      required:
        - object
        - data
        - has_more
        - url
        - next_cursor
        - previous_cursor
    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
    IntroductionSummary:
      oneOf:
        - $ref: '#/components/schemas/GroupIntroductionSummary'
        - $ref: '#/components/schemas/IndividualIntroductionSummary'
      discriminator:
        propertyName: type
        mapping:
          group:
            $ref: '#/components/schemas/GroupIntroductionSummary'
          individual:
            $ref: '#/components/schemas/IndividualIntroductionSummary'
    GroupIntroductionSummary:
      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
      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
    IndividualIntroductionSummary:
      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
      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
    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
    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.

````