Copper Financial Companies API

openapi: 3.2.0
info:
  title: Copper CRM Read-Only Companies 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: Companies
  description: Company management operations
paths:
  /companies/search:
    post:
      tags:
      - Companies
      summary: Search companies
      description: Search companies. 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: searchCompanies
      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 Company IDs to retrieve
                name:
                  oneOf:
                  - type: string
                    description: 'Simple string for exact match (case-insensitive). Example: ''Acme Corp'' will only match companies named exactly ''Acme Corp''.'
                  - type: object
                    description: Advanced object format for controlling match type
                    properties:
                      value:
                        type: string
                        description: The company 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., ''Happy Cat'' matches ''Happy Cat Hotels''), ''exact'' for exact match'
                          required:
                          - type
                        maxItems: 1
                    required:
                    - value
                    - special_value
                    example:
                      value: Happy Cat
                      special_value:
                      - type: partial
                  description: Filter by company name. Use simple string for exact match (case-insensitive), or use object format with special_value for partial matching capability.
                email_domain:
                  type: string
                  description: Filter by email domain (unique key for companies)
                email_domains:
                  type: array
                  items:
                    type: string
                  description: An array of email domains to filter by
                phone_number:
                  type: string
                  description: Filter by phone number
                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)
                primary_contact_ids:
                  type: array
                  items:
                    type: integer
                  description: An array of person IDs who are the primary contacts for these companies.
                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 companies). Use -2 for no assignee.
                contact_type_ids:
                  type: array
                  items:
                    type: integer
                  description: An array of contact type IDs to filter by. See List Contact Types.
                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 companies, 2 for not followed.
                age:
                  type: integer
                  description: Maximum age in seconds of the company record
                minimum_interaction_count:
                  type: integer
                  description: Filter by minimum number of interactions
                maximum_interaction_count:
                  type: integer
                  description: Filter by maximum number of interactions
                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
                custom_fields:
                  type: array
                  description: An array of custom field filters to search by. For date fields, use minimum_value and maximum_value. For multi-select fields, you can use 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.)
                      minimum_value:
                        type: integer
                        description: For date/number fields, the minimum value (Unix timestamp for dates)
                      maximum_value:
                        type: integer
                        description: For date/number fields, the maximum value (Unix timestamp for dates)
                      allow_empty:
                        type: boolean
                        description: When true, includes records where this custom field is empty/null
                sort_by:
                  type: string
                  enum:
                  - name
                  - phone
                  - contact
                  - contact_first_name
                  - contact_last_name
                  - date_modified
                  - date_created
                  - email_domain
                  - city
                  - state
                  - country
                  - zip
                  - assignee
                  - contact_group
                  - last_interaction
                  - interaction_count
                  - primary_website
                  - socials
                  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
                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', 'email_domain', 'phone_numbers'). 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', 'email_domain', 'phone_numbers', 'address', 'assignee_id', 'contact_type_id', 'primary_contact_id', 'tags', 'socials', 'websites', 'interaction_count', '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
                  - email_domain
                  - assignee_id
                  - interaction_count
      responses:
        '200':
          description: Companies 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/Company'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /companies/{id}/activities:
    post:
      tags:
      - Companies
      summary: Get company activities
      description: Retrieve all activities associated with a specific company
      operationId: getCompanyActivities
      parameters:
      - name: id
        in: path
        required: true
        description: Company 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: Company 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'
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: []
    Company:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the company
          example: 9607580
        name:
          type: string
          description: The name of the company
          example: Dunder Mifflin (sample)
        address:
          type: object
          nullable: true
          description: An encapsulation of the company's street, city, state, postal code, and country
          properties:
            street:
              type: string
              example: 213 West Main Street
            city:
              type: string
              example: Scranton
            state:
              type: string
              example: PA
            postal_code:
              type: string
              example: '18501'
            country:
              type: string
              example: ''
        assignee_id:
          type: integer
          nullable: true
          description: Unique identifier of the user that will be the owner of the company
          example: null
        contact_type_id:
          type: integer
          nullable: true
          description: The unique identifier of the contact type of the company
          example: null
        details:
          type: string
          nullable: true
          description: Description of the company
          example: 'Keywords: Dunder Mifflin, Dunder Mifflin Infinity, Dunder Mifflin Paper'
        email_domain:
          type: string
          nullable: true
          description: The domain to which email addresses for the company belong. This is a unique key for companies - no two records can have the same domain name.
          example: dundermifflin.com
        phone_numbers:
          type: array
          description: An array of phone numbers belonging to the company
          items:
            type: object
            properties:
              number:
                type: string
                description: A phone number
                example: '4153554776'
              category:
                type: string
                description: The category of the phone number
                example: work
        primary_contact_id:
          type: integer
          nullable: true
          description: The unique identifier of the person who is the primary contact for this company
          example: 27140359
        socials:
          type: array
          description: An array of social profiles belonging to the company
          items:
            type: object
            properties:
              url:
                type: string
                description: The URL of a social profile
                example: https://www.linkedin.com/in/sabreinc
              category:
                type: string
                description: The category of the social profile
                example: linkedin
        tags:
          type: array
          description: An array of the tags associated with the company
          items:
            type: string
          example: []
        websites:
          type: array
          description: An array of websites belonging to the company
          items:
            type: object
            properties:
              url:
                type: string
                description: The URL of a website
                example: http://www.dundermifflin.com/index.shtml
              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 company. 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
        interaction_count:
          type: integer
          description: The number of interactions with this company
          example: 0
        date_created:
          type: integer
          description: A Unix timestamp representing the time at which this company was created
          example: 1483988828
        date_modified:
          type: integer
          description: A Unix timestamp representing the time at which this company was last modified
          example: 1489018922
      required:
      - id
      - name
    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