A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Copper API is how an app or AI agent works with a Copper account: searching people and companies, creating a lead, advancing an opportunity through a pipeline, or logging an activity against a record. Access is granted through an API key tied to a user, so a call can reach whatever that user can reach, because Copper keys are account-level and carry no per-method permissions. Copper can also push a record change to a registered endpoint, so an integration learns about activity without polling.
How an app or AI agent connects to Copper determines what it can reach. There is a route for making calls, a route for receiving events, and each is governed by the key behind it and the access of the user who owns that key.
The REST API takes JSON request bodies, returns JSON, and lists records by POSTing filters to a /search endpoint with page_number and page_size paging, at https://api.copper.com/developer_api/v1. A call authenticates with the three X-PW headers carrying an API key, the key owner's email, and the application name.
Copper POSTs a notification to a registered HTTPS endpoint when a record changes. A subscription is created via POST /webhooks with a target URL, a record type, and an event (new, update, or delete), and an optional secret lets the receiver verify the payload. Only https:// targets are accepted, and an account may hold up to 100 active subscriptions.
A user generates an API key in the app, and every request sends it in X-PW-AccessToken alongside X-PW-UserEmail (the key owner's email) and X-PW-Application set to developer_api. The key has no scopes; it carries the full access of the owning user, so a key's reach equals that user's role. A user can hold several keys, and admins can generate keys for any user.
Copper offers an OAuth 2.0 authorization-code flow as the preferred method for partner integrations, where a user grants an app access and the app receives an access token instead of handling a raw key. The resulting token still acts as the granting user, with no per-method scopes, so its reach is that user's role.
The Copper API is split into areas an agent can act on, like people, companies, leads, opportunities, tasks, and activities. Each area has its own methods, and a write changes records other people in the account see.
Methods for working with People records (individual contacts).
Methods for working with Company records (organizations).
Methods for working with Lead records (unqualified prospects).
Methods for working with Opportunity records (deals in a pipeline).
Methods for working with Task records.
Methods for logging and reading Activities against records.
Methods for working with Project records.
Methods for reading Pipelines and their stages.
Methods for reading Custom Field Definitions.
Methods for reading the account and its users.
Methods for managing webhook subscriptions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PeopleMethods for working with People records (individual contacts).6 | ||||||
| POST | /people/search | List and filter People records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Reaches whatever the key's owning user can see. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /people/{id} | Fetch a single Person record by its id. | read | — | Current | |
Read-only. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /people/fetch_by_email | Fetch a Person record by email address (email sent in the request body). | read | — | Current | |
Read-only; a POST because the email is sent in the JSON body. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /people | Create a new Person record. | write | — | Current | |
A core write; the new record is visible to the account. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook event person.newRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /people/{id} | Update fields on an existing Person record. | write | — | Current | |
A core write; Copper uses PUT for updates. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook event person.updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /people/{id} | Delete a Person record. | write | — | Current | |
Irreversible removal of the record. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook event person.deleteRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CompaniesMethods for working with Company records (organizations).4 | ||||||
| POST | /companies/search | List and filter Company records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /companies/{id} | Fetch a single Company record by its id. | read | — | Current | |
Read-only. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /companies | Create a new Company record. | write | — | Current | |
A core write; the new record is visible to the account. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /companies/{id} | Update fields on an existing Company record. | write | — | Current | |
A core write; Copper uses PUT for updates. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LeadsMethods for working with Lead records (unqualified prospects).4 | ||||||
| POST | /leads/search | List and filter Lead records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /leads | Create a new Lead record. | write | — | Current | |
A core write; the new record is visible to the account. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event lead.newRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /leads/{id} | Update fields on an existing Lead record. | write | — | Current | |
A core write; Copper uses PUT for updates. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /leads/{id}/convert | Convert a Lead into a Person, optionally also creating a Company and an Opportunity. | write | — | Current | |
Creates a Person (and optionally a Company and Opportunity) and deletes the original Lead. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OpportunitiesMethods for working with Opportunity records (deals in a pipeline).3 | ||||||
| POST | /opportunities/search | List and filter Opportunity records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /opportunities | Create a new Opportunity record in a pipeline. | write | — | Current | |
A core write; the primary-contact field became optional on 2025-08-15. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /opportunities/{id} | Update fields on an existing Opportunity, including its pipeline stage. | write | — | Current | |
A core write; advancing a stage moves the deal in the pipeline. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook event opportunity.updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksMethods for working with Task records.2 | ||||||
| POST | /tasks/search | List and filter Task records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tasks | Create a new Task record. | write | — | Current | |
A core write; the new task is visible to the account. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ActivitiesMethods for logging and reading Activities against records.2 | ||||||
| POST | /activities | Log a new Activity (a note or interaction) against a record. | write | — | Current | |
Only User-type activities can be created; System-type activities are read-only. Acts onactivity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /activities/search | List and filter Activity records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Acts onactivity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsMethods for working with Project records.1 | ||||||
| POST | /projects/search | List and filter Project records, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PipelinesMethods for reading Pipelines and their stages.2 | ||||||
| GET | /pipelines | List the Pipelines configured in the account. | read | — | Current | |
Read-only metadata describing how opportunities are organized. Acts onpipeline Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pipeline_stages | List the Pipeline Stages configured in the account. | read | — | Current | |
Read-only metadata; the stages an opportunity can move through. Acts onpipeline_stage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom FieldsMethods for reading Custom Field Definitions.1 | ||||||
| GET | /custom_field_definitions | List the Custom Field Definitions configured in the account. | read | — | Current | |
Read-only metadata describing the account's custom fields and which records they apply to. Acts oncustom_field_definition Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Account & UsersMethods for reading the account and its users.3 | ||||||
| GET | /account | Fetch details about the Copper account, like its name and timezone. | read | — | Current | |
Read-only. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users/search | List the users in the account, with sorting and paging in the request body. | read | — | Current | |
Read-only; a POST because filters and paging go in the JSON body. Useful for detecting deactivations or role changes. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/me | Fetch the user that owns the API key or token making the call. | read | — | Current | |
Read-only; identifies which user a key acts as. Acts onuser Permission (capability)None required VersionIntroduced 2024-06-19 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for managing webhook subscriptions.3 | ||||||
| POST | /webhooks | Create a webhook subscription for a record type and event (new, update, or delete). | write | — | Current | |
Only https:// targets are accepted; an account may hold up to 100 active subscriptions. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /webhooks | List the account's active webhook subscriptions. | read | — | Current | |
Read-only. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/{id} | Delete a webhook subscription so its events stop being pushed. | write | — | Current | |
Stops delivery for that subscription. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Copper can notify an app when a record changes, like a person being created or an opportunity being updated. It sends the record type, the event, and the record id to a registered HTTPS endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
person / new | A new Person record was created in the account. | /people |
person / update | A field on an existing Person record changed. | /people/{id} |
person / delete | A Person record was removed. | /people/{id} |
lead / new | A new Lead record was created. | /leads |
opportunity / update | A field on an existing Opportunity changed, like its stage or value. | /opportunities/{id} |
Copper limits how fast an app can call, by a per-minute request count across the account, with a separate per-second ceiling on the bulk methods.
Copper meters requests by a flat per-minute count across the account, not by a per-method cost or point weighting. All API calls share a limit of 180 requests per minute, and the bulk methods carry a separate ceiling of 3 requests per second. Going over either returns HTTP 429, at which point a caller backs off and retries.
A /search endpoint is page-based, not cursor-based. The request body takes page_number (starting at 1) and page_size to walk through results, alongside sort_by and sort_direction to order them. A page that returns fewer than page_size records, or an empty page, signals the end of the results.
A /search request returns up to 200 records per page, the maximum value of page_size. An account may hold up to 100 active webhook subscriptions at once.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, for example invalid JSON or a missing required parameter. | Fix the request body and resend. The request is not retryable as-is. |
| 401 | Unauthorized | Authentication failed, for example a missing or invalid X-PW-AccessToken or X-PW-UserEmail header. | Confirm all three X-PW headers are present and the key and email are valid, then resend. |
| 403 | Forbidden | The authenticated user does not have access to the requested record or action. | Use a key owned by a user whose role allows the action, or request the access in the app. |
| 404 | Not Found | The requested record does not exist, or is not visible to the authenticated user. | Verify the record id and that the owning user can see it. |
| 422 | Unprocessable Entity | The request was well-formed but failed validation, for example an invalid webhook target or a field value Copper rejects. | Read the validation message, correct the offending field, and resend. |
| 429 | Too Many Requests | The 180-per-minute account limit, or the 3-per-second bulk limit, was exceeded. | Back off and retry, smoothing the request rate to stay under the limit. |
| 500 | Internal Server Error | An error on Copper's side. It is rare. | Retry with backoff, and contact Copper support if it persists. |
Copper exposes one API version in the path and ships dated, backward-compatible changes through its changelog rather than minting new version strings.
Copper exposes one version, v1, in the request path, and ships dated backward-compatible changes through its changelog rather than minting new version strings. Recent additions include account-detail fields, optional fields on opportunity creation, and a field-layouts endpoint.
A run of backward-compatible additions through late 2024, covering pipelines, opportunity search, and primary contacts.
Mid-2023 introduced the beta bulk APIs, custom webhook headers, and OAuth 2.0 as the preferred method for partner integrations.
There is one version to target; track the changelog for new fields and methods.
Copper API changelog ↗Bollard AI sits between a team's AI agents and Copper. Grant each agent exactly the access it needs, read or write, record type by record type, and every call is checked and logged.