### Install Dependencies and Run Tests

Source: https://github.com/claimerapp/copper-sdk/blob/master/README.md

Install project dependencies using pipenv, enter the shell, and then run tests. Ensure your Copper API token and email are set as environment variables.

```bash
# install depds
pipenv install
# enter shell
pipenv shell
# run tests
COPPER_API_TOKEN='<my copper token>' COPPER_API_EMAIL='<my copper email>' pytest
```

--------------------------------

### Get Customer Acquisition Sources

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Fetches a list of all available customer acquisition sources for leads and opportunities. This data can be used to standardize source tracking.

```python
sources = copper.customersources.get()
print(sources)
# Returns: [{'id': 1, 'name': 'Referral'}, {'id': 2, 'name': 'Website'}, ...]
```

--------------------------------

### Search Activities with Request Body

Source: https://github.com/claimerapp/copper-sdk/blob/master/README.md

When searching for activities, you can supply a request body as a dictionary to filter results. This example shows pagination parameters.

```python
all_activities = copper.activities.list({
    page_number: 2,
    page_size: 50
})
```

--------------------------------

### Get Account Information

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieve details for the authenticated Copper account using the account resource. Requires client initialization.

```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Get account details
account_info = copper.account.get()
print(account_info)
# Returns: {'id': 12345, 'name': 'My Company', ...}
```

--------------------------------

### Get an Activity by ID

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a specific activity using its unique identifier.

```python
activity = copper.activities.get(new_activity['id'])
```

--------------------------------

### Get a Task by ID

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a specific task using its unique identifier.

```python
task = copper.tasks.get(new_task['id'])
```

--------------------------------

### Get a Specific Pipeline

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves details for a single pipeline using its ID.

```python
pipeline = copper.pipelines.get(pipeline_id=12345)
```

--------------------------------

### Get Available Activity Types

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a list of all available activity types configured in your Copper account.

```python
activity_types = copper.activities.types()
```

--------------------------------

### Get Loss Reasons for Opportunities

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a list of predefined reasons for lost opportunities. This helps in analyzing why opportunities are not closed successfully.

```python
reasons = copper.lossreasons.get()
print(reasons)
# Returns: [{'id': 1, 'name': 'Price'}, {'id': 2, 'name': 'Competitor'}, ...]
```

--------------------------------

### Manage Opportunity Relationships

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Use these methods to get related records, establish new relationships, or remove existing ones for opportunities.

```python
related = copper.opportunities.related(new_opportunity['id'])
related_links = copper.opportunities.list_related(new_opportunity['id'])
```

```python
copper.opportunities.relate(
    relation_id=98765,
    id=new_opportunity['id'],
    target_type='person',
    target_id=54321
)
```

```python
copper.opportunities.unrelate(relation_link_id=44444)
```

--------------------------------

### Get a Specific Webhook

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves details for a single webhook using its ID.

```python
webhook = copper.webhooks.get(webhook_id=12345)
```

--------------------------------

### Get a Specific Pipeline Stage

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves details for a single pipeline stage using its ID.

```python
stage = copper.pipelinestages.get(stage_id=12345)
```

--------------------------------

### Initialization and Authentication

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Demonstrates how to initialize the Copper client with authentication credentials and optional configurations.

```APIDOC
## Initialization and Authentication

### Description
The Copper class is the main entry point that handles authentication and provides access to all CRM entity resources. It requires your Copper email and API token for authentication.

### Request Example
```python
from copper_sdk import Copper

# Initialize the Copper client
copper = Copper(
    email='your-email@company.com',
    token='your-copper-api-token'
)

# Optional: Enable debug mode to see request/response details
copper_debug = Copper(
    email='your-email@company.com',
    token='your-copper-api-token',
    debug=True
)

# Optional: Use a custom session or base URL
import requests
custom_session = requests.Session()
copper_custom = Copper(
    email='your-email@company.com',
    token='your-copper-api-token',
    base_url='https://api.copper.com/developer_api/v1',
    session=custom_session
)
```
```

--------------------------------

### Initialize Copper SDK

Source: https://github.com/claimerapp/copper-sdk/blob/master/README.md

Create an instance of the Copper class by providing your email and Copper API token. This is the entrypoint for all SDK operations.

```python
from copper_sdk import Copper

copper = Copper(
    email='joe@bloggs.com',
    token='abc123',
)
```

--------------------------------

### Full CRUD Operations for Leads

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Manage leads including creation, retrieval, update, deletion, and conversion. Supports searching, upserting, and relationship management. Requires client initialization.

