ClickFunnels Communities::Memberships::Ban Action API

openapi: 3.2.0
info:
  title: ClickFunnels Communities::Memberships::Ban Action API
  termsOfService: https://www.clickfunnels.com/terms-of-service
  contact:
    name: ClickFunnels API Team
    url: https://developers.myclickfunnels.com
  x-logo:
    url: https://statics.myclickfunnels.com/image/1126065/file/31edf05760fafe41a82f16a668ab251f.png
  description: 'The ClickFunnels REST API that powers webhooks, native integrations, and Zapier lets you manage your ClickFunnels data, automate your workflows, and recreate ClickFunnels functionality in your own apps.


    ### For AI agents


    This document is the catalogue: every operation ClickFunnels exposes over REST is described here, with a unique operationId, typed schemas, and the scopes it needs. It is served from `/openapi.json`, `/openapi.yaml`, `/api/openapi.{json,yaml}`, and `/api/v2/openapi.{json,yaml}` on the accounts host.


    Three things it does not describe, each one request away:


    - MCP server: the app-native Model Context Protocol server (Streamable HTTP, OAuth 2.1 with PKCE). Prefer it over raw REST when your client supports MCP - it describes itself at runtime.

    - Skill guides, also as an Agent Skills index: one task guide per job (pages, blogs, products, orders, workflows, emails, courses, stats, external SDK pages). Read the guide that matches your job before your first write. llms.txt covers when to use ClickFunnels at all, how to get credentials, and how to behave around rate limits.

    - Protected resource metadata (RFC 9728) and authorization server metadata (RFC 8414): the scope vocabulary and the OAuth endpoints. Dynamic client registration is for MCP clients only.


    On ClickFunnels-owned API hosts (`myclickfunnels.com` and its subdomains), the OpenAPI specification responses and API authentication failures (401, or 403 for insufficient scope) carry those links in an RFC 8288 `Link` header, so clients can discover the documentation and authentication metadata from those responses. Requests sent through a customer''s custom domain keep the Bearer challenge but omit those discovery pointers.'
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 2.0.0
servers:
- url: https://{subdomain}.myclickfunnels.com/api/v2
  description: ClickFunnels API
  variables:
    subdomain:
      default: myworkspace
security:
- BearerAuth: []
- OAuth2: []
tags:
- name: Communities::Memberships::BanAction
  description: '> Async bulk action that bans multiple community members in the background.


    Creating a BanAction enqueues a background job and immediately returns an action record. Poll the `show` endpoint using the returned `id` and check the `status` field (`queued` → `processing` → `completed`) to track progress.'
