# Copper > Read and write the Copper CRM: find, create and update people, companies and deals, raise and convert leads, keep tasks against them and log every call, meeting and note. App · CRM Systems · 20 actions. Web page: https://docs.lodol.com/docs/integrations/copper ## Actions ### Convert lead Turn a lead into a person, and optionally a company and a deal at the same time. Copper deletes the lead once this succeeds, so use the person's id from here on. Give the company either an id or a name, never both - an unmatched name makes a new company. **Inputs** - Lead ID (`lead_id`, text, required): The lead to convert. 'Search leads' and 'Create lead' return this id. It stops existing afterwards. - Person's name (`person_name`, text): What to call the person this creates. Leave empty to keep the lead's own name. - Existing company ID (`company_id`, text): File the new person against a company that already exists. Do not also give a company name. - Company name (`company_name`, text): Match or create a company by name. Copper matches loosely unless you tick exact matching, and creates a new company when nothing matches. - Match the company name exactly (`company_exact_match`, true/false): Only match a company whose name is exactly what you typed, instead of Copper's fuzzy match. Default: `false`. - Opportunity name (`opportunity_name`, text): Open a deal as part of the conversion. Leave empty to convert without one. - Opportunity pipeline (`pipeline_id`, text): Which pipeline the new deal belongs in. Pick it before the stage. - Opportunity stage (`pipeline_stage_id`, text): Which stage of that pipeline the new deal starts in. - Opportunity value (`monetary_value`, number): What the new deal is worth. - Opportunity owner (`assignee_id`, text): Which Copper user owns the new deal. **Outputs** - `company` (object): The company, when one was matched or made - `company_id` (number): The company's id, when there is one - `name` (text): The new person's name - `opportunity` (object): The deal, when one was opened - `opportunity_id` (number): The deal's id, when there is one - `person` (object): The person the lead became - `person_id` (number): The new person's id - use this from here on **Example output** ```json { "company": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Manufacturing partner.", "email_domain": "example.com", "id": 12030795, "interaction_count": 7, "name": "Analytical Engines", "phone_numbers": [ { "category": "work", "number": "415-555-0100" } ], "primary_contact_id": 27140359, "socials": [], "tags": [ "lodol-qa" ], "websites": [ { "category": "work", "url": "https://example.com" } ] }, "company_id": 12030795, "name": "Ada Lovelace", "opportunity": { "assignee_id": 137658, "close_date": "1/23/2027", "company_id": 12030795, "company_name": "Analytical Engines", "custom_fields": [], "customer_source_id": 331242, "date_created": 1747699200, "date_modified": 1757894400, "details": "Pilot agreed, waiting on procurement.", "id": 14341018, "interaction_count": 4, "loss_reason_id": null, "monetary_value": 25000, "name": "Difference Engine rollout", "pipeline_id": 213214, "pipeline_is_revenue": true, "pipeline_stage_id": 987790, "pipeline_type": "opportunity", "primary_contact_id": 27140359, "priority": "High", "status": "Open", "tags": [ "lodol-qa" ], "win_probability": 40 }, "opportunity_id": 14341018, "person": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "company_id": 12030795, "company_name": "Analytical Engines", "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Met at the analytics conference.", "emails": [ { "category": "work", "email": "ada@example.com" } ], "first_name": "Ada", "id": 27140359, "interaction_count": 3, "last_name": "Lovelace", "name": "Ada Lovelace", "phone_numbers": [ { "category": "work", "number": "415-555-0110" } ], "socials": [], "tags": [ "lodol-qa" ], "title": "Head of Analysis", "websites": [] }, "person_id": 27140359 } ``` ### Create company Add a company to Copper. Only the name is required. Setting the email domain is what lets Copper file later contacts against it automatically. **Inputs** - Name (`name`, text, required): The company's name. - Email domain (`email_domain`, text): The domain this company's people use, for example example.com. - Description (`details`, text): Free-text description stored on the record. - Phone numbers (`phone_numbers`, list): Phone numbers. Copper replaces the whole list with what you send. - Phone category (`phone_category`, text): How Copper labels the phone numbers sent above. One of: `mobile`, `work`, `home`, `other`. - Websites (`websites`, list): Website addresses. Copper replaces the whole list with what you send. - Website category (`website_category`, text): How Copper labels the websites sent above. One of: `work`, `personal`, `other`. - Social profiles (`socials`, list): Social profile URLs. Copper replaces the whole list with what you send. - Social network (`social_category`, text): Which network the profile URLs above belong to. One of: `linkedin`, `twitter` (X / Twitter), `googleplus` (Google+), `facebook`, `youtube`, `quora`, `foursquare`, `klout`, `gravatar`, `other`. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Contact type (`contact_type_id`, text): This account's own contact type, such as Potential Customer. - Primary contact (person ID) (`primary_contact_id`, text): The person who is this company's main contact. 'Create person' and 'Search people' return this id. - Street (`address_street`, text): Street address of the company. - City (`address_city`, text): City of the company. - State or region (`address_state`, text): State, province or region of the company. - Postal code (`address_postal_code`, text): Postal or ZIP code of the company. - Country (`address_country`, text): Country, written however this Copper account writes it - Copper accepts both 'United States' and 'US' and stores what it is given. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `company` (object): The company, as Copper returned it - `company_id` (number): The company's id - `name` (text): The company's name **Example output** ```json { "company": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Manufacturing partner.", "email_domain": "example.com", "id": 12030795, "interaction_count": 7, "name": "Analytical Engines", "phone_numbers": [ { "category": "work", "number": "415-555-0100" } ], "primary_contact_id": 27140359, "socials": [], "tags": [ "lodol-qa" ], "websites": [ { "category": "work", "url": "https://example.com" } ] }, "company_id": 12030795, "name": "Analytical Engines" } ``` ### Create lead Add a lead to Copper - an unqualified contact that has not become a person yet. Only the name is required. A lead's company is just a name; it becomes a real Company record when the lead is converted. **Inputs** - Full name (`name`, text, required): The lead's full name. - Email address (`email`, text): The lead's email address. Copper stores one address on a lead, unlike a person. - Email category (`email_category`, text): How Copper labels the email addresses sent above. One of: `work`, `personal`, `other`. - Phone numbers (`phone_numbers`, list): Phone numbers. Copper replaces the whole list with what you send. - Phone category (`phone_category`, text): How Copper labels the phone numbers sent above. One of: `mobile`, `work`, `home`, `other`. - Company name (`company_name`, text): Where the lead works, as plain text. Leads are not attached to a Company record until they are converted. - Job title (`title`, text): The lead's job title. - Description (`details`, text): Free-text description stored on the record. - Street (`address_street`, text): Street address of the lead. - City (`address_city`, text): City of the lead. - State or region (`address_state`, text): State, province or region of the lead. - Postal code (`address_postal_code`, text): Postal or ZIP code of the lead. - Country (`address_country`, text): Country, written however this Copper account writes it - Copper accepts both 'United States' and 'US' and stores what it is given. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Customer source (`customer_source_id`, text): Where this lead came from. - Status (`status`, text): The lead's status, from this account's own list. Leave it empty to take the account default. - Value (`monetary_value`, number): What the lead is thought to be worth. - Websites (`websites`, list): Website addresses. Copper replaces the whole list with what you send. - Website category (`website_category`, text): How Copper labels the websites sent above. One of: `work`, `personal`, `other`. - Social profiles (`socials`, list): Social profile URLs. Copper replaces the whole list with what you send. - Social network (`social_category`, text): Which network the profile URLs above belong to. One of: `linkedin`, `twitter` (X / Twitter), `googleplus` (Google+), `facebook`, `youtube`, `quora`, `foursquare`, `klout`, `gravatar`, `other`. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `lead` (object): The lead, as Copper returned it - `lead_id` (number): The lead's id - `name` (text): The lead's name **Example output** ```json { "lead": { "address": null, "assignee_id": 137658, "company_name": "Naval Systems", "custom_fields": [], "customer_source_id": 331240, "date_created": 1747699200, "date_modified": 1757894400, "details": "Downloaded the whitepaper.", "email": { "category": "work", "email": "grace@example.com" }, "id": 9123456, "interaction_count": 1, "monetary_unit": "USD", "monetary_value": 5000, "name": "Grace Hopper", "phone_numbers": [], "socials": [], "status": "New", "status_id": 208231, "tags": [ "lodol-qa" ], "title": "Rear Admiral", "websites": [] }, "lead_id": 9123456, "name": "Grace Hopper" } ``` ### Create opportunity Open a deal in Copper. Only the name is required - a primary contact has been optional since August 2025. Choose the pipeline first and the stage list follows it. **Inputs** - Name (`name`, text, required): What the deal is called. - Primary contact (person ID) (`primary_contact_id`, text): The person this deal is with. Optional since August 2025, whatever Copper's older docs say. - Company ID (`company_id`, text): The company this deal is with. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Pipeline (`pipeline_id`, text): Which pipeline the deal belongs in. Pick this before the stage - the stage list is this pipeline's. - Stage (`pipeline_stage_id`, text): Which stage of that pipeline the deal starts in. A stage from a different pipeline is rejected. - Customer source (`customer_source_id`, text): Where this deal came from. - Loss reason (`loss_reason_id`, text): Only meaningful when the status is Lost. - Status (`status`, text): The deal's state. Copper defaults new deals to Open. One of: `Open`, `Won`, `Lost`, `Abandoned`. - Priority (`priority`, text): How urgent the deal is. One of: `None`, `Low`, `Medium`, `High`. - Value (`monetary_value`, number): What the deal is worth, in the account's currency. - Win probability (`win_probability`, number): Chance of winning, 0-100. From 0 to 100. - Expected close date (`close_date`, date): When the deal is expected to close. - Description (`details`, text): Free-text description stored on the record. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `name` (text): The opportunity's name - `opportunity` (object): The opportunity, as Copper returned it - `opportunity_id` (number): The opportunity's id **Example output** ```json { "name": "Difference Engine rollout", "opportunity": { "assignee_id": 137658, "close_date": "1/23/2027", "company_id": 12030795, "company_name": "Analytical Engines", "custom_fields": [], "customer_source_id": 331242, "date_created": 1747699200, "date_modified": 1757894400, "details": "Pilot agreed, waiting on procurement.", "id": 14341018, "interaction_count": 4, "loss_reason_id": null, "monetary_value": 25000, "name": "Difference Engine rollout", "pipeline_id": 213214, "pipeline_is_revenue": true, "pipeline_stage_id": 987790, "pipeline_type": "opportunity", "primary_contact_id": 27140359, "priority": "High", "status": "Open", "tags": [ "lodol-qa" ], "win_probability": 40 }, "opportunity_id": 14341018 } ``` ### Create person Add a person to Copper. Only the name is required. An email address is worth setting: it is the unique key Copper looks people up by. **Inputs** - Full name (`name`, text, required): The person's full name, for example Ada Lovelace. - Email addresses (`emails`, list): The person's email addresses. Copper treats the address as this person's unique key. - Email category (`email_category`, text): How Copper labels the email addresses sent above. One of: `work`, `personal`, `other`. - Phone numbers (`phone_numbers`, list): Phone numbers. Copper replaces the whole list with what you send. - Phone category (`phone_category`, text): How Copper labels the phone numbers sent above. One of: `mobile`, `work`, `home`, `other`. - Job title (`title`, text): The person's job title. - Description (`details`, text): Free-text description stored on the record. - Company ID (`company_id`, text): The company this person works at. 'Search companies' and 'Create company' both return this id. Set it here if you can - 'Update person' cannot change it later. - Contact type (`contact_type_id`, text): This account's own contact type, such as Potential Customer. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Street (`address_street`, text): Street address of the person. - City (`address_city`, text): City of the person. - State or region (`address_state`, text): State, province or region of the person. - Postal code (`address_postal_code`, text): Postal or ZIP code of the person. - Country (`address_country`, text): Country, written however this Copper account writes it - Copper accepts both 'United States' and 'US' and stores what it is given. - Websites (`websites`, list): Website addresses. Copper replaces the whole list with what you send. - Website category (`website_category`, text): How Copper labels the websites sent above. One of: `work`, `personal`, `other`. - Social profiles (`socials`, list): Social profile URLs. Copper replaces the whole list with what you send. - Social network (`social_category`, text): Which network the profile URLs above belong to. One of: `linkedin`, `twitter` (X / Twitter), `googleplus` (Google+), `facebook`, `youtube`, `quora`, `foursquare`, `klout`, `gravatar`, `other`. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `name` (text): The person's name - `person` (object): The person, as Copper returned it - `person_id` (number): The person's id **Example output** ```json { "name": "Ada Lovelace", "person": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "company_id": 12030795, "company_name": "Analytical Engines", "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Met at the analytics conference.", "emails": [ { "category": "work", "email": "ada@example.com" } ], "first_name": "Ada", "id": 27140359, "interaction_count": 3, "last_name": "Lovelace", "name": "Ada Lovelace", "phone_numbers": [ { "category": "work", "number": "415-555-0110" } ], "socials": [], "tags": [ "lodol-qa" ], "title": "Head of Analysis", "websites": [] }, "person_id": 27140359 } ``` ### Create task Add a task, optionally about a person, company, deal, lead or project. Only the name is required. Copper stamps the completed date itself when a task moves to Completed. **Inputs** - Task (`name`, text, required): What needs doing. - Related to (`related_resource_type`, text): What kind of record this task is about. Fill this in together with the id beside it, or leave both empty. One of: `person`, `lead`, `company`, `opportunity`, `project`. - Related record ID (`related_resource_id`, text): The id of that record. Paste the app.copper.com link if that is what you have. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Due (`due_date`, date and time): When the task is due. - Remind at (`reminder_date`, date and time): When Copper should remind the owner. - Priority (`priority`, text): How urgent the task is. One of: `None`, `Low`, `Medium`, `High`. - Status (`status`, text): Open or Completed. Copper stamps the completed date itself, so there is nothing to set for that. One of: `Open`, `Completed`. - Description (`details`, text): Free-text description stored on the record. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `name` (text): The task's name - `task` (object): The task, as Copper returned it - `task_id` (number): The task's id **Example output** ```json { "name": "Send the pilot summary", "task": { "assignee_id": 137658, "completed_date": null, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Include the rollout timeline.", "due_date": 1758067200, "id": 6612345, "name": "Send the pilot summary", "priority": "High", "related_resource": { "id": 27140359, "type": "person" }, "reminder_date": 1757980800, "status": "Open", "tags": [ "lodol-qa" ] }, "task_id": 6612345 } ``` ### Find person by email Look a person up by email address - the unique key on Copper People records. Reports 'found' as false when nobody has that address, so a workflow can branch on it instead of failing. **Inputs** - Email address (`email`, text, required): The address to look up. It must match exactly. **Outputs** - `found` (true/false): Whether anyone in Copper has that address - `name` (text): The person's name - `person` (object): The person, when one was found - `person_id` (number): The person's id, when one was found **Example output** ```json { "found": true, "name": "Ada Lovelace", "person": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "company_id": 12030795, "company_name": "Analytical Engines", "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Met at the analytics conference.", "emails": [ { "category": "work", "email": "ada@example.com" } ], "first_name": "Ada", "id": 27140359, "interaction_count": 3, "last_name": "Lovelace", "name": "Ada Lovelace", "phone_numbers": [ { "category": "work", "number": "415-555-0110" } ], "socials": [], "tags": [ "lodol-qa" ], "title": "Head of Analysis", "websites": [] }, "person_id": 27140359 } ``` ### Get company Read one company by id, with every field Copper holds. **Inputs** - Company ID (`company_id`, text, required): The company to read. Paste the app.copper.com link if that is what you have. 'Search companies' returns these in 'ids'. **Outputs** - `company` (object): The company, as Copper returned it - `company_id` (number): The company's id - `name` (text): The company's name **Example output** ```json { "company": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Manufacturing partner.", "email_domain": "example.com", "id": 12030795, "interaction_count": 7, "name": "Analytical Engines", "phone_numbers": [ { "category": "work", "number": "415-555-0100" } ], "primary_contact_id": 27140359, "socials": [], "tags": [ "lodol-qa" ], "websites": [ { "category": "work", "url": "https://example.com" } ] }, "company_id": 12030795, "name": "Analytical Engines" } ``` ### Get opportunity Read one deal by id, including its pipeline, stage, status, value and custom fields. **Inputs** - Opportunity ID (`opportunity_id`, text, required): The deal to read. Paste the app.copper.com link if that is what you have. 'Search opportunities' returns these in 'ids'. **Outputs** - `name` (text): The opportunity's name - `opportunity` (object): The opportunity, as Copper returned it - `opportunity_id` (number): The opportunity's id **Example output** ```json { "name": "Difference Engine rollout", "opportunity": { "assignee_id": 137658, "close_date": "1/23/2027", "company_id": 12030795, "company_name": "Analytical Engines", "custom_fields": [], "customer_source_id": 331242, "date_created": 1747699200, "date_modified": 1757894400, "details": "Pilot agreed, waiting on procurement.", "id": 14341018, "interaction_count": 4, "loss_reason_id": null, "monetary_value": 25000, "name": "Difference Engine rollout", "pipeline_id": 213214, "pipeline_is_revenue": true, "pipeline_stage_id": 987790, "pipeline_type": "opportunity", "primary_contact_id": 27140359, "priority": "High", "status": "Open", "tags": [ "lodol-qa" ], "win_probability": 40 }, "opportunity_id": 14341018 } ``` ### Get person Read one person by id, with every field Copper holds on them including custom fields. **Inputs** - Person ID (`person_id`, text, required): The person to read. Paste the app.copper.com link if that is what you have - the id is read out of it. 'Search people' returns these in 'ids'. **Outputs** - `name` (text): The person's name - `person` (object): The person, as Copper returned it - `person_id` (number): The person's id **Example output** ```json { "name": "Ada Lovelace", "person": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "company_id": 12030795, "company_name": "Analytical Engines", "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Met at the analytics conference.", "emails": [ { "category": "work", "email": "ada@example.com" } ], "first_name": "Ada", "id": 27140359, "interaction_count": 3, "last_name": "Lovelace", "name": "Ada Lovelace", "phone_numbers": [ { "category": "work", "number": "415-555-0110" } ], "socials": [], "tags": [ "lodol-qa" ], "title": "Head of Analysis", "websites": [] }, "person_id": 27140359 } ``` ### Log activity Write a note, call or meeting onto a Copper record. The type list is this account's own; leave the date empty and Copper stamps the moment the step ran. **Inputs** - Logged against (`parent_type`, text, required): What kind of record this activity is about. One of: `person`, `lead`, `company`, `opportunity`, `project`. - Record ID (`parent_id`, text, required): The record to log against. Paste the app.copper.com link if that is what you have. - Activity type (`activity_type_id`, text, required): Which kind of activity - Note, Phone Call, Meeting, or whatever this account has added. - Notes (`details`, text, required): What happened. This is the body of the activity. - When it happened (`activity_date`, date and time): When the call, meeting or note happened. Leave empty for now. **Outputs** - `activity` (object): The activity, as Copper returned it - `activity_id` (number): The activity's id - `name` (text): The activity's name **Example output** ```json { "activity": { "activity_date": 1757894400, "date_created": 1757894400, "date_modified": 1757894400, "details": "Called to confirm the pilot dates.", "id": 4123456, "new_value": null, "old_value": null, "parent": { "id": 27140359, "type": "person" }, "type": { "category": "user", "id": 0 }, "user_id": 137658 }, "activity_id": 4123456, "name": null } ``` ### Search activities Read the activity log - every note, call and meeting, optionally just the ones on one record or in one date range. **Inputs** - Logged against (`parent_type`, text): Only return activities on this kind of record. Fill this in together with the id beside it, or leave both empty for the whole account. One of: `person`, `lead`, `company`, `opportunity`, `project`. - Record ID (`parent_id`, text): The record whose activities you want. - Activity types (`activity_type_ids`, list): Only return these kinds of activity. The list holds the activities people log; the ones Copper writes itself when a record changes come back in the results but cannot be filtered on here. - Happened on or after (`minimum_activity_date`, date): Only activities dated on or after this date. - Happened on or before (`maximum_activity_date`, date): Only activities dated on or before this date. - Faster, at the cost of duplicates (`full_result`, true/false): Copper's own trade-off: switching this on makes the search faster but may return the same activity more than once. Off by default. Default: `false`. - Page (`page_number`, number): Which page of results to read, starting at 1. Copper never returns more than the first 100,000 matches however far you page. From 1 to 100000. Default: `1`. - Results per page (`page_size`, number): How many records to return, 1-200. Defaults to 20. From 1 to 200. Default: `20`. **Outputs** - `activities` (list): The activities on this page - `count` (number): How many came back on this page - `ids` (list): Just the ids, for chaining into a later step - `page_number` (number): The page that was read - `page_size` (number): How many were asked for - `total` (number): Copper's upper-bound count of every match, from the X-PW-TOTAL header **Example output** ```json { "activities": [ { "activity_date": 1757894400, "date_created": 1757894400, "date_modified": 1757894400, "details": "Called to confirm the pilot dates.", "id": 4123456, "new_value": null, "old_value": null, "parent": { "id": 27140359, "type": "person" }, "type": { "category": "user", "id": 0 }, "user_id": 137658 } ], "count": 1, "ids": [ 4123456 ], "page_number": 1, "page_size": 20, "total": 1 } ``` ### Search companies Find companies by name, email domain, owner, contact type, location or tag. Every filter you fill in has to match; tags match any one of them. **Inputs** - Name (`name`, text): Company name search. Partial names match. - Email domain (`email_domain`, text): One domain, for example example.com. Copper takes a single domain here, not a list. - Contact types (`contact_type_ids`, list): Only return records with one of these contact types. - Owners (`assignee_ids`, list): Only return records owned by these Copper users. Choose 'Unassigned' for the records nobody owns. - City (`city`, text): Only return companies in this city. - State or region (`state`, text): Only return companies in this state or region. - Postal code (`postal_code`, text): Only return companies with this postal code. - Tags (`tags`, list): Only return records carrying any of these tags. Tags are the one filter that widens rather than narrows: a record with any one of them matches, while every other filter on this step has to match as well. - Last contacted on or after (`minimum_interaction_date`, date): Only companies interacted with on or after this date. - Last contacted on or before (`maximum_interaction_date`, date): Only companies interacted with on or before this date. - Sort direction (`sort_direction`, text): Ascending or descending. Copper sorts ascending by default. One of: `asc` (Ascending), `desc` (Descending). - Page (`page_number`, number): Which page of results to read, starting at 1. Copper never returns more than the first 100,000 matches however far you page. From 1 to 100000. Default: `1`. - Results per page (`page_size`, number): How many records to return, 1-200. Defaults to 20. From 1 to 200. Default: `20`. **Outputs** - `companies` (list): The companies on this page - `count` (number): How many came back on this page - `ids` (list): Just the ids, for chaining into a later step - `page_number` (number): The page that was read - `page_size` (number): How many were asked for - `total` (number): Copper's upper-bound count of every match, from the X-PW-TOTAL header **Example output** ```json { "companies": [ { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Manufacturing partner.", "email_domain": "example.com", "id": 12030795, "interaction_count": 7, "name": "Analytical Engines", "phone_numbers": [ { "category": "work", "number": "415-555-0100" } ], "primary_contact_id": 27140359, "socials": [], "tags": [ "lodol-qa" ], "websites": [ { "category": "work", "url": "https://example.com" } ] } ], "count": 1, "ids": [ 12030795 ], "page_number": 1, "page_size": 20, "total": 1 } ``` ### Search leads Find leads by name, email, phone, status, source, owner, location or tag. Converted leads are left out unless you ask for them. **Inputs** - Name (`name`, text): Lead name search. Partial names match. - Email address (`email`, text): One email address. Copper takes a single address here, not a list. - Phone number (`phone_number`, text): Only return leads with this phone number. - Owners (`assignee_ids`, list): Only return records owned by these Copper users. Choose 'Unassigned' for the records nobody owns. - Statuses (`status_ids`, list): Only return leads in these statuses. The list is this account's own - leads are the one place Copper stores the status word on the record but filters by its id. - Customer sources (`customer_source_ids`, list): Only return leads from these sources. - City (`city`, text): Only return leads in this city. - State or region (`state`, text): Only return leads in this state or region. - Postal code (`postal_code`, text): Only return leads with this postal code. - Country code (`country`, text): Two-letter country code, for example US or GB. - Tags (`tags`, list): Only return records carrying any of these tags. Tags are the one filter that widens rather than narrows: a record with any one of them matches, while every other filter on this step has to match as well. - Following (`followed`, text): Narrow to the records the connected Copper user follows. One of: `1` (Only records I follow), `2` (Only records I do not follow). - Value at least (`minimum_monetary_value`, number): Only leads worth at least this much. - Value at most (`maximum_monetary_value`, number): Only leads worth at most this much. - Created on or after (`minimum_created_date`, date): Only leads created on or after this date. - Created on or before (`maximum_created_date`, date): Only leads created on or before this date. - Include converted leads (`include_converted_leads`, true/false): Converted leads are hidden by default - a lead that became a person is no longer a lead. Tick this to see them anyway. Default: `false`. - Sort by (`sort_by`, text): Which field to order the results by. One of: `name`, `company_name` (Company), `title`, `value`, `email`, `phone`, `date_modified` (Last modified), `date_created` (Created), `city`, `state`, and 4 more. - Sort direction (`sort_direction`, text): Ascending or descending. Copper sorts ascending by default. One of: `asc` (Ascending), `desc` (Descending). - Page (`page_number`, number): Which page of results to read, starting at 1. Copper never returns more than the first 100,000 matches however far you page. From 1 to 100000. Default: `1`. - Results per page (`page_size`, number): How many records to return, 1-200. Defaults to 20. From 1 to 200. Default: `20`. **Outputs** - `count` (number): How many came back on this page - `ids` (list): Just the ids, for chaining into a later step - `leads` (list): The leads on this page - `page_number` (number): The page that was read - `page_size` (number): How many were asked for - `total` (number): Copper's upper-bound count of every match, from the X-PW-TOTAL header **Example output** ```json { "count": 1, "ids": [ 9123456 ], "leads": [ { "address": null, "assignee_id": 137658, "company_name": "Naval Systems", "custom_fields": [], "customer_source_id": 331240, "date_created": 1747699200, "date_modified": 1757894400, "details": "Downloaded the whitepaper.", "email": { "category": "work", "email": "grace@example.com" }, "id": 9123456, "interaction_count": 1, "monetary_unit": "USD", "monetary_value": 5000, "name": "Grace Hopper", "phone_numbers": [], "socials": [], "status": "New", "status_id": 208231, "tags": [ "lodol-qa" ], "title": "Rear Admiral", "websites": [] } ], "page_number": 1, "page_size": 20, "total": 1 } ``` ### Search opportunities Find deals by name, status, pipeline, company, contact, owner, value or close date. Every filter you fill in has to match. **Inputs** - Name (`name`, text): Opportunity name search. Partial names match. - Statuses (`status_ids`, list): Only return deals in these states. Copper stores the word on the record and numbers it in the filter; choosing here sends the number for you. One or more of: `0` (Open), `1` (Won), `2` (Lost), `3` (Abandoned). - Pipelines (`pipeline_ids`, list): Only return deals in these pipelines. - Company IDs (`company_ids`, list): Only return deals against these companies. - Primary contact IDs (`primary_contact_ids`, list): Only return deals whose main contact is one of these people. - Owners (`assignee_ids`, list): Only return records owned by these Copper users. Choose 'Unassigned' for the records nobody owns. - Customer sources (`customer_source_ids`, list): Only return deals from these sources. - Loss reasons (`loss_reason_ids`, list): Only return deals lost for these reasons. - Tags (`tags`, list): Only return records carrying any of these tags. Tags are the one filter that widens rather than narrows: a record with any one of them matches, while every other filter on this step has to match as well. - Value at least (`minimum_monetary_value`, number): Only deals worth at least this much. - Value at most (`maximum_monetary_value`, number): Only deals worth at most this much. - Closing on or after (`minimum_close_date`, date): Only deals expected to close on or after this date. - Closing on or before (`maximum_close_date`, date): Only deals expected to close on or before this date. - Created on or after (`minimum_created_date`, date): Only deals created on or after this date. - Created on or before (`maximum_created_date`, date): Only deals created on or before this date. - Sort by (`sort_by`, text): Which field to order the results by. One of: `name`, `assignee` (Owner), `company_name` (Company), `customer_source_id` (Customer source), `date_created` (Created), `date_modified` (Last modified), `inactive_days` (Days inactive), `interaction_count` (Interaction count), `last_interaction` (Last interaction), `monetary_unit` (Currency), and 5 more. - Sort direction (`sort_direction`, text): Ascending or descending. Copper sorts ascending by default. One of: `asc` (Ascending), `desc` (Descending). - Page (`page_number`, number): Which page of results to read, starting at 1. Copper never returns more than the first 100,000 matches however far you page. From 1 to 100000. Default: `1`. - Results per page (`page_size`, number): How many records to return, 1-200. Defaults to 20. From 1 to 200. Default: `20`. **Outputs** - `count` (number): How many came back on this page - `ids` (list): Just the ids, for chaining into a later step - `opportunities` (list): The opportunities on this page - `page_number` (number): The page that was read - `page_size` (number): How many were asked for - `total` (number): Copper's upper-bound count of every match, from the X-PW-TOTAL header **Example output** ```json { "count": 1, "ids": [ 14341018 ], "opportunities": [ { "assignee_id": 137658, "close_date": "1/23/2027", "company_id": 12030795, "company_name": "Analytical Engines", "custom_fields": [], "customer_source_id": 331242, "date_created": 1747699200, "date_modified": 1757894400, "details": "Pilot agreed, waiting on procurement.", "id": 14341018, "interaction_count": 4, "loss_reason_id": null, "monetary_value": 25000, "name": "Difference Engine rollout", "pipeline_id": 213214, "pipeline_is_revenue": true, "pipeline_stage_id": 987790, "pipeline_type": "opportunity", "primary_contact_id": 27140359, "priority": "High", "status": "Open", "tags": [ "lodol-qa" ], "win_probability": 40 } ], "page_number": 1, "page_size": 20, "total": 1 } ``` ### Search people Find people in Copper by name, email, phone, owner, company, location or tag. Every filter you fill in has to match; tags are the exception and match any one of them. **Inputs** - Name (`name`, text): Full-name search. Partial names match. - Email addresses (`emails`, list): Only return people with one of these email addresses. To look one person up by address, 'Find person by email' is faster and tells you when nobody has it. - Phone number (`phone_number`, text): Only return people with this phone number. - Phone matching (`phone_match`, text): How loosely to match the phone number. Leave empty for Copper's default exact match. One of: `partial` (Ends with these digits), `fuzzy` (Fuzzy - also tries it without a leading country or area code). - Contact types (`contact_type_ids`, list): Only return records with one of these contact types. - Owners (`assignee_ids`, list): Only return records owned by these Copper users. Choose 'Unassigned' for the records nobody owns. - Company IDs (`company_ids`, list): Only return people at these companies. Use -2 for the people who belong to no company. 'Search companies' returns these ids. - City (`city`, text): Only return people in this city. - State or region (`state`, text): Only return people in this state or region. - Postal code (`postal_code`, text): Only return people with this postal code. - Country code (`country`, text): Two-letter country code, for example US or GB. - Tags (`tags`, list): Only return records carrying any of these tags. Tags are the one filter that widens rather than narrows: a record with any one of them matches, while every other filter on this step has to match as well. - Following (`followed`, text): Narrow to the records the connected Copper user follows. One of: `1` (Only records I follow), `2` (Only records I do not follow). - Created on or after (`minimum_created_date`, date): Only people created on or after this date. - Created on or before (`maximum_created_date`, date): Only people created on or before this date. - Sort by (`sort_by`, text): Which field to order the results by. One of: `name`, `title`, `email`, `phone`, `date_modified` (Last modified), `date_created` (Created), `city`, `state`, `country`, `zip` (Postal code), `socials` (Social profiles). - Sort direction (`sort_direction`, text): Ascending or descending. Copper sorts ascending by default. One of: `asc` (Ascending), `desc` (Descending). - Page (`page_number`, number): Which page of results to read, starting at 1. Copper never returns more than the first 100,000 matches however far you page. From 1 to 100000. Default: `1`. - Results per page (`page_size`, number): How many records to return, 1-200. Defaults to 20. From 1 to 200. Default: `20`. **Outputs** - `count` (number): How many came back on this page - `ids` (list): Just the ids, for chaining into a later step - `page_number` (number): The page that was read - `page_size` (number): How many were asked for - `people` (list): The people on this page - `total` (number): Copper's upper-bound count of every match, from the X-PW-TOTAL header **Example output** ```json { "count": 1, "ids": [ 27140359 ], "page_number": 1, "page_size": 20, "people": [ { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "company_id": 12030795, "company_name": "Analytical Engines", "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Met at the analytics conference.", "emails": [ { "category": "work", "email": "ada@example.com" } ], "first_name": "Ada", "id": 27140359, "interaction_count": 3, "last_name": "Lovelace", "name": "Ada Lovelace", "phone_numbers": [ { "category": "work", "number": "415-555-0110" } ], "socials": [], "tags": [ "lodol-qa" ], "title": "Head of Analysis", "websites": [] } ], "total": 1 } ``` ### Search tasks Find tasks by owner, status, due date, tag, or the deal or project they belong to. **Inputs** - Owners (`assignee_ids`, list): Only return records owned by these Copper users. Choose 'Unassigned' for the records nobody owns. - Statuses (`statuses`, list): Only return tasks in these states. One or more of: `Open`, `Completed`. - Opportunity IDs (`opportunity_ids`, list): Only return tasks about these deals. - Project IDs (`project_ids`, list): Only return tasks about these projects. - Tags (`tags`, list): Only return records carrying any of these tags. Tags are the one filter that widens rather than narrows: a record with any one of them matches, while every other filter on this step has to match as well. - Following (`followed`, text): Narrow to the records the connected Copper user follows. One of: `1` (Only records I follow), `2` (Only records I do not follow). - Due on or after (`minimum_due_date`, date): Only tasks due on or after this date. - Due on or before (`maximum_due_date`, date): Only tasks due on or before this date. - Created on or after (`minimum_created_date`, date): Only tasks created on or after this date. - Created on or before (`maximum_created_date`, date): Only tasks created on or before this date. - Sort by (`sort_by`, text): Which field to order the results by. Copper sorts by due date by default. One of: `name`, `assigned_to` (Owner), `related_to` (Related record), `status`, `priority`, `due_date` (Due date), `reminder_date` (Reminder date), `completed_date` (Completed date), `date_created` (Created), `date_modified` (Last modified). - Sort direction (`sort_direction`, text): Ascending or descending. Copper sorts ascending by default. One of: `asc` (Ascending), `desc` (Descending). - Page (`page_number`, number): Which page of results to read, starting at 1. Copper never returns more than the first 100,000 matches however far you page. From 1 to 100000. Default: `1`. - Results per page (`page_size`, number): How many records to return, 1-200. Defaults to 20. From 1 to 200. Default: `20`. **Outputs** - `count` (number): How many came back on this page - `ids` (list): Just the ids, for chaining into a later step - `page_number` (number): The page that was read - `page_size` (number): How many were asked for - `tasks` (list): The tasks on this page - `total` (number): Copper's upper-bound count of every match, from the X-PW-TOTAL header **Example output** ```json { "count": 1, "ids": [ 6612345 ], "page_number": 1, "page_size": 20, "tasks": [ { "assignee_id": 137658, "completed_date": null, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Include the rollout timeline.", "due_date": 1758067200, "id": 6612345, "name": "Send the pilot summary", "priority": "High", "related_resource": { "id": 27140359, "type": "person" }, "reminder_date": 1757980800, "status": "Open", "tags": [ "lodol-qa" ] } ], "total": 1 } ``` ### Update company Change fields on an existing company. Only the fields you fill in are sent; everything else is left exactly as it is. List fields - phones, websites, tags - replace what is there rather than adding to it. **Inputs** - Company ID (`company_id`, text, required): The company to update. Paste the app.copper.com link if that is what you have. - Name (`name`, text): A new name for the company. - Email domain (`email_domain`, text): A new email domain for the company. - Description (`details`, text): Free-text description stored on the record. - Phone numbers (`phone_numbers`, list): Phone numbers. Copper replaces the whole list with what you send. - Phone category (`phone_category`, text): How Copper labels the phone numbers sent above. One of: `mobile`, `work`, `home`, `other`. - Websites (`websites`, list): Website addresses. Copper replaces the whole list with what you send. - Website category (`website_category`, text): How Copper labels the websites sent above. One of: `work`, `personal`, `other`. - Social profiles (`socials`, list): Social profile URLs. Copper replaces the whole list with what you send. - Social network (`social_category`, text): Which network the profile URLs above belong to. One of: `linkedin`, `twitter` (X / Twitter), `googleplus` (Google+), `facebook`, `youtube`, `quora`, `foursquare`, `klout`, `gravatar`, `other`. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Contact type (`contact_type_id`, text): This account's own contact type, such as Potential Customer. - Primary contact (person ID) (`primary_contact_id`, text): A new main contact for this company. - Street (`address_street`, text): Street address of the company. - City (`address_city`, text): City of the company. - State or region (`address_state`, text): State, province or region of the company. - Postal code (`address_postal_code`, text): Postal or ZIP code of the company. - Country (`address_country`, text): Country, written however this Copper account writes it - Copper accepts both 'United States' and 'US' and stores what it is given. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `company` (object): The company, as Copper returned it - `company_id` (number): The company's id - `name` (text): The company's name **Example output** ```json { "company": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Manufacturing partner.", "email_domain": "example.com", "id": 12030795, "interaction_count": 7, "name": "Analytical Engines", "phone_numbers": [ { "category": "work", "number": "415-555-0100" } ], "primary_contact_id": 27140359, "socials": [], "tags": [ "lodol-qa" ], "websites": [ { "category": "work", "url": "https://example.com" } ] }, "company_id": 12030795, "name": "Analytical Engines" } ``` ### Update opportunity Move a deal along, change its value, or close it. Only the fields you fill in are sent. Marking one Lost is worth sending a loss reason with. **Inputs** - Opportunity ID (`opportunity_id`, text, required): The deal to update. Paste the app.copper.com link if that is what you have. - Name (`name`, text): A new name for the deal. - Primary contact (person ID) (`primary_contact_id`, text): A new main contact for the deal. - Company ID (`company_id`, text): A new company for the deal. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Pipeline (`pipeline_id`, text): Move the deal to this pipeline. Pick it before the stage - the stage list is this pipeline's. - Stage (`pipeline_stage_id`, text): Move the deal to this stage. The stage must belong to the deal's pipeline. - Customer source (`customer_source_id`, text): Where this deal came from. - Loss reason (`loss_reason_id`, text): Why the deal was lost. Send it with a Lost status. - Status (`status`, text): The deal's new state. One of: `Open`, `Won`, `Lost`, `Abandoned`. - Priority (`priority`, text): How urgent the deal is. One of: `None`, `Low`, `Medium`, `High`. - Value (`monetary_value`, number): What the deal is worth, in the account's currency. - Win probability (`win_probability`, number): Chance of winning, 0-100. From 0 to 100. - Expected close date (`close_date`, date): When the deal is now expected to close. - Description (`details`, text): Free-text description stored on the record. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `name` (text): The opportunity's name - `opportunity` (object): The opportunity, as Copper returned it - `opportunity_id` (number): The opportunity's id **Example output** ```json { "name": "Difference Engine rollout", "opportunity": { "assignee_id": 137658, "close_date": "1/23/2027", "company_id": 12030795, "company_name": "Analytical Engines", "custom_fields": [], "customer_source_id": 331242, "date_created": 1747699200, "date_modified": 1757894400, "details": "Pilot agreed, waiting on procurement.", "id": 14341018, "interaction_count": 4, "loss_reason_id": null, "monetary_value": 25000, "name": "Difference Engine rollout", "pipeline_id": 213214, "pipeline_is_revenue": true, "pipeline_stage_id": 987790, "pipeline_type": "opportunity", "primary_contact_id": 27140359, "priority": "High", "status": "Open", "tags": [ "lodol-qa" ], "win_probability": 40 }, "opportunity_id": 14341018 } ``` ### Update person Change fields on an existing person. Only the fields you fill in are sent, and everything else is left exactly as it is. List fields - emails, phones, tags - replace what is there rather than adding to it. A person's company cannot be changed through this endpoint; do that in Copper. **Inputs** - Person ID (`person_id`, text, required): The person to update. Paste the app.copper.com link if that is what you have. - Full name (`name`, text): A new full name for the person. - Email addresses (`emails`, list): Replaces every address on the record with these. Send the ones you want to keep as well. - Email category (`email_category`, text): How Copper labels the email addresses sent above. One of: `work`, `personal`, `other`. - Phone numbers (`phone_numbers`, list): Phone numbers. Copper replaces the whole list with what you send. - Phone category (`phone_category`, text): How Copper labels the phone numbers sent above. One of: `mobile`, `work`, `home`, `other`. - Job title (`title`, text): A new job title for the person. - Description (`details`, text): Free-text description stored on the record. - Contact type (`contact_type_id`, text): This account's own contact type, such as Potential Customer. - Owner (`assignee_id`, text): The Copper user who owns this record. Leave empty to leave it unowned. - Street (`address_street`, text): Street address of the person. - City (`address_city`, text): City of the person. - State or region (`address_state`, text): State, province or region of the person. - Postal code (`address_postal_code`, text): Postal or ZIP code of the person. - Country (`address_country`, text): Country, written however this Copper account writes it - Copper accepts both 'United States' and 'US' and stores what it is given. - Websites (`websites`, list): Website addresses. Copper replaces the whole list with what you send. - Website category (`website_category`, text): How Copper labels the websites sent above. One of: `work`, `personal`, `other`. - Social profiles (`socials`, list): Social profile URLs. Copper replaces the whole list with what you send. - Social network (`social_category`, text): Which network the profile URLs above belong to. One of: `linkedin`, `twitter` (X / Twitter), `googleplus` (Google+), `facebook`, `youtube`, `quora`, `foursquare`, `klout`, `gravatar`, `other`. - Tags (`tags`, list): The record's tags. Copper replaces the whole set with what you send, so include the tags it already has if you want to keep them. - Custom fields (`custom_fields`, object): Custom field values, keyed by the field's definition id - for example {"126240": "Referral", "126241": 42}. The ids are on Copper's Settings > Customize Fields screen. Only the fields you list here are touched. **Outputs** - `name` (text): The person's name - `person` (object): The person, as Copper returned it - `person_id` (number): The person's id **Example output** ```json { "name": "Ada Lovelace", "person": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94105", "state": "CA", "street": "301 Howard St" }, "assignee_id": 137658, "company_id": 12030795, "company_name": "Analytical Engines", "contact_type_id": 451490, "custom_fields": [], "date_created": 1747699200, "date_modified": 1757894400, "details": "Met at the analytics conference.", "emails": [ { "category": "work", "email": "ada@example.com" } ], "first_name": "Ada", "id": 27140359, "interaction_count": 3, "last_name": "Lovelace", "name": "Ada Lovelace", "phone_numbers": [ { "category": "work", "number": "415-555-0110" } ], "socials": [], "tags": [ "lodol-qa" ], "title": "Head of Analysis", "websites": [] }, "person_id": 27140359 } ```