```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Create a new lead
new_lead = copper.leads.create({
    'name': 'Jane Smith',
    'email': {'email': 'jane@prospect.com', 'category': 'work'},
    'phone_numbers': [{'number': '555-1234', 'category': 'work'}],
    'address': {'city': 'San Francisco', 'state': 'CA'},
    'customer_source_id': 12345,
    'monetary_value': 50000,
    'tags': ['enterprise', 'inbound']
})
print(f"Created lead ID: {new_lead['id']}")

# Get a specific lead
lead = copper.leads.get(new_lead['id'])

# Update a lead
updated_lead = copper.leads.update(new_lead['id'], {
    'monetary_value': 75000,
    'status': 'Qualified'
})

# Search/list leads with filters and pagination
leads = copper.leads.list({
    'page_number': 1,
    'page_size': 100,
    'sort_by': 'name',
    'sort_direction': 'asc'
})

# Upsert a lead (create or update based on match)
upserted_lead = copper.leads.upsert({
    'name': 'Jane Smith',
    'email': {'email': 'jane@prospect.com', 'category': 'work'},
    'properties': {'match_field': 'email'}
})

# Convert lead to opportunity/person/company
conversion_result = copper.leads.convert(new_lead['id'], {
    'details': {
        'person': {'name': 'Jane Smith', 'contact_type_id': 1},
        'company': {'name': 'Prospect Corp'},
        'opportunity': {
            'name': 'Prospect Corp Deal',
            'pipeline_id': 12345,
            'monetary_value': 75000
        }
    }
})

# Get activities for a lead
lead_activities = copper.leads.activities(new_lead['id'], {
    'page_number': 1,
    'page_size': 50
})

# Get lead statuses and customer sources
statuses = copper.leads.statuses()
sources = copper.leads.customer_sources()

# Manage lead relationships
related = copper.leads.list_related(new_lead['id'])
copper.leads.relate(
    relation_id=98765,          # Custom field definition ID
    id=new_lead['id'],          # Lead ID
    target_type='company',      # Target entity type
    target_id=54321             # Target entity ID
)
copper.leads.unrelate(relation_link_id=11111)

# Delete a lead
copper.leads.delete(new_lead['id'])
```

--------------------------------

### Manage Opportunities with Copper SDK

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

This snippet covers managing sales opportunities. It includes creating, retrieving, updating, and listing opportunities, as well as fetching pipeline and stage information.

```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Create a new opportunity
new_opportunity = copper.opportunities.create({
    'name': 'Enterprise Deal - Acme Corp',
    'primary_contact_id': 12345,
    'company_id': 67890,
    'pipeline_id': 11111,
    'pipeline_stage_id': 22222,
    'monetary_value': 150000,
    'close_date': 1704067200,  # Unix timestamp
    'customer_source_id': 33333,
    'tags': ['enterprise', 'q1-target']
})
print(f"Created opportunity ID: {new_opportunity['id']}")

# Get an opportunity by ID
opportunity = copper.opportunities.get(new_opportunity['id'])

# Update an opportunity
updated_opportunity = copper.opportunities.update(new_opportunity['id'], {
    'pipeline_stage_id': 33333,  # Move to next stage
    'monetary_value': 175000,
    'win_probability': 75
})

# Search/list opportunities with filters
opportunities = copper.opportunities.list({
    'page_number': 1,
    'page_size': 100,
    'sort_by': 'name',
    'sort_direction': 'asc'
})

# Get pipeline and stage information
pipelines = copper.opportunities.pipelines()
all_stages = copper.opportunities.pipeline_stages()
stages_in_pipeline = copper.opportunities.stages_in_pipeline(pipeline_id=11111)

# Get customer sources and loss reasons
customer_sources = copper.opportunities.customer_sources()
loss_reasons = copper.opportunities.loss_reasons()
```

--------------------------------

### Initialize Copper CRM Client

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Instantiate the Copper client with your email and API token. Debug mode and custom base URLs or sessions are optional configurations.

```python
from copper_sdk import Copper

# Initialize the Copper client
copper = Copper(
    email='your-email@company.com',
    token='your-copper-api-token'
)

# Optional: Enable debug mode to see request/response details
copper_debug = Copper(
    email='your-email@company.com',
    token='your-copper-api-token',
    debug=True
)

# Optional: Use a custom session or base URL
import requests
custom_session = requests.Session()
copper_custom = Copper(
    email='your-email@company.com',
    token='your-copper-api-token',
    base_url='https://api.copper.com/developer_api/v1',
    session=custom_session
)
```

--------------------------------

### Create a New Pipeline

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Creates a new sales pipeline with a specified name and a list of stage names.

```python
new_pipeline = copper.pipelines.create({
    'name': 'Enterprise Sales Pipeline',
    'stages': ['Discovery', 'Proposal', 'Negotiation', 'Closed Won']
})
```

--------------------------------

### Manage Company Records with Copper SDK

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

This snippet demonstrates how to manage organization records. It covers creating, retrieving, updating, and deleting companies, including bulk updates and searching.