paths:
  /communities/{community_id}/memberships/ban_actions:
    post:
      tags:
      - Communities::Memberships::BanAction
      summary: Create Membership Ban Action
      description: 'Enqueue an async background job to ban one or more community members. The action record is returned immediately with `status: queued`. Poll `GET /communities/memberships/ban_actions/{id}` until `status` is `completed`.'
      operationId: createCommunitiesMembershipsBanActions
      parameters:
      - name: community_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: Parameters for the ban action
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                communities_memberships_ban_action:
                  type: object
                  $ref: '#/components/schemas/CommunitiesMembershipsBanActionParameters'
            example:
              communities_memberships_ban_action:
                target_all: false
                target_ids:
                - AbCdEf
                - GhIjKl
                reason: Violated community guidelines
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunitiesMembershipsBanActionAttributes'
              example:
                id: 501
                public_id: BnAcT1
                community_id: 1
                target_all: false
                target_ids:
                - 101
                - 102
                failed_ids: []
                target_count: null
                performed_count: 0
                started_at: null
                completed_at: null
                created_at: '2025-01-01T00:00:00.000Z'
                updated_at: '2025-01-01T00:00:00.000Z'
                status: queued
                reason: Violated community guidelines
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: API key missing or invalid
                hint: 'Send the token as `Authorization: Bearer <token>`. Create one under Account > Team > Platform Applications (a workspace API key), or obtain one with OAuth 2.1; both use the same scopes. See https://developers.myclickfunnels.com/docs/authentication, or append .md to that URL for markdown.'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: Reason is too long (maximum is 1024 characters)
                hint: null
        '403':
          $ref: '#/components/responses/WorkspaceGrantForbidden'
  /communities/memberships/ban_actions/{id}:
    get:
      tags:
      - Communities::Memberships::BanAction
      summary: Fetch Membership Ban Action
      description: Retrieve the current status of a membership ban action. Poll this endpoint until `status` is `completed`.
      operationId: getCommunitiesMembershipsBanActions
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunitiesMembershipsBanActionAttributes'
              example:
                id: 501
                public_id: BnAcT1
                community_id: 1
                target_all: false
                target_ids:
                - 101
                - 102
                failed_ids: []
                target_count: 2
                performed_count: 2
                started_at: '2025-01-01T00:01:00.000Z'
                completed_at: '2025-01-01T00:01:05.000Z'
                created_at: '2025-01-01T00:00:00.000Z'
                updated_at: '2025-01-01T00:01:05.000Z'
                status: completed
                reason: Violated community guidelines
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: API key missing or invalid
                hint: 'Send the token as `Authorization: Bearer <token>`. Create one under Account > Team > Platform Applications (a workspace API key), or obtain one with OAuth 2.1; both use the same scopes. See https://developers.myclickfunnels.com/docs/authentication, or append .md to that URL for markdown.'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: 'Not found: Record missing'
                hint: null
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    WorkspaceGrantForbidden:
      description: "Forbidden — this request's workspace is closed to it.\n\nThree cases return this:\n\n* The access token is limited to specific workspaces (see the workspace selection made when\n  the key was provisioned, or the workspaces approved on the OAuth consent screen) and the\n  request acts on a workspace outside that set.\n* The access token is limited to specific workspaces and the request's workspace could not be\n  determined at all. The gate is fail-closed, so a workspace-limited token is denied rather\n  than allowed through when the target workspace is ambiguous.\n* The workspace's team has no active ClickFunnels subscription: it was canceled, is paused,\n  or is locked out after failed payments. Reads and writes are both refused until the\n  subscription is reactivated, and the body carries `\"code\": \"subscription_inactive\"`.\n\nA token with no workspace restriction never receives the first two."
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                description: A machine-readable cause, when there is one. `subscription_inactive` means the workspace's team has no active ClickFunnels subscription.
                enum:
                - subscription_inactive
              hint:
                type:
                - string
                - 'null'
                description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
          examples:
            workspace_not_granted:
              summary: Token not granted this workspace
              value:
                error: 'Forbidden: This access token is limited to specific workspaces and was not granted access to this one.'
                hint: The token's workspace grant was chosen when it was provisioned (Platform Applications) or on the OAuth consent screen. Use GET /api/v2/teams/{team_id}/workspaces to list the workspaces this token can reach (GET /api/v2/teams lists the team ids).
            subscription_inactive:
              summary: Team subscription inactive
              value:
                error: 'Forbidden: This workspace''s team does not have an active ClickFunnels subscription, so API access to it is disabled until the subscription is reactivated.'
                hint: null
                code: subscription_inactive
  schemas:
    CommunitiesMembershipsBanActionAttributes:
      type: object
      title: Communities::Memberships::BanAction
      description: Communities::Memberships::BanAction
      allOf:
      - $ref: '#/components/schemas/CommunitiesActionAttributes'
      - type: object
        properties:
          reason:
            type:
            - string
            - 'null'
            description: Optional reason applied to each ban created by this action
      example:
        id: 501
        public_id: BnAcT1
        community_id: 1
        target_all: false
        target_ids:
        - 101
        - 102
        failed_ids: []
        target_count: 2
        performed_count: 2
        started_at: '2025-01-01T00:01:00.000Z'
        completed_at: '2025-01-01T00:01:05.000Z'
        created_at: '2025-01-01T00:00:00.000Z'
        updated_at: '2025-01-01T00:01:05.000Z'
        status: completed
        reason: Violated community guidelines
    CommunitiesActionAttributes:
      type: object
      title: Async Action
      description: 'Base response shape shared by all community async bulk-action resources. The `status` field progresses from `queued` → `processing` → `completed`. Poll the `show` endpoint until `status` is `completed` or `performed_count` equals `target_count`.

        '
      properties:
        id:
          type: integer
          description: Action ID
        public_id:
          type:
          - string
          - 'null'
          description: Action public ID
        community_id:
          type: integer
          description: ID of the Community this action belongs to
        target_all:
          type: boolean
          description: When true the action targets all eligible records in the community rather than the explicit target_ids list
        target_ids:
          type: array
          description: Integer IDs of the targeted records (memberships or bans)
          items:
            type: integer
        failed_ids:
          type: array
          description: Integer IDs of records that could not be processed
          items:
            type: integer
        target_count:
          type:
          - integer
          - 'null'
          description: Total number of records that will be processed
        performed_count:
          type:
          - integer
          - 'null'
          description: Number of records processed so far
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the background job began processing
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the background job finished
        created_at:
          type: string
          format: date-time
          description: Created at
        updated_at:
          type: string
          format: date-time
          description: Updated at
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          description: 'Current status of the async action. Progresses: queued → processing → completed.'
    CommunitiesMembershipsBanActionParameters:
      type: object
      title: Communities::Memberships::BanAction
      description: Communities::Memberships::BanAction
      properties:
        target_all:
          type: boolean
          description: When true, ban all members in the community (target_ids is ignored)
        target_ids:
          type: array
          description: Array of membership public IDs to ban. Required when target_all is false.
          items:
            type: string
        reason:
          type:
          - string
          - 'null'
          description: Optional reason applied to each ban
      example:
        communities_memberships_ban_action:
          target_all: false
          target_ids:
          - AbCdEf
          - GhIjKl
          reason: Violated community guidelines
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'A workspace API key or an OAuth access token, sent as `Authorization: Bearer <token>`.


        Both carry the same scope vocabulary as the `OAuth2` scheme below. Category-only

        scopes restrict access to the categories they name. Coarse wildcards remain additive:

        `read contacts:read` reads every category, while `write contacts:read` can write every

        category. Omit coarse scopes when restricting access to specific categories.

        Legacy tokens with only coarse scopes retain their existing unrestricted access;

        a bare `read` scope alone does not enforce read-only access.

        '
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 authorization code flow for REST integrations. Create a Platform Application

        and follow `https://developers.myclickfunnels.com/docs/oauth-20` to connect users.

        Authorization server metadata is published at

        `https://accounts.myclickfunnels.com/.well-known/oauth-authorization-server`.

        Dynamic client registration at `/oauth/register` is for MCP clients only; MCP-scoped

        tokens must use `https://agents.myclickfunnels.com/mcp`, not the REST API.


        Scopes are least-privilege by category. Ask for the two coarse wildcards (`read`,

        `write`) only when an integration genuinely needs the whole workspace; otherwise ask

        for the `<category>:read` / `<category>:write` pairs you use. `write` implies `read`

        for the same category. Protected resource metadata (RFC 9728) for this API lives at

        `https://accounts.myclickfunnels.com/.well-known/oauth-protected-resource`.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.myclickfunnels.com/oauth/authorize
          tokenUrl: https://accounts.myclickfunnels.com/oauth/token
          refreshUrl: https://accounts.myclickfunnels.com/oauth/token
          scopes:
            read: Read any resource in the granted workspaces
            write: Read and write any resource in the granted workspaces
            contacts:read: Read Contacts
            contacts:write: Read and write Contacts
            workflows:read: Read Workflows (Automations)
            workflows:write: Read and write Workflows (Automations)
            funnels:read: Read Funnels
            funnels:write: Read and write Funnels
            sites:read: Read Sites & Design
            sites:write: Read and write Sites & Design
            courses:read: Read Courses
            courses:write: Read and write Courses
            emails:read: Read Emails
            emails:write: Read and write Emails
            blog:read: Read Blog
            blog:write: Read and write Blog
            community:read: Read Community
            community:write: Read and write Community
            appointments:read: Read Appointments
            appointments:write: Read and write Appointments
            opportunities:read: Read Opportunities
            opportunities:write: Read and write Opportunities
            store:read: Read Store
            store:write: Read and write Store
            forms:read: Read Forms
            forms:write: Read and write Forms
            media:read: Read Media
            media:write: Read and write Media
            webhooks:read: Read Webhooks
            webhooks:write: Read and write Webhooks
            account:read: Read Account
            account:write: Read and write Account
            reference:read: Read Reference Data
            reference:write: Read and write Reference Data
externalDocs:
  description: More in-depth guides and further resources
  url: https://developers.myclickfunnels.com
x-provenance:
  method: harvested
  publisher: ClickFunnels
  source: https://accounts.myclickfunnels.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)