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

# Get guest connections

> Retrieve a paginated list of guest connections for the target organization.
    #### [Authorization scenarios](/content/developer-guide/introduction/authorization#scenarios)
    | Guest | Host | Self |
    |-------|------|------|
    | ❌    | ❌   | ✅  |



## OpenAPI

````yaml /content/developer-guide/api-reference/openapi_v1.json get /guest-connections
openapi: 3.1.0
info:
  title: API - V1
  version: 1.0.0
servers:
  - url: https://api.mycreditapp.ai/v1-beta
security: []
paths:
  /guest-connections:
    get:
      tags:
        - Guest Connections
      summary: Get guest connections
      description: >-
        Retrieve a paginated list of guest connections for the target
        organization.
            #### [Authorization scenarios](/content/developer-guide/introduction/authorization#scenarios)
            | Guest | Host | Self |
            |-------|------|------|
            | ❌    | ❌   | ✅  |
      operationId: get_guest_connections_guest_connections_get
      parameters:
        - name: statuses
          in: query
          required: true
          schema:
            type: array
            uniqueItems: true
            items:
              $ref: '#/components/schemas/ConnectionStatus'
            minItems: 1
            description: Filter guest connections by their statuses
            title: Statuses
          description: Filter guest connections by their statuses
        - name: search_field
          in: query
          required: false
          schema:
            enum:
              - guest_name
              - guest_email
              - owner_email
            type: string
            description: Field to search by when providing `search_text`.
            default: guest_name
            title: Search Field
          description: Field to search by when providing `search_text`.
        - name: search_text
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
                minLength: 1
              - type: 'null'
            description: Text to search for in the selected `search_field`.
            examples:
              - Example Corp
              - corp@example.com
            title: Search Text
          description: Text to search for in the selected `search_field`.
        - name: order_by
          in: query
          required: false
          schema:
            enum:
              - guest_name
              - guest_email
              - owner_email
              - total_score
              - score_updated_at
              - created_at
              - updated_at
              - archived_at
              - active_action_updated_at
            type: string
            description: Field to sort the results by
            default: guest_name
            title: Order By
          description: Field to sort the results by
        - name: active_action_types
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/ConnectionActionType'
                minItems: 1
              - type: 'null'
            description: Filter results by active action types
            title: Active Action Types
          description: Filter results by active action types
        - name: order_dir
          in: query
          required: false
          schema:
            enum:
              - asc
              - desc
            type: string
            description: Sort direction for the `order_by` field
            default: asc
            title: Order Dir
          description: Sort direction for the `order_by` field
        - name: archived
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Filter by archived status
            title: Archived
          description: Filter by archived status
        - name: limit
          in: query
          required: true
          schema:
            type: integer
            maximum: 100
            exclusiveMinimum: 0
            description: Maximum number of results to return
            examples:
              - 10
              - 20
              - 30
            title: Limit
          description: Maximum number of results to return
        - name: offset
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
            description: Number of items to skip before returning results (for pagination)
            examples:
              - 0
              - 50
              - 75
            title: Offset
          description: Number of items to skip before returning results (for pagination)
        - name: Requester-Organization-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
            description: |

              The unique identifier of the organization making the request.
              **This ID is used to authorize the requester within the system**.
            examples:
              - 054b4106-174b-46b0-97f8-86d8d7b6f0af
            title: Requester-Organization-Id
          description: |

            The unique identifier of the organization making the request.
            **This ID is used to authorize the requester within the system**.
        - name: Target-Organization-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
            description: >

              The unique identifier of the organization that is the target of
              the request.

              The `Target-Organization-ID` may match the
              `Requester-Organization-ID` if the requester accesses their own
              resources.

              If the `Target-Organization-ID` differs from the
              `Requester-Organization-ID`, the requester can access third-party
              resources **if the requester has a connection with the target
              organization and is authorized to perform such actions**.
            examples:
              - 123e4567-e89b-12d3-a456-426614174000
            title: Target-Organization-Id
          description: >

            The unique identifier of the organization that is the target of the
            request.

            The `Target-Organization-ID` may match the
            `Requester-Organization-ID` if the requester accesses their own
            resources.

            If the `Target-Organization-ID` differs from the
            `Requester-Organization-ID`, the requester can access third-party
            resources **if the requester has a connection with the target
            organization and is authorized to perform such actions**.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestConnectionList'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                detail:
                  - loc: []
                    msg: Unsupported CRUD operation!
                    type: request
                    code: unsupported_crud_operation
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                detail:
                  - loc: []
                    msg: Token is required!
                    type: token
                    code: token_required
                  - loc: []
                    msg: The token has expired!
                    type: token
                    code: token_expired
                  - loc: []
                    msg: Invalid token!
                    type: token
                    code: invalid_token
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                detail:
                  - loc: []
                    msg: Access denied!
                    type: request
                    code: access_denied
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                detail:
                  - loc: []
                    msg: Account not found!
                    type: request
                    code: account_not_found
                  - loc: []
                    msg: Organization not found!
                    type: request
                    code: organization_not_found
              schema:
                $ref: '#/components/schemas/APIError'
        '409':
          description: Conflict
          content:
            application/json:
              example:
                detail:
                  - loc: []
                    msg: >-
                      The account is in the process of being deleted! The
                      Account's email can only be reused after its data has been
                      completely deleted. The removal process may take up to 24
                      hours.
                    type: request
                    code: account_being_deleted
                  - loc: []
                    msg: >-
                      The organization is in the process of being deleted! The
                      removal process may take up to 24 hours.
                    type: request
                    code: organization_being_deleted
              schema:
                $ref: '#/components/schemas/APIError'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                detail:
                  - loc: []
                    msg: The request is too large!
                    type: request
                    code: request_too_large
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                detail:
                  - loc:
                      - string
                      - 0
                    msg: string
                    type: string
                    code: validation_error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                detail:
                  - loc: []
                    msg: Error processing request, please try later!
                    type: try_later
                    code: internal_conflict_error
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                detail:
                  - loc: []
                    msg: Service is under maintenance, please try later!
                    type: maintanance
                    code: service_under_maintenance
      security:
        - Token: []