```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Create a new company
new_company = copper.companies.create({
    'name': 'Acme Corporation',
    'address': {'street': '456 Corporate Blvd', 'city': 'Chicago', 'state': 'IL'},
    'phone_numbers': [{'number': '555-9999', 'category': 'work'}],
    'email_domain': 'acme.com',
    'contact_type_id': 2,
    'tags': ['enterprise', 'tech']
})
print(f"Created company ID: {new_company['id']}")

# Get a company by ID
company = copper.companies.get(new_company['id'])

# Update a company
updated_company = copper.companies.update(new_company['id'], {
    'details': 'Updated company description',
    'tags': ['enterprise', 'tech', 'strategic']
})

# Bulk update multiple companies
bulk_result = copper.companies.bulk_update(new_company['id'], [
    {'id': 11111, 'tags': ['bulk-updated']},
    {'id': 22222, 'tags': ['bulk-updated']}
])

# Search/list companies with filters
companies = copper.companies.list({
    'page_number': 1,
    'page_size': 50,
    'sort_by': 'date_modified',
    'sort_direction': 'desc'
})

# Get related records for a company
related = copper.companies.list_related(new_company['id'])

# Get company activities
activities = copper.companies.activities(new_company['id'])

# Get contact types
contact_types = copper.companies.contact_types()

# Delete a company
copper.companies.delete(new_company['id'])
```

--------------------------------

### Create, Update, and Delete Webhooks

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Demonstrates how to create, update, and delete webhooks for CRM events. Ensure the target URL is accessible and the event type is valid.

```python
new_webhook = copper.webhooks.create({
    'target': 'https://your-server.com/copper-webhook',
    'type': 'lead',
    'event': 'new'  # Options: new, update, delete
})
print(f"Created webhook ID: {new_webhook['id']}")
```

```python
updated_webhook = copper.webhooks.update(new_webhook['id'], {
    'target': 'https://your-server.com/new-webhook-endpoint'
})
```

```python
copper.webhooks.delete(new_webhook['id'])
```

--------------------------------

### Create a New Activity

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Creates a new activity record in Copper. Requires details like type, description, parent record, and activity date.

```python
new_activity = copper.activities.create({
    'type': {'id': 1, 'category': 'user'},  # Activity type
    'details': 'Had a productive discovery call',
    'parent': {'id': 12345, 'type': 'lead'},
    'activity_date': 1704067200  # Unix timestamp
})
```

--------------------------------

### List All Pipelines

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a list of all sales pipelines configured in your Copper account.

```python
pipelines = copper.pipelines.list()
```

--------------------------------

### Handle SDK Errors and Rate Limiting

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Demonstrates how to implement error handling for Copper SDK operations, including specific exceptions for rate limiting (TooManyRequests) and general Copper or HTTP errors.

```python
from copper_sdk import Copper
from copper_sdk.exception import TooManyRequests, CopperException
import requests

copper = Copper(email='user@company.com', token='api-token')

try:
    leads = copper.leads.list({'page_size': 200})
except TooManyRequests as e:
    # Handle rate limiting (429 errors)
    print(f"Rate limited: {e}")
    print(f"Response: {e.response}")
    print(f"Original request body: {e.json_body}")
except requests.exceptions.HTTPError as e:
    # Handle HTTP errors (including Copper internal errors)
    print(f"HTTP error occurred: {e}")
except CopperException as e:
    # Handle other Copper-specific errors
    print(f"Copper error: {e}")
```

--------------------------------

### Search and List Activities

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Fetches a list of activities, with options for pagination and filtering. Use 'full_result': False for paginated results.

```python
activities = copper.activities.list({
    'page_number': 1,
    'page_size': 50,
    'full_result': False
})
```

```python
lead_activities = copper.activities.list({
    'parent': {'id': 12345, 'type': 'lead'},
    'page_number': 1,
    'page_size': 100
})
```

```python
recent_activities = copper.activities.list({
    'minimum_activity_date': 1701388800,  # Dec 1, 2023
    'maximum_activity_date': 1704067200,  # Jan 1, 2024
    'page_size': 100
})
```

--------------------------------

### Tasks API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Resource for managing action items and to-dos.

