Copper Financial Activities API

openapi: 3.2.0
info:
  title: Copper CRM Read-Only Activities API
  description: Read-only operations for Copper CRM API - optimized for ChatGPT integration
  version: 1.0.0
  contact:
    name: Copper Developer Support
    url: https://developer.copper.com/
    email: support@copper.com
servers:
- url: https://api.copper.com/developer_api/v1
  description: Copper API Production Server
security:
- bearerAuth: []
tags:
- name: Activities
  description: Activity tracking operations
paths:
  /activities/search:
    post:
      tags:
      - Activities
      summary: Search activities
      description: Search activities (use min/max_activity_date for ranges). Response uses pagination envelope (`page_number`,`total`,`data`) so ChatGPT can read pagination info; the X-PW-TOTAL header still exists. Paginate with page_number/page_size (max 200) until received records equal total. Limit to 100K results.
      operationId: searchActivities
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                parent:
                  type: object
                  description: Filter activities by parent resource
                  properties:
                    id:
                      type: integer
                      description: The ID of the parent resource
                    type:
                      type: string
                      enum:
                      - lead
                      - person
                      - company
                      - opportunity
                      description: The type of the parent resource
                activity_types:
                  type: array
                  description: An array of activity type objects to filter by
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: The activity type ID
                      category:
                        type: string
                        enum:
                        - user
                        - system
                        description: The activity type category
                user_ids:
                  type: array
                  items:
                    type: integer
                  description: An array of user IDs to filter by
                minimum_activity_date:
                  type: integer
                  description: Unix timestamp for the minimum activity date to filter by
                maximum_activity_date:
                  type: integer
                  description: Unix timestamp for the maximum activity date to filter by
                full_result:
                  type: boolean
                  description: When true, returns all activities matching the criteria (pagination still applies)
                  default: false
                sort_by:
                  type: string
                  description: The field on which to sort the results
                sort_direction:
                  type: string
                  enum:
                  - asc
                  - desc
                  description: The direction in which to sort the results
                page_number:
                  type: integer
                  minimum: 1
                  default: 1
                  description: The page number (starting with 1) that you would like to view
                page_size:
                  type: integer
                  minimum: 1
                  maximum: 200
                  default: 50
                  description: The number of entries included in a page of results
      responses:
        '200':
          description: Activities retrieved successfully
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-PW-TOTAL:
              $ref: '#/components/headers/X-PW-TOTAL'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginationEnvelope'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Activity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /activity_types:
    get:
      tags:
      - Activities
      summary: List activity types
      description: Retrieve a list of all available activity types in Copper
      operationId: listActivityTypes
      responses:
        '200':
          description: Activity types retrieved successfully
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: The activity type ID
                      example: 190711
                    category:
                      type: string
                      enum:
                      - user
                      - system
                      description: The activity type category
                      example: user
                    name:
                      type: string
                      description: The activity type name
                      example: Phone Call
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  headers:
    Retry-After:
      description: The number of seconds to wait before making a new request after hitting the rate limit
      schema:
        type: integer
        example: 60
    X-RateLimit-Reset:
      description: The time at which the current rate limit window resets, in UTC epoch seconds
      schema:
        type: integer
        example: 1640995200
    X-RateLimit-Remaining:
      description: The number of requests remaining in the current time window
      schema:
        type: integer
        example: 179
    X-PW-TOTAL:
      description: 'An upper bound of the total number of records that match the search criteria. This value is now also surfaced inside the response body as the ''total'' field of the pagination envelope so ChatGPT does not need to read headers. Use this with page_size (or the body-level total) to calculate the number of pages needed for pagination. Note: Search requests are limited to returning only the first 100,000 records regardless of pagination parameters.'
      schema:
        type: integer
        example: 775
    X-RateLimit-Limit:
      description: The maximum number of requests allowed in the current time window
      schema:
        type: integer
        example: 180
  schemas:
    Activity:
      type: object
      description: Copper keeps a record of activities for People, Leads, Opportunities, and Companies. Only 'User' type Activities can be created or modified using the developer API. 'System' type Activities are read-only.
      properties:
        id:
          type: integer
          description: Unique identifier for the activity
          example: 3061844454
        parent:
          type: object
          description: The identifier of the resource to which this activity belongs
          properties:
            id:
              type: integer
              description: The ID of the parent resource
              example: 9607580
            type:
              type: string
              description: The type of the parent resource
              enum:
              - lead
              - person
              - company
              - opportunity
              example: company
          required:
          - id
          - type
        type:
          type: object
          description: The activity type of this activity
          properties:
            id:
              type: integer
              description: The ID of the activity type
              example: 190711
            category:
              type: string
              description: The category of the activity type
              enum:
              - user
              - system
              example: user
          required:
          - id
          - category
        user_id:
          type: integer
          nullable: true
          description: When applicable, the id of the user who performed this activity
          example: 137658
        details:
          type: string
          nullable: true
          description: When applicable, the text body of this activity
          example: Demo phone call
        activity_date:
          type: integer
          nullable: true
          description: A Unix timestamp representing the time at which this activity took place
          example: 1496710783
        old_value:
          nullable: true
          description: When applicable, the value of a resource's property before this activity took place
          example: null
        new_value:
          nullable: true
          description: When applicable, the value of a resource's property after this activity took place
          example: null
        date_created:
          type: integer
          description: A Unix timestamp representing the time at which this activity was created
          example: 1496710787
        date_modified:
          type: integer
          description: A Unix timestamp representing the time at which this activity was last modified
          example: 1496710783
      required:
      - id
      - parent
      - type
      - details
    PaginationEnvelope:
      type: object
      description: Standard paginated response envelope returned for ChatGPT-only requests. Mirrors the previous pagination headers by surfacing totals inside the response body while keeping the original headers available.
      properties:
        page_number:
          type: integer
          description: Current page number (defaults to 1 when not provided in the request).
          example: 1
        total:
          type: integer
          description: Total number of records that match the request filters (equivalent to the X-PW-TOTAL header).
          example: 775
        data:
          type: array
          description: Records returned for the requested page. The item schema depends on the endpoint using this envelope.
          items: {}
      required:
      - page_number
      - total
      - data
      example:
        page_number: 1
        total: 775
        data: []
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              description: Human-readable error message
              example: You have exceeded your rate limit of 180 requests per minute
            details:
              type: object
              description: Additional error details
              additionalProperties: true
          required:
          - code
          - message
      required:
      - error
  responses:
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Authentication credentials were missing or incorrect
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request - The request was invalid or cannot be served
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Copper API key for authentication. Get your API key from your Copper account settings.
x-rate-limit:
  description: Copper API rate limiting information
  general:
    limit: 180
    period: minute
    description: Maximum of 180 requests per minute for general API calls
  bulk:
    limit: 3
    period: second
    description: Maximum of 3 requests per second for bulk operations