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

# Create Activity

> Log a new activity for a contact.



## OpenAPI

````yaml POST /v1/activities
openapi: 3.0.3
info:
  title: v1.0
  description: >
    ## Authentication


    All API requests require authentication via API key in the `Authorization`
    header with Bearer scheme:


    ```bash

    curl -H "Authorization: Bearer your_api_key_here"
    https://api.clientcommander.com/v1/people

    ```


    Generate API keys from **Settings > API Keys** in your Client Commander
    dashboard.


    ## Rate Limiting


    API requests are rate-limited to ensure system stability:


    - **Rate Limit:** 1000 requests per hour per API key

    - **Headers:** Every response includes rate limit information


    ```

    X-RateLimit-Limit: 1000

    X-RateLimit-Remaining: 999

    X-RateLimit-Reset: 1640995200

    ```


    When rate limit is exceeded, you'll receive a `429 Too Many Requests`
    response with a `Retry-After` header.


    ## Pagination


    List endpoints support pagination with consistent parameters:


    - `limit`: Number of items per page (default: 10, max: 100)

    - `cursor`: Opaque cursor for next page (returned in response)


    Response includes pagination metadata:


    ```json

    {
      "data": [...],
      "meta": {
        "count": 10,
        "hasMore": true,
        "nextCursor": "eyJpZCI6IjEyMyJ9"
      }
    }

    ```


    ## Error Handling


    Errors follow a consistent structure with machine-readable codes:


    ```json

    {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid email address",
        "details": [
          {
            "field": "email",
            "message": "Must be a valid email address",
            "code": "INVALID_FORMAT"
          }
        ],
        "requestId": "req_abc123",
        "timestamp": "2023-11-15T10:00:00Z"
      }
    }

    ```



    ## Idempotency


    POST and PUT requests support idempotency via the `Idempotency-Key` header:


    ```bash

    curl -X POST -H "Idempotency-Key: unique-key-123" ...

    ```


    ## Versioning


    - **Current Version:** v1

    - **Version Header:** `X-API-Version: 1` (optional)

    - **Deprecation Policy:** 12 months notice before sunset


    ## Support


    - **Documentation:** https://docs.clientcommander.com

    - **Status Page:** https://status.clientcommander.com

    - **Support:** support@clientcommander.me
  version: 1.0.0
  contact:
    name: Client Commander API Support
    email: api@clientcommander.me
    url: https://clientcommander.com/support
  license:
    name: Proprietary
    url: https://clientcommander.com/terms
servers:
  - url: https://api.clientcommander.com
    description: Production API
    variables: {}
security:
  - Authentication: []
tags:
  - name: People
    description: >
      Contact management endpoints. Create, read, update, and delete contacts
      with rich profile data including emails, phones, addresses, custom fields,
      and lifecycle stages.


      **Permissions:** Requires `people.view.*` and `people.edit.*` scopes based
      on operation.
  - name: Tasks
    description: >
      Task management for contact follow-ups and to-dos. Supports due dates,
      priorities, and assignment to team members.


      **Permissions:** Requires `tasks.manage` scope.
  - name: Deals
    description: >
      Deal pipeline management with customizable stages. Track opportunities,
      revenue, and close dates.


      **Permissions:** Requires `deals.view.*` and `deals.manage` scopes.
  - name: Appointments
    description: >
      Calendar and appointment scheduling. Supports recurring appointments,
      timezones, and guest management.


      **Permissions:** Requires `appointments.manage` scope.
  - name: Activities
    description: >
      Activity logging and interaction history. Track calls, emails, meetings,
      and custom activities.


      **Permissions:** Requires `activities.view` and `activities.create`
      scopes.
  - name: Tags
    description: |
      Tag management for contact categorization and segmentation.

      **Permissions:** Requires `tags.manage` scope.
  - name: Stages
    description: |
      Contact lifecycle stage management (Lead, Prospect, Client, etc.).

      **Permissions:** Requires `stages.manage` scope (Owner/Admin only).
  - name: Pipelines
    description: |
      Deal pipeline configuration and stage management.

      **Permissions:** Requires `pipelines.manage` scope.
  - name: Users
    description: |
      User and agent information endpoints.

      **Permissions:** Requires `users.view` scope.
  - name: Teams
    description: |
      Team and member management.

      **Permissions:** Requires `teams.manage` scope.
  - name: Smart Lists
    description: |
      Dynamic contact segmentation with advanced filtering.

      **Permissions:** Requires `smartlists.manage` scope.
paths:
  /v1/activities:
    post:
      tags:
        - Activities
      summary: Create activity
      description: Log a new activity for a contact.
      operationId: createActivity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityInput'
      responses:
        '201':
          description: Activity created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Activity'
      security:
        - Authentication:
            - activities.create
components:
  schemas:
    ActivityInput:
      type: object
      required:
        - personId
        - type
      properties:
        personId:
          type: string
        type:
          type: string
          enum:
            - call
            - email
            - note
            - meeting
            - sms
            - activity
        channel:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        content:
          type: string
          maxLength: 5000
    SuccessResponse:
      type: object
      required:
        - meta
      properties:
        meta:
          type: object
          required:
            - requestId
            - timestamp
          properties:
            requestId:
              type: string
              format: uuid
              description: Unique request ID for tracing
            timestamp:
              type: string
              format: date-time
              description: Response timestamp
            version:
              type: string
              default: 1.0.0
    Activity:
      type: object
      required:
        - id
        - personId
        - type
        - createdAt
      properties:
        id:
          type: string
        personId:
          type: string
        type:
          type: string
          description: Activity type
          enum:
            - call
            - email
            - note
            - meeting
            - sms
            - activity
        channel:
          type: string
          nullable: true
        direction:
          type: string
          enum:
            - inbound
            - outbound
          nullable: true
        content:
          type: string
          maxLength: 5000
          nullable: true
        createdAt:
          type: string
          format: date-time
        agentName:
          type: string
          nullable: true
        starred:
          type: boolean
          default: false
  securitySchemes:
    Authentication:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        API key for authentication using Bearer token scheme.

        **How to get your API key:**
        1. Log into Client Commander
        2. Go to **Admin > API Keys**
        3. Click **Create API Key**
        4. Copy the key and use it in the Authorization header:

        ```
        Authorization: Bearer ccmd_live_your_key_here
        ```

````