```APIDOC
## Tasks API

### Description
The Tasks resource manages action items and to-dos that can be related to other CRM entities.

### Methods
- `create(task_data)`: Create a new task.
- `get(task_id)`: Get a task by its ID.
- `update(task_id, update_data)`: Update an existing task.
- `list(filters)`: Search or list tasks with optional filters.
- `relate(id, entity_id, entity_type)`: Relate a task to another entity.
- `delete(task_id)`: Delete a task.

### Parameters
#### Request Body for `create`
- **name** (string) - Required - The name of the task.
- **assignee_id** (integer) - Required - The ID of the user assigned to the task.
- **due_date** (integer) - Required - Unix timestamp for the due date.
- **reminder_date** (integer) - Optional - Unix timestamp for the reminder date.
- **priority** (string) - Optional - Priority of the task (e.g., 'High', 'Medium', 'Low').
- **status** (string) - Optional - Status of the task (e.g., 'Open', 'Completed').
- **details** (string) - Optional - Detailed description of the task.

#### Request Body for `update`
- **status** (string) - Optional - Update the status of the task.
- **details** (string) - Optional - Update the details of the task.

#### Query Parameters for `list`
- **page_number** (integer) - Optional - The page number for pagination.
- **page_size** (integer) - Optional - The number of items per page.
- **sort_by** (string) - Optional - Field to sort by (e.g., 'name').
- **sort_direction** (string) - Optional - Direction of sorting ('asc' or 'desc').

#### Parameters for `relate`
- **id** (integer) - Required - The ID of the task to relate.
- **entity_id** (integer) - Required - The ID of the entity to relate the task to.
- **entity_type** (string) - Required - The type of the entity (e.g., 'person', 'organization').

### Request Example for `create`
```json
{
  "name": "Follow up with client",
  "assignee_id": 12345,
  "due_date": 1704153600,
  "reminder_date": 1704067200,
  "priority": "High",
  "status": "Open",
  "details": "Send proposal and schedule demo"
}
```

### Response Example for `create`
```json
{
  "id": "new_task_id",
  "name": "Follow up with client",
  "assignee_id": 12345,
  "due_date": 1704153600,
  "reminder_date": 1704067200,
  "priority": "High",
  "status": "Open",
  "details": "Send proposal and schedule demo"
}
```
```

--------------------------------

### Create a New Task

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Creates a new task in Copper. Requires a name, assignee, due date, and other optional details.

```python
new_task = copper.tasks.create({
    'name': 'Follow up with client',
    'assignee_id': 12345,
    'due_date': 1704153600,  # Unix timestamp
    'reminder_date': 1704067200,
    'priority': 'High',
    'status': 'Open',
    'details': 'Send proposal and schedule demo'
})
```

--------------------------------

### List All Webhooks

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a list of all configured webhooks in your Copper account.

```python
webhooks = copper.webhooks.list()
```

--------------------------------

### Search and List Tasks

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Fetches a list of tasks with options for pagination and sorting. You can sort by name in ascending or descending order.

```python
tasks = copper.tasks.list({
    'page_number': 1,
    'page_size': 50,
    'sort_by': 'name',
    'sort_direction': 'asc'
})
```

--------------------------------

### List Activities using Copper SDK

Source: https://github.com/claimerapp/copper-sdk/blob/master/README.md

Access the 'activities' entity via the initialized Copper object to perform operations like listing all activities. Ensure the Copper class is instantiated first.

```python
from copper_sdk import Copper

copper = Copper(
    email='joe@bloggs.com',
    token='abc123',
)

all_activities = copper.activities.list()
```

--------------------------------

### List All Pipeline Stages

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a list of all pipeline stages across all pipelines in your Copper account.

```python
stages = copper.pipelinestages.list()
```

--------------------------------

### Pipelines API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Resource for managing sales pipeline configurations.

```APIDOC
## Pipelines API

### Description
The Pipelines resource manages sales pipeline configurations for opportunity tracking.

### Methods
- `list()`: List all pipelines.
- `get(pipeline_id)`: Get a specific pipeline by its ID.
- `create(pipeline_data)`: Create a new pipeline.
- `update(pipeline_id, update_data)`: Update an existing pipeline.
- `delete(pipeline_id)`: Delete a pipeline.

### Parameters
#### Request Body for `create`
- **name** (string) - Required - The name of the pipeline.
- **stages** (array of strings) - Required - The names of the stages in the pipeline.

#### Request Body for `update`
- **name** (string) - Optional - The updated name of the pipeline.

### Request Example for `create`
```json
{
  "name": "Enterprise Sales Pipeline",
  "stages": ["Discovery", "Proposal", "Negotiation", "Closed Won"]
}
```

### Response Example for `create`
```json
{
  "id": "new_pipeline_id",
  "name": "Enterprise Sales Pipeline",
  "stages": ["Discovery", "Proposal", "Negotiation", "Closed Won"]
}
```
```

--------------------------------

### Customer Sources API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

List available customer acquisition sources for leads and opportunities.

```APIDOC
## Customer Sources API

### Description
The CustomerSources resource lists available customer acquisition sources for leads and opportunities.

### Get all customer sources
```python
sources = copper.customersources.get()
print(sources)
# Returns: [{'id': 1, 'name': 'Referral'}, {'id': 2, 'name': 'Website'}, ...]
```
```

--------------------------------

### Error Handling

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Information on how the SDK handles errors, including automatic retries and custom exceptions.

```APIDOC
## Error Handling

### Description
The SDK provides automatic retry logic for rate limiting and exposes custom exceptions for error handling.

### Example Usage
```python
from copper_sdk import Copper
from copper_sdk.exception import TooManyRequests, CopperException
import requests

copper = Copper(email='user@company.com', token='api-token')

try:
    leads = copper.leads.list({'page_size': 200})
