Copper Financial Account API

openapi: 3.2.0
info:
  title: Copper CRM Read-Only Account 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: Account
  description: Account and user information operations
paths:
  /users/search:
    post:
      tags:
      - Account
      summary: List users
      description: Retrieve all users. Response returns a pagination envelope (`page_number`, `total`, `data`) so ChatGPT can read pagination info; the X-PW-TOTAL header remains available. Continue paging with page_number/page_size until the received records match the total value.
      operationId: listUsers
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                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: Users 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/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{id}:
    get:
      tags:
      - Account
      summary: Get user by ID
      description: Retrieve a specific user by their ID. Special ID 'me' can be passed in to obtain the current API user.
      operationId: getUser
      parameters:
      - name: id
        in: path
        required: true
        description: User ID or 'me' for the current API user
        schema:
          oneOf:
          - type: integer
          - type: string
            enum:
            - me
      responses:
        '200':
          description: User 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:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '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:
    User:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the user
          example: 159258
        name:
          type: string
          description: Full name of the user
          example: Demo User
        email:
          type: string
          format: email
          description: Email address of the user
          example: demouser@example.com
        groups:
          type: array
          description: A list of teams (previously known as 'Groups') that the user belongs to
          items:
            type: object
            properties:
              id:
                type: integer
                description: Unique identifier for the team
                example: 1
              name:
                type: string
                description: Name of the team
                example: Sales
            required:
            - id
            - name
      required:
      - id
      - name
      - email
    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'
    NotFound:
      description: Not Found - The requested resource was not found
      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'
  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