What we do
Tools
Industries
Department
How we workLet's talk →
Home/Copper/Copper API Docs, Headers and Webhook Limits
Copper CRM

Copper API: Three Headers, 180 Calls a Minute, and Webhooks That Fire Once

Your team works Copper from Gmail, but the API underneath is plain REST: one base URL, a few custom headers, JSON in and out. What catches a first integration out sits further in. Searches are POSTs, a search never returns past 100,000 records, and Copper sends each webhook at most once.

Copper API at a glance

Docs: developer.copper.com, covering every record type, webhooks and OAuth 2.0.

Key: generated in the Copper web app.

System settings API Keys Generate API key

Headers on every call: X-PW-AccessToken (the key), X-PW-Application: developer_api, X-PW-UserEmail (the email of the user who made the key) and Content-Type: application/json.

Base URL: https://api.copper.com/developer_api/v1/. GET /account is a quick way to prove the key works.

A new Copper key to a live webhook, in five steps

  1. 1

    Generate a key per integration

    System settings API Keys

    A user can hold several valid keys, and admins can see everyone's and create new ones. A key for each integration means you can revoke one without breaking the others.

  2. 2

    Fetch the account

    curl https://api.copper.com/developer_api/v1/account -H "X-PW-AccessToken: YOUR_KEY" -H "X-PW-Application: developer_api" -H "X-PW-UserEmail: you@yourcompany.com" returns your Copper account's details.

    Watch for: the email header. It has to match the user who generated the key.

  3. 3

    Search people

    POST /people/search with a JSON body such as {"page_size": 25, "sort_by": "name"}. Leads, companies and opportunities have search endpoints of the same shape.

    Watch for: the method. Searches, creates and updates all send their parameters as a JSON body, not a query string.

  4. 4

    Page through the results

    page_size defaults to 20 and goes up to 200. Start page_number at 1 and count up. The X-PW-TOTAL response header gives an upper bound on matches, and Copper's docs recommend sorting, for example by date_modified descending.

    Watch for: the ceiling. A search returns only the first 100,000 records whatever the page number, so split a large pull into date ranges.

  5. 5

    Subscribe to a webhook

    POST /webhooks with a target (https only), a type such as opportunity or person, and an event of new, update or delete. Optional secret and headers values are passed to your endpoint, which is how you tell Copper's calls from anyone else's.

    Watch for: the cap of 100 active subscriptions per account, one per type and event pair you need.

Copper behaviors that drop updates without an error

A webhook that failed once won't come back

How you'll know: A deal moved stage in Copper, the other system never heard, and nothing shows a retry.

Fix: Copper fires each notification at most once and doesn't retry, whatever your endpoint answers. Run a scheduled search sorted by date_modified and reconcile anything changed since the last run.

Notifications that carry IDs, not records

How you'll know: The handler expects deal fields and finds only an array of numbers.

Fix: Each notification sends between 1 and 30 record IDs. Fetch each record before acting on it, and remember every notification counts toward the rate limit too.

429s halfway through a bulk job

How you'll know: A load or cleanup runs fine for a minute, then every call fails.

Fix: The limit is 180 requests a minute on a rolling window, and bulk endpoints are capped at 3 a second on their own. Space calls out, and back off on a 429 rather than retrying straight away.

Gaps after a big import

How you'll know: After a mass update, only some records reached the downstream system.

Fix: Notifications are capped at 600 a minute and 1,800 per 10 minutes per account. After any bulk change, run the catch-up search instead of trusting the webhook stream to cover it.

Copper API, before the first commit

Where do I find Copper's API documentation?

At developer.copper.com. It covers authentication, requests, paging, each record type, webhooks and OAuth 2.0. Your key comes from System settings, then API Keys, inside the Copper web app.

Does Copper have a public API?

Yes, a REST API with JSON responses, open to any Copper account through a key generated in settings, with no separate developer sign-up. For an app that other Copper accounts will install, Copper prefers OAuth 2.0 over keys.

What can I connect to Copper besides its built-in Google Workspace and marketplace integrations?

Copper's directory already covers tools like Xero, QuickBooks, Zapier, Slack, DocuSign and PandaDoc, and most listings need the Professional plan or higher, so check what Copper connects to first. Past that, anything with an API can be joined: an ERP, a scheduling system, an internal database, built on Copper's API with webhooks and a catch-up search.

Do I need to be a developer to use Copper's API?

Someone on the project does. The API is conventional REST, but the code has to set the headers, page through searches, stay under the limits and recover webhooks that never arrived. That's a modest lift for someone who's built an integration before, and a slow one for anyone who hasn't.

Who builds Copper API integrations when no listed connector fits?

That's the work n-frames takes on for Copper teams: a won opportunity passed to the system that delivers the work, records kept matching between Copper and an ERP or database, and webhook receivers backed by a scheduled sweep so nothing is lost.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.