except TooManyRequests as e:
    # Handle rate limiting (429 errors)
    print(f"Rate limited: {e}")
    print(f"Response: {e.response}")
    print(f"Original request body: {e.json_body}")
except requests.exceptions.HTTPError as e:
    # Handle HTTP errors (including Copper internal errors)
    print(f"HTTP error occurred: {e}")
except CopperException as e:
    # Handle other Copper-specific errors
    print(f"Copper error: {e}")
```
```

--------------------------------

### Pipeline Stages API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Resource for managing individual stages within sales pipelines.

```APIDOC
## Pipeline Stages API

### Description
The PipelineStages resource manages individual stages within sales pipelines.

### Methods
- `list()`: List all pipeline stages.
- `get(stage_id)`: Get a specific pipeline stage by its ID.
- `create(stage_data)`: Create a new pipeline stage.
- `update(stage_id, update_data)`: Update an existing pipeline stage.
- `delete(stage_id)`: Delete a pipeline stage.

### Parameters
#### Request Body for `create`
- **name** (string) - Required - The name of the stage.
- **pipeline_id** (integer) - Required - The ID of the pipeline this stage belongs to.
- **win_probability** (integer) - Optional - The probability of winning associated with this stage (0-100).

#### Request Body for `update`
- **name** (string) - Optional - The updated name of the stage.
- **win_probability** (integer) - Optional - The updated win probability.

### Request Example for `create`
```json
{
  "name": "Qualification",
  "pipeline_id": 67890,
  "win_probability": 20
}
```

### Response Example for `create`
```json
{
  "id": "new_stage_id",
  "name": "Qualification",
  "pipeline_id": 67890,
  "win_probability": 20
}
```
```

--------------------------------

### Create a New Pipeline Stage

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Creates a new stage within a specified pipeline. Requires a name, pipeline ID, and win probability.

```python
new_stage = copper.pipelinestages.create({
    'name': 'Qualification',
    'pipeline_id': 67890,
    'win_probability': 20
})
```

--------------------------------

### Loss Reasons API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

List available reasons for lost opportunities.

```APIDOC
## Loss Reasons API

### Description
The LossReasons resource lists available reasons for lost opportunities.

### Get all loss reasons
```python
reasons = copper.lossreasons.get()
print(reasons)
# Returns: [{'id': 1, 'name': 'Price'}, {'id': 2, 'name': 'Competitor'}, ...]
```
```

--------------------------------

### Manage Users in Copper CRM

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieve a specific user by ID or list/search users with pagination. Ensure the Copper client is initialized.

```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Get a specific user by ID
user = copper.users.get(12345)
print(user)
# Returns: {'id': 12345, 'name': 'John Doe', 'email': 'john@company.com', ...}

# List/search users with pagination
users = copper.users.list({
    'page_number': 1,
    'page_size': 50
})
print(users)
# Returns: [{'id': 12345, 'name': 'John Doe', ...}, ...]
```

--------------------------------

### Update an Activity

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Modifies an existing activity. Provide the activity ID and the fields to update.

```python
updated_activity = copper.activities.update(new_activity['id'], {
    'details': 'Updated: Had a productive discovery call - follow up scheduled'
})
```

--------------------------------

### Opportunities API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

The Opportunities resource manages sales deals through pipelines with support for pipeline stages, related records, and reporting metadata.

```APIDOC
## Opportunities API

### Description
The Opportunities resource manages sales deals through pipelines with support for pipeline stages, related records, and reporting metadata.

### Methods

- **Create Opportunity**: Creates a new sales deal record.
- **Get Opportunity**: Retrieves a sales deal record by ID.
- **Update Opportunity**: Updates an existing sales deal record.
- **List Opportunities**: Searches or lists sales deal records with filters.
- **Get Pipelines**: Retrieves information about sales pipelines.
- **Get Pipeline Stages**: Retrieves information about all pipeline stages.
- **Get Stages in Pipeline**: Retrieves pipeline stages for a specific pipeline.
- **Get Customer Sources**: Retrieves available customer sources.
- **Get Loss Reasons**: Retrieves available loss reasons.

### Request Body Examples

#### Create Opportunity
```json
{
  "name": "Enterprise Deal - Acme Corp",
  "primary_contact_id": 12345,
  "company_id": 67890,
  "pipeline_id": 11111,
  "pipeline_stage_id": 22222,
  "monetary_value": 150000,
  "close_date": 1704067200,  // Unix timestamp
  "customer_source_id": 33333,
  "tags": ["enterprise", "q1-target"]
}
```

#### Update Opportunity
```json
{
  "pipeline_stage_id": 33333,  // Move to next stage
  "monetary_value": 175000,
  "win_probability": 75
}
```

#### List Opportunities Filters
```json
{
  "page_number": 1,
  "page_size": 100,
  "sort_by": "name",
  "sort_direction": "asc"
}
```

### Response Examples

#### Create Opportunity Response
```json
{
  "id": "opportunity_id_123",
  "name": "Enterprise Deal - Acme Corp",
  "primary_contact_id": 12345,
  "company_id": 67890,
  "pipeline_id": 11111,
  "pipeline_stage_id": 22222,
  "monetary_value": 150000,
  "close_date": 1704067200,
  "customer_source_id": 33333,
  "tags": ["enterprise", "q1-target"]
}
```

#### Get Opportunity Response
```json
{
  "id": "opportunity_id_123",
  "name": "Enterprise Deal - Acme Corp",
  "primary_contact_id": 12345,
  "company_id": 67890,
  "pipeline_id": 11111,
  "pipeline_stage_id": 22222,
  "monetary_value": 150000,
  "close_date": 1704067200,
  "customer_source_id": 33333,
  "tags": ["enterprise", "q1-target"]
}
```

#### List Opportunities Response
```json
[
  {
    "id": "opportunity_id_123",
    "name": "Enterprise Deal - Acme Corp",
    "monetary_value": 150000
  },
  {
    "id": "opportunity_id_456",
    "name": "Small Business Deal",
    "monetary_value": 5000
  }
]
```

#### Pipelines Response
```json
[
  {"id": 11111, "name": "Sales Pipeline"},
  {"id": 22222, "name": "Renewal Pipeline"}
]
```

#### Pipeline Stages Response
```json
[
  {"id": 22222, "name": "Prospecting", "pipeline_id": 11111},
  {"id": 33333, "name": "Proposal", "pipeline_id": 11111}
]
```
```

