ClosedLoop AI Customers API

openapi: 3.2.0
info:
  title: ClosedLoop AI Public Customers API
  version: 1.8.0
  x-logo:
    url: https://app.closedloop.sh/favicon.svg
    altText: ClosedLoop AI
  description: '# ClosedLoop AI Public API


    Programmatic access to your team''s **product insights**, the structured intelligence

    ClosedLoop AI extracts from customer conversations (Gong, Fireflies, Slack, …) and

    structured feedback (surveys, webhooks).'
  contact:
    name: ClosedLoop AI Support
    email: support@closedloop.sh
    url: https://closedloop.sh
  license:
    name: Proprietary (ClosedLoop Labs LLC)
    url: https://closedloop.sh/terms
servers:
- url: https://api.closedloop.sh/v1
  description: United States (production)
- url: https://eu.api.closedloop.sh/v1
  description: European Union (production)
security:
- ApiKeyAuth: []
tags:
- name: Customers
  description: The people and accounts who gave feedback, with CRM context.
paths:
  /customers:
    get:
      tags:
      - Customers
      summary: List / search customers
      description: 'Customers who gave feedback, with CRM context (plan, ARR, active/churned) and

        **account-family** hierarchy: a parent account and its child properties.'
      parameters:
      - $ref: '#/components/parameters/Query'
      - name: is_active_customer
        in: query
        schema:
          type: boolean
        description: Filter on the tri-state customer status. true returns only confirmed active customers; false returns only accounts resolved as not active. Accounts whose status could not be resolved (is_active_customer null) are excluded by BOTH values.
      - name: parent_id
        in: query
        schema:
          type: string
          format: uuid
        description: Return the child customers under this parent account (account family).
      - name: parents_only
        in: query
        schema:
          type: boolean
        description: Return only top-level parent accounts, rolling up child properties.
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A page of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '503':
          $ref: '#/components/responses/AuthenticationUnavailable'
      operationId: getCustomers
      x-operation-id-source: derived
  /customers/{id}:
    get:
      tags:
      - Customers
      summary: Get a customer
      x-mint:
        metadata:
          description: Get one customer profile with its account summary, product insights, churn state, deals, people, and chronological activity timeline.
      description: 'Customer profile with history: their insights, churn state, deals, and a timeline.'
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Customer detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/AuthenticationUnavailable'
      operationId: getCustomersById
      x-operation-id-source: derived
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 200
      description: Page size (max 200).
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Resource UUID.
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      description: Number of records to skip.
    Query:
      name: q
      in: query
      schema:
        type: string
      description: Free-text search over titles and content.
  schemas:
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: User-safe message.
        code:
          type: string
          example: INVALID_API_KEY
        hint:
          type: string
          description: Optional next step.
    Pagination:
      type: object
      required:
      - total
      - limit
      - offset
      properties:
        total:
          type: integer
          description: Total matching records (full set, not the page).
          example: 508
        limit:
          type: integer
          example: 50
        offset:
          type: integer
          example: 0
    Customer:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
          example: c0ffee00-0000-4000-8000-000000000001
        name:
          type: string
          example: Acme Co
        parent_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Parent account (account family), if this is a child property.
        parent_name:
          type:
          - string
          - 'null'
          description: Parent account name.
        domain:
          type: string
          example: acme.com
        industry:
          type: string
          example: Hospitality
        employee_count:
          type: integer
          example: 250
        arr:
          type:
          - number
          - 'null'
          example: 48000
          description: 'Annualized recurring revenue: SUM of won-deal annual_value (team currency).'
        currency:
          type: string
          example: USD
        is_active_customer:
          type:
          - boolean
          - 'null'
          example: true
          description: Tri-state. true = a confirmed active customer; false = resolved and not an active customer; null = the account could not be resolved, so the status is unknown. Never read null as false.
        churn_state:
          type: string
          enum:
          - active
          - at_risk
          - churned
          example: active
        insight_count:
          type: integer
          example: 23
        last_seen:
          type: string
          format: date-time
          example: '2026-06-10T09:00:00Z'
  responses:
    NotFound:
      description: Resource not found (or not in your team)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found.
            code: NOT_FOUND
    AuthenticationUnavailable:
      description: API-key authentication infrastructure is temporarily unavailable
      headers:
        Retry-After:
          schema:
            type: integer
            example: 10
          description: Wait 10 seconds before retrying authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            authentication:
              summary: Authentication dependency failure
              value:
                error: API key authentication is temporarily unavailable. Please retry shortly.
                code: API_KEY_AUTH_UNAVAILABLE
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Team-scoped API key created in the app (Settings → API Keys).

        Sent as `X-API-Key: <key>` on every request. The header name `apikey`

        is also accepted as an alias.

        '
x-tagGroups:
- name: Prioritization
  tags:
  - Insights
  - Products
  - Themes
  - Features
- name: Customers & Context
  tags:
  - Customers
  - Context
  - Competitors
- name: Reporting
  tags:
  - Analytics
- name: Account
  tags:
  - Integrations
  - Usage
- name: Meta
  tags:
  - Meta