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

# List accounts and usage

> Retrieve managed firms, current resource summaries, and monthly aggregate usage.

## List managed accounts

```bash theme={null}
curl "https://spitshake.io/api/partner/v1/accounts?page=1&per_page=25" \
  -H "Authorization: Bearer $SPITSHAKE_PARTNER_KEY"
```

Accounts are ordered by numeric ID. `per_page` defaults to 25 and is capped at 100.

```json 200 theme={null}
{
  "data": [{
    "id": 412,
    "name": "Acme Legal",
    "external_id": "firm-8675309",
    "plan": "business",
    "admin_email": "admin@acme.example",
    "created_at": "2026-07-22T18:20:00Z",
    "usage_summary": {
      "users_active": 3,
      "templates_unarchived": 12,
      "submissions_this_month": 84
    }
  }],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
```

`GET /api/partner/v1/accounts/{id}` returns the same account object. An account owned by another
partner returns `404`, preventing ownership discovery.

## Monthly usage

```bash theme={null}
curl "https://spitshake.io/api/partner/v1/usage?month=2026-06" \
  -H "Authorization: Bearer $SPITSHAKE_PARTNER_KEY"
```

`month` uses `YYYY-MM` and defaults to the current month. Boundaries are UTC: `starts_at` is
inclusive and `ends_at` is exclusive. Future or malformed months return `422`.

```json 200 theme={null}
{
  "month": "2026-06",
  "period": {
    "starts_at": "2026-06-01T00:00:00Z",
    "ends_at": "2026-07-01T00:00:00Z"
  },
  "accounts": [{
    "account_id": 412,
    "name": "Acme Legal",
    "external_id": "firm-8675309",
    "submissions_created": 84,
    "submissions_completed": 78,
    "templates_total": 12,
    "users_total": 3
  }],
  "totals": {
    "submissions_created": 84,
    "submissions_completed": 78,
    "templates_total": 12,
    "users_total": 3
  }
}
```

Created and completed submission counts use their respective timestamps. Template totals exclude
archived templates and internal one-off templates, including cover-page clones. User totals include
only active users.

```json 422 theme={null}
{ "error": "month cannot be in the future" }
```


## OpenAPI

````yaml get /api/partner/v1/usage
openapi: 3.0.3
info:
  title: SpitShake API
  version: 1.0.0
  description: >
    SpitShake is a document signing and e-signature platform. This API allows
    you to

    manage templates, send documents for signing, track submissions, and
    integrate

    document signing into your applications.


    ## Authentication


    SpitShake supports the tenant authentication methods below plus an isolated
    partner credential:


    ### API Token (Recommended)

    Pass your API token in the `X-Auth-Token` header or as `Authorization:
    Bearer <token>`.

    Generate tokens at **Settings > API** with granular scopes.


    ```

    curl -H "X-Auth-Token: YOUR_TOKEN" https://your-instance.com/api/templates

    ```


    ### OAuth 2.1 (Authorization Code + PKCE)

    For connector directories and third-party agents. Discover endpoints at

    `GET /.well-known/oauth-authorization-server`. PKCE is mandatory.


    ### Session Cookie

    Automatically set when logged into the web application. Used by the
    frontend.


    ### JWT Bearer Token (Embed API only)

    For embedded forms and builders. Generate via `POST /api/embed/token`.


    ```

    curl -H "Authorization: Bearer JWT_TOKEN"
    https://your-instance.com/api/embed/submission/123

    ```


    ### Partner Bearer Key (`/api/partner/v1` only)

    Operator-issued `spk_` keys authenticate the reseller control plane. Partner
    keys and tenant

    credentials are mutually non-acceptable.


    ## Idempotency

    Create and send operations accept an `Idempotency-Key` header. A repeated

    request with the same key and body replays the original response without

    creating a duplicate. Keys expire after 24 hours.


    ## Versioning

    Tenant API responses include an `X-API-Version: v1` header. The tenant API
    is available

    at both `/api/*` and `/api/v1/*` (explicit pin). Partner responses include

    `X-API-Version: partner-v1`, and that control plane is separately pinned at

    `/api/partner/v1/*`.


    ## Pagination


    List endpoints use cursor-based pagination:


    | Parameter | Type | Description |

    |-----------|------|-------------|

    | `limit` | integer | Items per page (1-100, default 10) |

    | `after` | integer | Return items after this ID |

    | `before` | integer | Return items before this ID |


    Response includes a `pagination` object:

    ```json

    {
      "data": [...],
      "pagination": {
        "count": 10,
        "next": 456,
        "prev": 123
      }
    }

    ```


    Use `pagination.next` as the `after` parameter to get the next page.


    ## Rate Limits


    API requests are limited to 120 requests per minute per API token.

    Partner API requests are limited to 100 requests per minute per partner key.


    ## Errors


    All errors return a JSON object with an `error` field:


    ```json

    { "error": "Not found" }

    ```


    | Status | Meaning |

    |--------|---------|

    | 400 | Bad request - invalid parameters |

    | 401 | Unauthorized - invalid or missing authentication |

    | 403 | Forbidden - insufficient permissions or plan limits exceeded |

    | 404 | Not found |

    | 422 | Unprocessable entity - validation errors |

    | 500 | Internal server error (includes `detail` field with exception
    message for debugging) |


    ## Plan Limits


    Some endpoints require specific subscription plans. If your plan doesn't
    support an endpoint,

    you'll receive a 403 response with an `upgrade_url` field.
  contact:
    name: SpitShake Support
    url: https://spitshake.io
  license:
    name: Proprietary