--------------------------------

### Leads API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Provides full CRUD operations for managing sales leads, including conversion, activity tracking, and relationship management.

```APIDOC
## Leads API

### Description
The Leads resource provides full CRUD operations for managing sales leads, including conversion to opportunities, activity tracking, and relationship management.

### Method
POST, GET, PUT, DELETE, POST, POST, GET, POST, POST, POST, POST, POST, POST, DELETE

### Endpoint
/leads
/leads/{id}
/leads/{id}
/leads
/leads/upsert
/leads/{id}/convert
/leads/{id}/activities
/leads/statuses
/leads/customer_sources
/leads/{id}/related
/leads/{id}/relate
/leads/{id}/unrelate
/leads/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the lead.
- **relation_id** (integer) - Required - The ID of the custom field definition.
- **relation_link_id** (integer) - Required - The ID of the relationship link.

#### Query Parameters
- **page_number** (integer) - Optional - The page number for pagination.
- **page_size** (integer) - Optional - The number of leads per page.
- **sort_by** (string) - Optional - Field to sort by (e.g., 'name').
- **sort_direction** (string) - Optional - Direction of sorting ('asc' or 'desc').

#### Request Body
**create**: 
- **name** (string) - Required - The name of the lead.
- **email** (object) - Optional - Lead's email address.
  - **email** (string) - Required - The email address.
  - **category** (string) - Optional - Category of the email (e.g., 'work').
- **phone_numbers** (array) - Optional - List of phone numbers.
  - **number** (string) - Required - The phone number.
  - **category** (string) - Optional - Category of the phone number (e.g., 'work').
- **address** (object) - Optional - Lead's address.
  - **city** (string) - Optional - City.
  - **state** (string) - Optional - State.
- **customer_source_id** (integer) - Optional - ID of the customer source.
- **monetary_value** (integer) - Optional - Monetary value associated with the lead.
- **tags** (array) - Optional - List of tags.

**update**: 
- **monetary_value** (integer) - Optional - Updated monetary value.
- **status** (string) - Optional - Updated status.

**upsert**: 
- **name** (string) - Required - The name of the lead.
- **email** (object) - Required - Lead's email address.
  - **email** (string) - Required - The email address.
  - **category** (string) - Optional - Category of the email (e.g., 'work').
- **properties** (object) - Required - Properties for matching.
  - **match_field** (string) - Required - Field to match on (e.g., 'email').

**convert**: 
- **details** (object) - Required - Details for conversion.
  - **person** (object) - Optional - Person details.
    - **name** (string) - Required - Person's name.
    - **contact_type_id** (integer) - Required - ID of the contact type.
  - **company** (object) - Optional - Company details.
    - **name** (string) - Required - Company name.
  - **opportunity** (object) - Optional - Opportunity details.
    - **name** (string) - Required - Opportunity name.
    - **pipeline_id** (integer) - Required - ID of the pipeline.
    - **monetary_value** (integer) - Optional - Monetary value of the opportunity.

**relate**: 
- **target_type** (string) - Required - Type of the target entity (e.g., 'company').
- **target_id** (integer) - Required - ID of the target entity.

### Request Example
```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Create a new lead
new_lead = copper.leads.create({
    'name': 'Jane Smith',
    'email': {'email': 'jane@prospect.com', 'category': 'work'},
    'phone_numbers': [{'number': '555-1234', 'category': 'work'}],
    'address': {'city': 'San Francisco', 'state': 'CA'},
    'customer_source_id': 12345,
    'monetary_value': 50000,
    'tags': ['enterprise', 'inbound']
})
print(f"Created lead ID: {new_lead['id']}")