components:
  schemas:
    ConnectionStatus:
      type: string
      enum:
        - connected
        - disconnected
      title: ConnectionStatus
    ConnectionActionType:
      type: string
      enum:
        - analytics_request
      title: ConnectionActionType
    GuestConnectionList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GuestConnection'
          type: array
          title: Items
          description: List of guest connections returned by the query
        total_items:
          type: integer
          minimum: 0
          title: Total Items
          description: Total number of guest connections matching the query
          examples:
            - 0
            - 25
            - 100
      type: object
      required:
        - items
        - total_items
      title: GuestConnectionList
    APIError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ErrorItem'
          type: array
          title: Detail
          description: >

            List of returned errors.

            **All unsuccessful error codes except code `422` can only contain 1
            element in the list**.
      type: object
      required:
        - detail
      title: APIError
    GuestConnection:
      properties:
        host_organization_id:
          type: string
          format: uuid
          title: Host Organization Id
          description: >-
            Unique identifier of the host
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization)
          examples:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
        guest_organization_id:
          type: string
          format: uuid
          title: Guest Organization Id
          description: >-
            Unique identifier of the guest
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization)
          examples:
            - c9b1f0d1-8d3f-4cfa-91b8-9f9b0c5e2a77
        status:
          $ref: '#/components/schemas/ConnectionStatus'
          description: Current status of the guest connection
        guest_name:
          type: string
          maxLength: 300
          minLength: 1
          title: Guest Name
          description: >-
            Full name of the guest
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization)
          examples:
            - Example Corp
        guest_email:
          type: string
          maxLength: 100
          minLength: 1
          format: email
          title: Guest Email
          description: >-
            Email of the guest
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization)
            contact
          examples:
            - contact@example.com
        owner_email:
          type: string
          maxLength: 100
          minLength: 1
          format: email
          title: Owner Email
          description: >-
            Email of the host
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization)
            owner responsible for the connection
          examples:
            - owner@host.com
        total_score:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Total Score
          description: Current total score of the guest organization if calculated
          examples:
            - 87.5
            - 50.7
        score_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Score Updated At
          description: Timestamp when the total score was last updated
          examples:
            - '2025-12-12T10:30:00.123456'
        archived:
          type: boolean
          title: Archived
          description: Indicates whether the guest connection is archived
        archived_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Archived At
          description: Timestamp when the connection was archived, if applicable
          examples:
            - '2025-12-12T10:30:00.123456'
        active_action_type:
          anyOf:
            - $ref: '#/components/schemas/ConnectionActionType'
            - type: 'null'
          description: Type of the currently active action associated with the connection
        active_action_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Active Action Updated At
          description: Timestamp when the active action was last updated
          examples:
            - '2025-12-12T10:30:00.123456'
        parent_organization_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Parent Organization Id
          description: >-
            ID of the parent
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization),
            if applicable
          examples:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
        parent_organization_name:
          anyOf:
            - type: string
              maxLength: 300
              minLength: 1
            - type: 'null'
          title: Parent Organization Name
          description: >-
            Name of the parent
            [organization](https://docs.mycreditapp.ai/api-reference/organizations/get-organization),
            if applicable
          examples:
            - Example Parent Corp
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when the guest connection was created
          examples:
            - '2025-12-12T10:30:00.123456'
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Timestamp when the guest connection was last updated
          examples:
            - '2025-12-12T10:30:00.123456'
      type: object
      required:
        - host_organization_id
        - guest_organization_id
        - status
        - guest_name
        - guest_email
        - owner_email
        - archived
        - created_at
        - updated_at
      title: GuestConnection
    ErrorItem:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Loc
          description: |

            Shows the dynamic location of the current error.
            If an empty array is returned, the error is static.
          examples:
            - - body
              - date_field
              - 0
            - - header
              - Authorization
        msg:
          type: string
          title: Msg
          description: |

            A human-readable message providing more details about the error.
          examples:
            - Token is required!
            - Invalid token!
        type:
          type: string
          title: Type
          description: >

            A string indicating the type of error.

            **The list is not fixed, so it's necessary to pay attention to the
            possible type for a specific error**.
          examples:
            - token
            - request
            - try_later
        code:
          type: string
          title: Code
          description: >

            Unique text error code identifying the error.

            **The list is not fixed, so it's necessary to pay attention to the
            possible code for a specific error**.
          examples:
            - token_required
            - invalid_token
            - access_denied
      type: object
      required:
        - loc
        - msg
        - type
        - code
      title: ErrorItem
  securitySchemes:
    Token:
      type: http
      description: >-
        [Bearer
        authentication](/content/developer-guide/introduction/authentication)
        using a JWT token. Provide a valid access token. Authorization header
        format: `Authorization: Bearer <token>`.
      scheme: bearer

````