Copper Financial Leads API

openapi: 3.2.0
info:
  title: Copper CRM Read-Only Leads 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: Leads
  description: Lead management operations
paths:
  /leads/search:
    post:
      tags:
      - Leads
      summary: Search leads
      description: Search leads. 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: searchLeads
      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:
                ids:
                  type: array
                  items:
                    type: integer
                  description: An array of Lead IDs to retrieve
                name:
                  type: string
                  description: Filter by lead's full name (first and last name)
                first_name:
                  type: string
                  description: Filter by lead's first name
                last_name:
                  type: string
                  description: Filter by lead's last name
                middle_name:
                  type: string
                  description: Filter by lead's middle name
                emails:
                  type: string
                  format: email
                  description: Filter by email address
                phone_number:
                  type: string
                  description: Filter by phone number
                company_name:
                  type: string
                  description: Filter by the name of the company the lead belongs to
                title:
                  type: string
                  description: Filter by professional title
                city:
                  type: string
                  description: Filter by city in address
                state:
                  type: string
                  description: Filter by state in address
                postal_code:
                  type: string
                  description: Filter by postal code in address
                country:
                  type: string
                  description: Filter by country in address (two-character country code)
                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 leads). To get User IDs, see List Users. Use -2 for no assignee.
                status_ids:
                  type: array
                  items:
                    type: integer
                  description: An array of status IDs to filter by. To get lead status IDs, see List Lead Statuses.
                customer_source_ids:
                  type: array
                  items:
                    type: integer
                  description: An array of customer source IDs to filter by. To get customer source IDs, see List Customer Sources. Use -2 for no customer source.
                socials:
                  type: array
                  items:
                    type: string
                  description: An array of social profile URLs to filter by
                followed:
                  type: integer
                  enum:
                  - 1
                  - 2
                  description: Filter by followed status. Use 1 for followed leads, 2 for not followed.
                age:
                  type: integer
                  description: Maximum age in seconds of the lead
                minimum_monetary_value:
                  type: number
                  description: Filter by minimum monetary value
                maximum_monetary_value:
                  type: number
                  description: Filter by maximum monetary value
                minimum_interaction_count:
                  type: integer
                  description: Filter by minimum number of interactions the lead has had
                maximum_interaction_count:
                  type: integer
                  description: Filter by maximum number of interactions the lead has had
                minimum_interaction_date:
                  type: integer
                  description: Unix timestamp for the earliest date of the last interaction
                maximum_interaction_date:
                  type: integer
                  description: Unix timestamp for the latest date of the last interaction
                minimum_created_date:
                  type: integer
                  description: Unix timestamp for the minimum creation date
                maximum_created_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
                include_converted_leads:
                  type: boolean
                  description: When true, includes converted leads in the response
                  default: false
                custom_fields:
                  type: array
                  description: An array of custom field filters to search by. For multi-select fields, you can optionally include an 'option' property set to 'ANY' to match any of the specified values.
                  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.)
                      option:
                        type: string
                        enum:
                        - ANY
                        description: For multi-select fields, set to 'ANY' to match any of the specified values
                sort_by:
                  type: string
                  enum:
                  - name
                  - company_name
                  - title
                  - value
                  - email
                  - phone
                  - date_modified
                  - date_created
                  - city
                  - state
                  - country
                  - zip
                  - inactive_days
                  - socials
                  description: 'The field on which to sort the results. Note: date_modified and date_created sort from oldest to newest; inactive_days sorts from newest to oldest.'
                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: 25
                  default: 25
                  description: The number of entries included in a page of results
                fields:
                  type: array
                  description: Specify which fields to include in the response to reduce payload size. Include system field names as strings (e.g., 'name', 'status', 'email'). To include specific custom fields, add an object with custom_fields array. If omitted, all fields are returned.
                  items:
                    oneOf:
                    - type: string
                      description: System field name (e.g., 'id', 'name', 'first_name', 'last_name', 'company_name', 'title', 'email', 'phone_numbers', 'assignee_id', 'status', 'status_id', 'monetary_value', 'customer_source_id', 'tags', 'address', 'socials', 'websites', 'date_created', 'date_modified')
                    - type: object
                      properties:
                        custom_fields:
                          type: array
                          description: Array of custom field definition IDs to include
                          items:
                            type: object
                            properties:
                              custom_field_definition_id:
                                type: integer
                                description: The ID of the custom field definition to include in the response
                            required:
                            - custom_field_definition_id
                      required:
                      - custom_fields
                  example:
                  - id
                  - name
                  - company_name
                  - status
                  - assignee_id
      responses:
        '200':
          description: Leads 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/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /leads/{id}/activities:
    post:
      tags:
      - Leads
      summary: Get lead activities
      description: Retrieve all activities associated with a specific lead
      operationId: getLeadActivities
      parameters:
      - name: id
        in: path
        required: true
        description: Lead ID
        schema:
          type: integer
      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: Lead 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'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer_sources:
    get:
      tags:
      - Leads
      summary: List customer sources
      description: Retrieve a list of all customer sources in the account
      operationId: listCustomerSources
      responses:
        '200':
          description: Customer sources 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: Unique identifier for the customer source
                      example: 331241
                    name:
                      type: string
                      description: Name of the customer source
                      example: Website
                  required:
                  - id
                  - name
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /lead_statuses:
    get:
      tags:
      - Leads
      summary: List lead statuses
      description: Retrieve a list of all lead statuses in the account
      operationId: listLeadStatuses
      responses:
        '200':
          description: Lead statuses 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: Unique identifier for the lead status
                      example: 208231
                    name:
                      type: string
                      description: Name of the lead status
                      example: New
                  required:
                  - id
                  - name
        '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:
    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
    Lead:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the lead
          example: 8894157
        name:
          type: string
          description: The first and last name of the lead
          example: Test Lead
        prefix:
          type: string
          nullable: true
          description: Name prefix
          example: null
        first_name:
          type: string
          description: First name of the lead
          example: Test
        last_name:
          type: string
          description: Last name of the lead
          example: Lead
        middle_name:
          type: string
          nullable: true
          description: Middle name of the lead
          example: null
        suffix:
          type: string
          nullable: true
          description: Name suffix
          example: null
        address:
          type: object
          description: An object containing the lead's address
          properties:
            street:
              type: string
              example: 301 Howard St Ste 600
            city:
              type: string
              example: San Francisco
            state:
              type: string
              example: CA
            postal_code:
              type: string
              example: '94105'
            country:
              type: string
              example: US
        assignee_id:
          type: integer
          description: Unique identifier of the user that will be the owner of the lead
          example: 137658
        company_name:
          type: string
          description: The name of the company to which the lead belongs
          example: Lead's Company
        customer_source_id:
          type: integer
          description: Unique identifier of the customer source that generated this lead
          example: 331241
        details:
          type: string
          description: Description of the lead
          example: This is a demo description
        email:
          type: object
          description: An object containing the lead's email address and category
          properties:
            email:
              type: string
              format: email
              example: address@workemail.com
            category:
              type: string
              example: work
        monetary_value:
          type: number
          description: The expected monetary value of business with the lead
          example: 100
        phone_numbers:
          type: array
          description: An array of phone numbers belonging to the lead
          items:
            type: object
            properties:
              number:
                type: string
                description: A phone number
                example: 415-999-4321
              category:
                type: string
                description: The category of the phone number
                example: mobile
        socials:
          type: array
          description: An array of social profiles belonging to the lead
          items:
            type: object
            properties:
              url:
                type: string
                description: The URL of a social profile
                example: facebook.com/test_lead
              category:
                type: string
                description: The category of the social profile
                example: facebook
        status:
          type: string
          description: A string representing the status of the lead
          enum:
          - New
          - Unqualified
          - Contacted
          - Qualified
          example: New
        status_id:
          type: integer
          description: Unique identifier of the lead status
          example: 208231
        tags:
          type: array
          description: An array of the tags associated with the lead
          items:
            type: string
          example:
          - tag 1
          - tag 2
        title:
          type: string
          description: The professional title of the lead
          example: Title
        websites:
          type: array
          description: An array of websites belonging to the lead
          items:
            type: object
            properties:
              url:
                type: string
                description: The URL of a website
                example: www.workwebsite.com
              category:
                type: string
                description: The category of the website
                example: work
        custom_fields:
          type: array
          description: An array of custom field values belonging to the lead. 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
        date_created:
          type: integer
          description: A Unix timestamp representing the time at which this lead was created
          example: 1489018784
        date_modified:
          type: integer
          description: A Unix timestamp representing the time at which this lead was last modified
          example: 1489173601
        date_last_contacted:
          type: integer
          description: A Unix timestamp representing the time at which this lead was last contacted
          example: 1515796263
      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'
    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