# Get a specific lead
lead = copper.leads.get(new_lead['id'])

# Update a lead
updated_lead = copper.leads.update(new_lead['id'], {
    'monetary_value': 75000,
    'status': 'Qualified'
})

# Search/list leads with filters and pagination
leads = copper.leads.list({
    'page_number': 1,
    'page_size': 100,
    'sort_by': 'name',
    'sort_direction': 'asc'
})

# Upsert a lead (create or update based on match)
upserted_lead = copper.leads.upsert({
    'name': 'Jane Smith',
    'email': {'email': 'jane@prospect.com', 'category': 'work'},
    'properties': {'match_field': 'email'}
})

# Convert lead to opportunity/person/company
conversion_result = copper.leads.convert(new_lead['id'], {
    'details': {
        'person': {'name': 'Jane Smith', 'contact_type_id': 1},
        'company': {'name': 'Prospect Corp'},
        'opportunity': {
            'name': 'Prospect Corp Deal',
            'pipeline_id': 12345,
            'monetary_value': 75000
        }
    }
})

# Get activities for a lead
lead_activities = copper.leads.activities(new_lead['id'], {
    'page_number': 1,
    'page_size': 50
})

# Get lead statuses and customer sources
statuses = copper.leads.statuses()
sources = copper.leads.customer_sources()

# Manage lead relationships
related = copper.leads.list_related(new_lead['id'])
copper.leads.relate(
    relation_id=98765,          # Custom field definition ID
    id=new_lead['id'],          # Lead ID
    target_type='company',      # Target entity type
    target_id=54321             # Target entity ID
)
copper.leads.unrelate(relation_link_id=11111)

# Delete a lead
copper.leads.delete(new_lead['id'])
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the lead.
- **name** (string) - The name of the lead.
- **email** (object) - Lead's email address.
- **phone_numbers** (array) - List of phone numbers.
- **address** (object) - Lead's address.
- **customer_source_id** (integer) - ID of the customer source.
- **monetary_value** (integer) - Monetary value associated with the lead.
- **tags** (array) - List of tags.

#### Response Example
```json
{
  "id": 12345,
  "name": "Jane Smith",
  "email": {"email": "jane@prospect.com", "category": "work"},
  "phone_numbers": [{"number": "555-1234", "category": "work"}],
  "address": {"city": "San Francisco", "state": "CA"},
  "customer_source_id": 12345,
  "monetary_value": 50000,
  "tags": ["enterprise", "inbound"]
}
```
```

--------------------------------

### Users API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Allows retrieval and searching of user information within your Copper account.

```APIDOC
## Users API

### Description
The Users resource allows you to retrieve user information and search for users in your Copper account.

### Method
GET

### Endpoint
/users/{id}
/users

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the user to retrieve.

#### Query Parameters
- **page_number** (integer) - Optional - The page number for pagination.
- **page_size** (integer) - Optional - The number of users per page.

### Request Example
```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Get a specific user by ID
user = copper.users.get(12345)
print(user)

# List/search users with pagination
users = copper.users.list({
    'page_number': 1,
    'page_size': 50
})
print(users)
```

### Response
#### Success Response (200)
- **id** (integer) - The user ID.
- **name** (string) - The name of the user.
- **email** (string) - The email address of the user.

#### Response Example
```json
{
  "id": 12345,
  "name": "John Doe",
  "email": "john@company.com",
  ...
}
```
```

--------------------------------

### List All Tags

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Retrieves a list of all tags available in the Copper CRM. This is useful for understanding existing tag structures or for populating tag selection interfaces.

```python
tags = copper.tags.list()
print(tags)
# Returns: [{'id': 1, 'name': 'enterprise'}, {'id': 2, 'name': 'priority'}, ...]
```

--------------------------------

### Webhooks API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Manage webhooks for receiving real-time event notifications from Copper.

```APIDOC
## Webhooks API

### Description
Manages webhooks for receiving real-time event notifications from Copper.

### Create a new webhook
```python
new_webhook = copper.webhooks.create({
    'target': 'https://your-server.com/copper-webhook',
    'type': 'lead',
    'event': 'new'  # Options: new, update, delete
})
print(f"Created webhook ID: {new_webhook['id']}")
```

### Update a webhook
```python
updated_webhook = copper.webhooks.update(new_webhook['id'], {
    'target': 'https://your-server.com/new-webhook-endpoint'
})
```

### Delete a webhook
```python
copper.webhooks.delete(new_webhook['id'])
```
```

--------------------------------

### Account API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Provides access to account-level information for the authenticated Copper account.

```APIDOC
## Account API

