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

# Retrieve a smart group of clients

> Return one calculated smart group for a barber, including its booking rules and how membership is determined.



## OpenAPI

````yaml /api-reference/Clients/openapi.yaml get /barbers/{barberId}/smartGroups/{groupId}
openapi: 3.0.0
info:
  title: Clients
  version: 0.1.0
  contact:
    name: Guile Engineering
    url: https://www.guile.app
    email: engineering@guile.app
  license:
    name: MIT
    url: https://opensource.org/license/mit
  description: |-
    The Clients API provides operations for managing a barber's clients
    within the Guile platform.
servers:
  - url: https://api.guile.app
    variables: {}
  - url: https://guile.fly.dev
    variables: {}
security: []
tags:
  - name: Groups
    description: Smart groups and booking rules for clients
  - name: Notes
    description: Private notes a barber keeps on a client
  - name: Clients
    description: A barber client roster
paths:
  /barbers/{barberId}/smartGroups/{groupId}:
    get:
      tags:
        - Groups
      summary: Retrieve a smart group of clients
      description: >-
        Return one calculated smart group for a barber, including its booking
        rules and how membership is determined.
      operationId: getSmartGroup
      parameters:
        - name: barberId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/resourceId'
        - name: groupId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/clientGroupType'
      responses:
        '200':
          description: |-
            Ok.
            The operation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/calculatedClientGroup'
        '400':
          description: >-
            Bad Request.

            The request body, request headers, and/or query parameters are not
            well-formed.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/badRequest](https://docs.guile.app/problems/badRequest)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '401':
          description: >-
            Unauthorized.

            The operation requires authentication but no authentication or
            insufficient authentication was given.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/unauthorized](https://docs.guile.app/problems/unauthorized)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '403':
          description: >-
            Forbidden.

            The authenticated caller is not authorized to perform the requested
            operation.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/forbidden](https://docs.guile.app/problems/forbidden)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '404':
          description: >-
            Not Found.

            There is no such resource at the request URL.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/notFound](https://docs.guile.app/problems/notFound)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '422':
          description: >-
            Unprocessable Entity.

            The request body and/or query parameters were well-formed but
            otherwise invalid.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/unprocessableEntity](https://docs.guile.app/problems/unprocessableEntity)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
        '429':
          description: >-
            Too Many Requests.

            The client has sent too many requests in a given amount of time.



            This problem response may have one of the following `type` values:

            *
            [https://docs.guile.app/problems/tooManyRequests](https://docs.guile.app/problems/tooManyRequests)
          headers:
            Retry-After:
              required: true
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: uint32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/apiProblem'
      security:
        - BearerAuth: []
components:
  schemas:
    resourceId:
      type: string
      description: >-
        The unique, opaque system identifier for a resource.

        This case-sensitive ID is also used as path parameters in URLs or in
        other

        properties or parameters that reference a resource by ID rather than
        URL.
    clientGroupType:
      type: string
      enum:
        - active
        - lost
        - risky
        - new
    calculatedClientGroup:
      type: object
      required:
        - id
        - name
        - strategy
        - rules
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/clientGroupType'
          description: The unique identifier for the client group.
        name:
          type: string
          description: The human-readable name of the client group.
        strategy:
          allOf:
            - $ref: '#/components/schemas/clientGroupStrategy'
          description: The strategy for the client group.
        rules:
          allOf:
            - $ref: '#/components/schemas/clientGroupRules'
          description: The rules for this group.
      description: A client group, including clients and rules.
    apiProblem:
      type: object
      required:
        - type
        - title
        - occurredAt
        - id
        - status
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/uri'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          maxLength: 120
          description: >-
            A short, human-readable summary of the problem type. The title is
            usually the same for all

            problems with the same `type`.
        occurredAt:
          type: string
          format: date-time
          description: >-
            The date-time when this problem occurred, in [RFC
            3339](https://tools.ietf.org/html/rfc3339)

            date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived
            and immutable.
        detail:
          type: string
          maxLength: 256
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The unique identifier for this problem. This is an immutable opaque
            string.
        status:
          allOf:
            - $ref: '#/components/schemas/statusCode'
          description: >-
            The [HTTP status
            code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for
            this

            occurrence of the problem.
        instance:
          allOf:
            - $ref: '#/components/schemas/uri'
          maxLength: 2048
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. This is the URI of an

            API resource that the problem is related to, with a unique error
            correlation ID URI fragment.
        attributes:
          type: object
          additionalProperties: {}
          description: >-
            Additional optional attributes related to the problem. This data
            conforms to the schema

            associated with the error type.
        recovery:
          allOf:
            - $ref: '#/components/schemas/clientFailureRecovery'
          description: The recovery contract for this problem occurrence.
        problems:
          type: array
          items:
            $ref: '#/components/schemas/problem'
          maxItems: 128
          description: |-
            Optional root-causes if there are multiple problems in the request
            or API call processing.
      description: >-
        API problem or error response, as per

        [RFC 9457
        application/problem+json](https://tools.ietf.org/html/rfc9457).
    clientGroupStrategy:
      type: string
      enum:
        - calculated
        - manual
      description: |-
        The strategy for a client group.
        Calculated groups are automatically managed by the platform. 
        Manual groups are managed by the user.
    clientGroupRules:
      type: object
      required:
        - autoConfirm
        - requireCardOnFile
        - sameDayBookingNotice
        - bookingWindow
        - depositRequired
        - lateCancelation
        - noShowFee
        - prePaymentStrategy
      properties:
        autoConfirm:
          type: boolean
          description: Whether appointments are automatically confirmed for this group.
        requireCardOnFile:
          type: boolean
          description: Whether a card on file is required for this group.
        sameDayBookingNotice:
          type: string
          format: duration
          description: Minimum notice required for same-day bookings.
        bookingWindow:
          type: string
          format: duration
          nullable: true
          description: >-
            How far ahead of today a client in this group may book. Null means
            no

            advance limit. Counted in whole days, so `P14D` and `P14DT12H` both
            allow

            the same fourteen days, and the shortest window we accept is `P1D`.

            Calendar months and years (`P1M`, `P1Y`) are not accepted. Their
            length is

            not a fixed number of seconds.
        depositRequired:
          allOf:
            - $ref: '#/components/schemas/DepositRequirementSettings'
          description: Deposit requirements for this group.
        lateCancelation:
          allOf:
            - $ref: '#/components/schemas/LateCancelationPolicy'
          description: Late cancelation policy settings.
        noShowFee:
          allOf:
            - $ref: '#/components/schemas/FeeSettings'
          description: No-show fee policy settings.
        cardAuthorization:
          allOf:
            - $ref: '#/components/schemas/CardAuthorizationPolicy'
          description: >-
            Card authorization policy settings for this group. This is required
            when

            `prePaymentStrategy` is set to `authorization`. Guile's booking
            settings

            offer a fixed one-dollar card check or a full-subtotal hold, placed
            at the

            configured time before appointment start. The duration is the
            server-owned

            scheduling dial; if its run time has passed, authorization starts
            when the

            booking becomes confirmed.
        cardDeposit:
          allOf:
            - $ref: '#/components/schemas/CardDepositPolicy'
          description: >-
            Legacy card-deposit settings retained for compatible reads and
            writes.

            Guile treats this amount as an uncaptured authorization hold and
            never

            captures it at booking. New clients use `cardAuthorization`.
        prePaymentStrategy:
          allOf:
            - $ref: '#/components/schemas/prePaymentStrategy'
          description: |-
            The pre-payment strategy for this group. Determines how payment is
            collected or held when a client books.
      description: Rules for a client group.
    uri:
      type: string
      maxLength: 1024
      format: uri
      description: A URI reference to an internal or external resource.
    statusCode:
      type: integer
      format: uint16
      minimum: 100
      maximum: 599
      description: The HTTP status code for a response.
    clientFailureRecovery:
      type: object
      required:
        - outcome
        - retry
      properties:
        outcome:
          allOf:
            - $ref: '#/components/schemas/clientFailureOutcome'
          description: The known outcome of the request.
        retry:
          allOf:
            - $ref: '#/components/schemas/clientRetryDirective'
          description: The safe retry action for the request.
        sessionAction:
          allOf:
            - $ref: '#/components/schemas/clientSessionAction'
          description: The session action required before the request can continue.
        rateLimit:
          allOf:
            - $ref: '#/components/schemas/rateLimit'
          description: The rate limit state that prevented the request.
      description: The recovery contract for a failed client request.
    problem:
      type: object
      required:
        - type
        - title
        - occurredAt
        - id
        - status
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/uri'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          maxLength: 120
          description: >-
            A short, human-readable summary of the problem type. The title is
            usually the same for all

            problems with the same `type`.
        occurredAt:
          type: string
          format: date-time
          description: >-
            The date-time when this problem occurred, in [RFC
            3339](https://tools.ietf.org/html/rfc3339)

            date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived
            and immutable.
        detail:
          type: string
          maxLength: 256
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        id:
          allOf:
            - $ref: '#/components/schemas/resourceId'
          description: >-
            The unique identifier for this problem. This is an immutable opaque
            string.
        status:
          allOf:
            - $ref: '#/components/schemas/statusCode'
          description: >-
            The [HTTP status
            code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for
            this

            occurrence of the problem.
        instance:
          allOf:
            - $ref: '#/components/schemas/uri'
          maxLength: 2048
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem. This is the URI of an

            API resource that the problem is related to, with a unique error
            correlation ID URI fragment.
        attributes:
          type: object
          additionalProperties: {}
          description: >-
            Additional optional attributes related to the problem. This data
            conforms to the schema

            associated with the error type.
      description: >-
        Standard problem or error response, as per

        [RFC 9457
        application/problem+json](https://tools.ietf.org/html/rfc9457).
    DepositRequirementSettings:
      type: object
      required:
        - type
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/depositType'
          description: The type of deposit required.
        fixed:
          allOf:
            - $ref: '#/components/schemas/money'
          description: >-
            The amount required for a fixed deposit. This field is required if
            `type` is `fixed`.
        percentage:
          type: integer
          format: int8
          minimum: 0
          maximum: 100
          description: >-
            The percentage required for a percentage deposit. This field is
            required if `type` is `percentage`.
      description: Settings for deposit requirements for a client group.
    LateCancelationPolicy:
      type: object
      required:
        - cancellationWindow
        - fee
      properties:
        cancellationWindow:
          type: string
          format: duration
          description: Time window before appointment when cancelation is considered late.
        fee:
          allOf:
            - $ref: '#/components/schemas/FeeSettings'
          description: Fee policy for late cancelations.
      description: Late cancelation policy settings for a client group.
    FeeSettings:
      type: object
      required:
        - type
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/feeType'
          description: The type of fee.
        fixed:
          allOf:
            - $ref: '#/components/schemas/money'
          description: >-
            The amount for a fixed fee. This field is required if `type` is
            `fixed`.
        percentage:
          type: integer
          format: int8
          minimum: 0
          maximum: 100
          description: >-
            The percentage for a percentage fee. This field is required if
            `type` is `percentage`.
      description: Settings for fees for a client group.
    CardAuthorizationPolicy:
      type: object
      required:
        - appointmentOffset
        - type
      properties:
        appointmentOffset:
          type: string
          format: duration
          description: >-
            Time before appointment start when the authorization runs. A zero
            duration

            means when the booking becomes confirmed. If the configured time has

            passed, authorization starts immediately after confirmation.
        type:
          allOf:
            - $ref: '#/components/schemas/cardAuthorizationAmountType'
          description: The type of authorization amount.
        fixed:
          allOf:
            - $ref: '#/components/schemas/money'
          description: >-
            The amount for a fixed authorization. This field is required if
            `type` is `fixed`.
        percentage:
          type: integer
          format: int8
          minimum: 0
          maximum: 100
          description: >-
            The percentage for a percentage authorization. This field is
            required if `type` is `percentage` and must be a whole number.
      description: >-
        Card authorization policy settings for a client group. Booking settings
        use

        a fixed value of `1.00` for a card check or a percentage value of `100`
        for a

        full-subtotal hold.
    CardDepositPolicy:
      type: object
      required:
        - type
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/cardDepositAmountType'
          description: The type of deposit amount.
        fixed:
          allOf:
            - $ref: '#/components/schemas/money'
          description: >-
            The amount for a fixed deposit. This field is required if `type` is
            `fixed`.
        percentage:
          type: integer
          format: int8
          minimum: 0
          maximum: 100
          description: >-
            The percentage for a percentage deposit. This field is required if
            `type` is `percentage` and must be a whole number.
      description: Card deposit policy settings for a client group.
    prePaymentStrategy:
      type: string
      enum:
        - none
        - deposit
        - authorization
      description: The pre-payment strategy for a client group.
    clientFailureOutcome:
      type: string
      enum:
        - notApplied
        - unknown
      description: The known outcome of a failed client request.
    clientRetryDirective:
      type: string
      enum:
        - doNotRetry
        - retrySameRequest
        - retrySameRequestAfterDelay
      description: The safe retry action for a failed client request.
    clientSessionAction:
      type: string
      enum:
        - refresh
        - signIn
      description: The session action required before a failed request can continue.
    rateLimit:
      type: object
      required:
        - limit
        - remaining
        - resetsAt
      properties:
        limit:
          type: integer
          format: uint64
          description: The maximum number of requests allowed in the active window.
        remaining:
          type: integer
          format: uint64
          description: The number of requests remaining in the active window.
        resetsAt:
          type: string
          format: date-time
          description: >-
            The date-time when the active window resets, in [RFC
            3339](https://tools.ietf.org/html/rfc3339) date-time
            `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC.
      description: The rate limit state for the request.
    depositType:
      type: string
      enum:
        - none
        - fixed
        - percentage
      description: The type of deposit required for a client group.
    money:
      type: string
      pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
      format: decimal
      description: >-
        A monetary amount in the lowest denomination for the given currency.

        The numeric value is represented as a string so that it can be exact
        with no

        loss of precision. Values may be positive or negative.
      example: '456.78'
    feeType:
      type: string
      enum:
        - none
        - fixed
        - percentage
      description: The type of fee for a client group.
    cardAuthorizationAmountType:
      type: string
      enum:
        - fixed
        - percentage
      description: The type of card authorization amount for a client group.
    cardDepositAmountType:
      type: string
      enum:
        - fixed
        - percentage
      description: The type of card deposit amount for a client group.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````