servers:
  - url: /
    description: Current instance
security:
  - ApiToken: []
  - SessionCookie: []
tags:
  - name: Templates
    description: Manage document templates with fields, submitters, and documents
  - name: Submissions
    description: Create and manage document signing submissions
  - name: Submitters
    description: Manage individual submitters (signers) within submissions
  - name: Users
    description: Manage account users and team members
  - name: Access Tokens
    description: Manage API tokens for programmatic access (requires Pro plan)
  - name: Webhooks
    description: Configure webhook endpoints for event notifications (requires Pro plan)
  - name: Settings
    description: Account settings, SMTP, storage, certificates, and email configuration
  - name: Audit Events
    description: View audit log of account activities (requires Pro plan)
  - name: Subscriptions
    description: View current plan, usage, and manage billing
  - name: Plans
    description: List available subscription plans (public)
  - name: Payments
    description: Process payments within signing flows via Stripe
  - name: Verification
    description: SMS OTP phone verification for signing sessions
  - name: KBA
    description: Knowledge-Based Authentication for identity verification
  - name: AI
    description: AI-powered document analysis and field detection
  - name: Embed
    description: Embed signing forms and template builders in your application
  - name: Custom Domains
    description: >-
      Manage custom signing domains with automatic SSL provisioning via
      Cloudflare
  - name: Teams
    description: Team management and template access control
  - name: Health
    description: System health check endpoints (public)
  - name: MFA
    description: Multi-Factor Authentication setup, management, and verification
  - name: BAA
    description: Business Associate Agreement acceptance and management (HIPAA)
  - name: Security Events
    description: Security event monitoring and breach detection dashboard (admin only)
  - name: Thumbnails
    description: Template document thumbnail generation and retrieval
  - name: Partner API
    description: >-
      Versioned reseller control plane for provisioning and metering isolated
      tenant accounts
paths:
  /api/partner/v1/usage:
    get:
      tags:
        - Partner API
      summary: Get monthly partner usage
      description: >
        Uses inclusive UTC month starts and exclusive UTC month ends. Submission
        creation and

        completion are counted by their respective timestamps. Template totals
        exclude archived

        and one-off templates; user totals include active users only.
      operationId: getPartnerUsage
      parameters:
        - name: month
          in: query
          schema:
            type: string
            pattern: ^\d{4}-(0[1-9]|1[0-2])$
          description: Defaults to the current UTC month. Future months are rejected.
      responses:
        '200':
          description: Per-account and aggregate usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerMonthlyUsageResponse'
              example:
                month: 2026-06
                period:
                  starts_at: '2026-06-01T00:00:00Z'
                  ends_at: '2026-07-01T00:00:00Z'
                accounts:
                  - account_id: 412
                    name: Acme Legal
                    external_id: firm-8675309
                    submissions_created: 84
                    submissions_completed: 78
                    templates_total: 12
                    users_total: 3
                totals:
                  submissions_created: 84
                  submissions_completed: 78
                  templates_total: 12
                  users_total: 3
        '401':
          description: Missing or unknown partner key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
        '403':
          description: Partner is suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Partner access is suspended
        '422':
          description: Month is malformed or in the future
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: month cannot be in the future
        '429':
          description: Partner key exceeded 100 requests per minute
      security:
        - PartnerBearer: []
components:
  schemas:
    PartnerMonthlyUsageResponse:
      type: object
      required:
        - month
        - period
        - accounts
        - totals
      properties:
        month:
          type: string
          pattern: ^\d{4}-(0[1-9]|1[0-2])$
        period:
          type: object
          required:
            - starts_at
            - ends_at
          properties:
            starts_at:
              type: string
              format: date-time
            ends_at:
              type: string
              format: date-time
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/PartnerMonthlyUsageRow'
        totals:
          type: object
          required:
            - submissions_created
            - submissions_completed
            - templates_total
            - users_total
          properties:
            submissions_created:
              type: integer
            submissions_completed:
              type: integer
            templates_total:
              type: integer
            users_total:
              type: integer
    Error:
      type: object
      properties:
        error:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
    PartnerMonthlyUsageRow:
      type: object
      required:
        - account_id
        - name
        - external_id
        - submissions_created
        - submissions_completed
        - templates_total
        - users_total
      properties:
        account_id:
          type: integer
        name:
          type: string
        external_id:
          type: string
          nullable: true
        submissions_created:
          type: integer
        submissions_completed:
          type: integer
        templates_total:
          type: integer
        users_total:
          type: integer
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: API token generated at Settings > API
    SessionCookie:
      type: apiKey
      in: cookie
      name: _docutrust_session
      description: Session cookie (automatic when logged in)
    PartnerBearer:
      type: http
      scheme: bearer
      bearerFormat: spk_
      description: Operator-issued partner key. Accepted only under /api/partner/v1.

````