### Description
The Account resource provides access to account-level information for the authenticated Copper account.

### Method
GET

### Endpoint
/account

### Request Example
```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Get account details
account_info = copper.account.get()
print(account_info)
```

### Response
#### Success Response (200)
- **id** (integer) - The account ID.
- **name** (string) - The name of the account.

#### Response Example
```json
{
  "id": 12345,
  "name": "My Company",
  ...
}
```
```

--------------------------------

### Manage People Records with Copper SDK

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Use this snippet to perform CRUD operations on contact records. It includes creating, retrieving, updating, and deleting people, as well as bulk updates and searching.

```python
from copper_sdk import Copper

copper = Copper(email='user@company.com', token='api-token')

# Create a new person
new_person = copper.people.create({
    'name': 'Bob Johnson',
    'emails': [{'email': 'bob@client.com', 'category': 'work'}],
    'phone_numbers': [{'number': '555-5678', 'category': 'mobile'}],
    'address': {'street': '123 Main St', 'city': 'New York', 'state': 'NY'},
    'company_id': 12345,
    'contact_type_id': 1,
    'tags': ['customer', 'priority']
})
print(f"Created person ID: {new_person['id']}")

# Get a person by ID
person = copper.people.get(new_person['id'])

# Get a person by email address
person_by_email = copper.people.get_by_email('bob@client.com')

# Update a person
updated_person = copper.people.update(new_person['id'], {
    'title': 'VP of Engineering',
    'tags': ['customer', 'priority', 'decision-maker']
})

# Bulk update multiple people
bulk_result = copper.people.bulk_update([
    {'id': 11111, 'tags': ['updated']},
    {'id': 22222, 'tags': ['updated']},
    {'id': 33333, 'tags': ['updated']}
])

# Search/list people with filters
people = copper.people.list({
    'page_number': 1,
    'page_size': 100,
    'sort_by': 'first_name',
    'sort_direction': 'asc'
})

# Relate/unrelate a person to a company
copper.people.relate_to_company(new_person['id'], company_id=12345)
copper.people.unrelate_to_company(new_person['id'], company_id=12345)

# Get person activities
activities = copper.people.activities(new_person['id'])

# Get contact types
contact_types = copper.people.contact_types()

# Delete a person
copper.people.delete(new_person['id'])
```

--------------------------------

### Webhooks API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Resource for configuring event-driven notifications for CRM changes.

```APIDOC
## Webhooks API

### Description
The Webhooks resource allows you to configure event-driven notifications for CRM changes.

### Methods
- `list()`: List all configured webhooks.
- `get(webhook_id)`: Get a specific webhook by its ID.

### Parameters
#### Parameters for `get`
- **webhook_id** (integer) - Required - The ID of the webhook to retrieve.
```

--------------------------------

### Activities API

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Resource for tracking interactions and events related to CRM records.

```APIDOC
## Activities API

### Description
The Activities resource tracks all interactions and events related to CRM records including calls, meetings, notes, and custom activity types.

### Methods
- `create(activity_data)`: Create a new activity.
- `get(activity_id)`: Get an activity by its ID.
- `update(activity_id, update_data)`: Update an existing activity.
- `list(filters)`: Search or list activities with optional filters.
- `types()`: Get available activity types.
- `delete(activity_id)`: Delete an activity.

### Parameters
#### Request Body for `create` and `update`
- **type** (object) - Required - The type of activity, including `id` and `category`.
- **details** (string) - Required - Description of the activity.
- **parent** (object) - Required - The parent record, including `id` and `type`.
- **activity_date** (integer) - Required - Unix timestamp for the activity date.

#### Query Parameters for `list`
- **page_number** (integer) - Optional - The page number for pagination.
- **page_size** (integer) - Optional - The number of items per page.
- **full_result** (boolean) - Optional - Whether to return full results.
- **parent** (object) - Optional - Filter activities by a specific parent record (`id` and `type`).
- **minimum_activity_date** (integer) - Optional - Unix timestamp for the minimum activity date.
- **maximum_activity_date** (integer) - Optional - Unix timestamp for the maximum activity date.

### Request Example for `create`
```json
{
  "type": {"id": 1, "category": "user"},
  "details": "Had a productive discovery call",
  "parent": {"id": 12345, "type": "lead"},
  "activity_date": 1704067200
}
```

### Response Example for `create`
```json
{
  "id": "new_activity_id",
  "type": {"id": 1, "category": "user"},
  "details": "Had a productive discovery call",
  "parent": {"id": 12345, "type": "lead"},
  "activity_date": 1704067200
}
```
```

--------------------------------

### Update a Task

Source: https://context7.com/claimerapp/copper-sdk/llms.txt

Modifies an existing task. Provide the task ID and the fields to update, such as status or details.

```python
updated_task = copper.tasks.update(new_task['id'], {
    'status': 'Completed',
    'details': 'Proposal sent, demo scheduled for next week'
})
```