Copper Financial Tasks API

openapi: 3.2.0
info:
  title: Copper CRM Read-Only Tasks 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: Tasks
  description: Task management operations
paths:
  /tasks/search:
    post:
      tags:
      - Tasks
      summary: Search tasks
      description: Search tasks. Response uses a 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. Limited to 100K results.
      operationId: searchTasks
      parameters:
      - name: custom_field_computed_values
        in: query
        required: false
        description: When true, returns computed custom field values (human-readable labels) in addition to option IDs for Dropdown and Multi-select fields. The response will include a 'computed_value' field alongside the 'value' field in custom_fields array.
        schema:
          type: boolean
          default: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  oneOf:
                  - type: string
                    description: 'Simple string for exact match (case-insensitive). Example: ''Follow up call'' will only match tasks named exactly ''Follow up call''.'
                  - type: object
                    description: Advanced object format for controlling match type
                    properties:
                      value:
                        type: string
                        description: The task name to search for
                      special_value:
                        type: array
                        description: Array specifying the match type
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - partial
                              - exact
                              description: 'Match type: ''partial'' for substring matching (e.g., ''Follow'' matches ''Follow up call''), ''exact'' for exact match'
                          required:
                          - type
                        maxItems: 1
                    required:
                    - value
                    - special_value
                    example:
                      value: Follow
                      special_value:
                      - type: partial
                  description: Filter by task name. Use simple string for exact match (case-insensitive), or use object format with special_value for partial matching capability.
                phrase:
                  oneOf:
                  - type: string
                    description: Simple string for exact match (case-insensitive). Alias for 'name' parameter.
                  - type: object
                    description: Advanced object format for controlling match type
                    properties:
                      value:
                        type: string
                        description: The task name/phrase to search for
                      special_value:
                        type: array
                        description: Array specifying the match type
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - partial
                              - exact
                              description: 'Match type: ''partial'' for substring matching, ''exact'' for exact match'
                          required:
                          - type
                        maxItems: 1
                    required:
                    - value
                    - special_value
                    example:
                      value: Follow
                      special_value:
                      - type: partial
                  description: Filter by task name (alias for 'name'). Use simple string for exact match (case-insensitive), or use object format with special_value for partial matching capability.
                related_resource:
                  type: object
                  description: Filter by the primary related resource for the task
                  properties:
                    id:
                      type: integer
                      description: The ID of the related resource
                    type:
                      type: string
                      enum:
                      - person
                      - company
                      - opportunity
                      - project
                      - lead
                      description: The type of the related resource
                tags:
                  type: array
                  items:
                    type: string
                  description: An array of tags to filter by
                assignee_ids:
                  type: array
                  items:
                    type: integer
                  description: An array of assignee IDs to filter by (the user IDs who own these tasks)
                statuses:
                  type: array
                  items:
                    type: string
                    enum:
                    - Open
                    - Completed
                  description: An array of statuses to filter by
                priorities:
                  type: array
                  items:
                    type: string
                    enum:
                    - None
                    - Low
                    - Medium
                    - High
                  description: An array of priorities to filter by
                minimum_due_date:
                  type: integer
                  description: Unix timestamp for the minimum due date
                maximum_due_date:
                  type: integer
                  description: Unix timestamp for the maximum due date
                minimum_reminder_date:
                  type: integer
                  description: Unix timestamp for the minimum reminder date
                maximum_reminder_date:
                  type: integer
                  description: Unix timestamp for the maximum reminder date
                minimum_completed_date:
                  type: integer
                  description: Unix timestamp for the minimum completed date
                maximum_completed_date:
                  type: integer
                  description: Unix timestamp for the maximum completed date
                minimum_close_date:
                  type: integer
                  description: Unix timestamp for the minimum creation date
                maximum_close_date:
                  type: integer
                  description: Unix timestamp for the maximum creation date
                minimum_modified_date:
                  type: integer
                  description: Unix timestamp for the minimum modification date
                maximum_modified_date:
                  type: integer
                  description: Unix timestamp for the maximum modification date
                custom_fields:
                  type: array
                  description: An array of custom field filters. Each filter can include custom_field_definition_id and optionally allow_empty to include records where the field is empty
                  items:
                    type: object
                    properties:
                      custom_field_definition_id:
                        type: integer
                        description: The custom field definition ID to filter by
                      value:
                        description: The value to match (can be string, number, array of option IDs, etc.)
                      allow_empty:
                        type: boolean
                        description: When true, includes records where this custom field is empty/null
                sort_by:
                  type: string
                  enum:
                  - name
                  - assigned_to
                  - related_to
                  - status
                  - priority
                  - due_date
                  - reminder_date
                  - completed_date
                  - date_created
                  - date_modified
                  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: Tasks 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/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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:
    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
    Task:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the task
          example: 3716920
        name:
          type: string
          description: The name of the task
          example: My First Task
        related_resource:
          type: object
          nullable: true
          description: The primary related resource for the task
          properties:
            id:
              type: integer
              description: The ID of the related resource
              example: 144296
            type:
              type: string
              description: The type of the related resource
              example: project
        assignee_id:
          type: integer
          nullable: true
          description: Unique identifier of the user that will be the owner of the task
          example: 137658
        due_date:
          type: integer
          nullable: true
          description: The date on which the task is due (Unix timestamp)
          example: 1496799000
        reminder_date:
          type: integer
          nullable: true
          description: The date on which to receive a reminder about the task (Unix timestamp)
          example: null
        completed_date:
          type: integer
          nullable: true
          description: The date on which the task was completed (Unix timestamp). This is automatically set when the status changes from Open to Completed, and cannot be set directly.
          example: null
        priority:
          type: string
          description: The priority of the task
          enum:
          - None
          - Low
          - Medium
          - High
          example: None
        status:
          type: string
          description: The status of the task
          enum:
          - Open
          - Completed
          example: Open
        details:
          type: string
          nullable: true
          description: Description of the task
          example: null
        tags:
          type: array
          description: An array of the tags associated with the task
          items:
            type: string
          example: []
        custom_fields:
          type: array
          description: An array of custom field values belonging to the task. When custom_field_computed_values query parameter is true, each field will include a computed_value with human-readable labels for Dropdown and Multi-select fields.
          items:
            type: object
            properties:
              custom_field_definition_id:
                type: integer
                description: The id of the custom field definition for which this custom field stores a value
                example: 100764
              value:
                description: The value (number, string, option id, or timestamp) of this custom field
                nullable: true
                example: null
              computed_value:
                description: The human-readable value of this custom field. For Dropdown/Multi-select fields, this contains the option label(s) instead of IDs. Only present when custom_field_computed_values=true is specified.
                nullable: true
        custom_activity_type_id:
          type: integer
          nullable: true
          description: The custom activity type ID associated with this task
          example: null
        date_created:
          type: integer
          description: A Unix timestamp representing the time at which this task was created
          example: 1496712856
        date_modified:
          type: integer
          description: A Unix timestamp representing the time at which this task was last modified
          example: 1496712857
      required:
      - id
      - name
  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