Copper API Integration Profile
Information and guides about integrating with Copper API
Add Copper Integration to Your App- Fetch Account Details
Fetch Account Details
- Fetch User by ID
Fetch User by ID
- List Users
Parameters
You can include the following parameters in a search request.
Field Type Details Default Required Parameters -- Optional Parameters page_number number The page number (starting with 1) that you would like to view. 1 page_size number The number of entries included in a page of results 20 - Fetch a Lead by ID
Fetch a Lead by ID
- Update a Lead
Updates are only applied to fields explicitly specified in the request body. For example, if an update request is made with an empty body, no updates will be made. To remove the value from a field, the request body must specify the target field value as 'null'.
- Delete a Lead
This request permanently removes a Lead from your Copper account.
- Create a New Lead
Create a New Lead
- UPSERT a Lead
Functionality
"Upsert" (update + insert) will atomically do the following:
- Check for the existence of a Lead matching certain criteria
- If one exists, update it with the supplied parameters.
- If not, create a new Lead with the supplied parameters.
- This is particularly useful to avoid creating duplicate Leads.
Match Criteria
The supported match criteria are:
- Name
- Custom Fields
To match on a Custom Field, the corresponding Custom Field Definition must be available on Leads and included in filters. (These settings may be viewed and edited in the web application via System Settings -> Custom Fields.)
Match Outcomes
Match outcomes are handled as follows:
- If no matches are found, create a new Lead.
- If exactly one match is found, update that Lead.
- If more than one match is found, return a 422 response with the IDs of the matching Leads.
- If more than 30 matches are found, return a 422 response without the IDs of the matching Leads.
- CONVERT a Lead
This request creates a Person record from a Lead record. Optionally, a Company and an Opportunity record can be created as well in the same process. The Lead record is removed after it has been converted.
Field Type Details person object Details about the Person to be created by the Lead conversion. Valid fields are name, contact_type_id, and assignee_id. company object Details about the Company to which the newly created Person will belong. Valid fields are id or name, and they are mutually exclusive. If a Company id is specified, the new Person will belong to that Company. If the name of an existing Company is specified, the new Person will belong to that Company. If a new name is specified, a new Company will be created with that name, and the new Person will belong to that Company. If you explicitly supply an empty string ("") for the company name, then no Company will be created. By default, fuzzy matching will return a list of candidate companies. An optional Boolean field "exact_match" can be specified if the exact company name is known. opportunity object Details about the Opportunity to be created by the Lead conversion. Valid fields are name, pipeline_id, pipeline_stage_id, monetary_value, and assignee_id. If unspecified, no Opportunity will be created. If pipeline_stage_id is unspecified, it will default to the first stage in the pipeline. - List Leads (Search)
The /search endpoint provides the ability to list Leads and sort the results by certain parameters. When multiple ciriteria are provided records meeting ALL criteria will be returned (the filtering criteria have an 'AND' relationship).
To see examples of search request using the various parameters, click on the
Leads Searchdropdown on the right. Certain fields can be filtered by an empty value, i.e., filter records where the field is not specified. For Leads, these fields are: city, state, postal_code, tags, custom dropdown, custom multi-select fields. For an example of how this works, seeSearch Leads by Empty Field. Some fields (e.g. assignee_ids) can also filter for an empty value by specifying -2 as the ID.To search by custom fields, see
Search Entity by Custom FieldunderCustom Fieldsfolder.To change the number of records returned, change the "page_size" parameter. E.g., specify 200 for a page size of 200 records.
Field Type Details Default page_number number The page number (starting with 1) that you would like to view. 1 page_size number The number of entries included in a page of results 20 sort_by string The field on which to sort the results (see footnote 1). name sort_direction string The direction in which to sort the results. Possible values are: asc or desc. asc name string Full name of the Lead to search for. none phone_number string Phone number of the Lead to search for. none emails string Email of the Lead to search for. none assignee_ids number[] The ids of Users that Leads are assigned to (see footnote 2). none status_ids number[] An array of Lead status IDs (see footnote 3). none customer_source_ids number[] An array of customer source IDs (see footnote 4). none city string The city in which Leads must be located. none state string The state or province in which Leads must be located. none postal_code string The postal code in which Leads must be located. none country string The two character country code where Leads must be located. none tags string[] Filter Leads to those that match at least one of the tags specified. none followed number 1: followed, 2: not followed none age number The maximum age in seconds that each Lead must be. none minimum_monetary_value number The minimum monetary value Leads must have. none maximum_monetary_value number The maximum monetary value Leads must have. none minimum_interaction_count number The minimum number of interactions Leads must have had. none maximum_interaction_count number The maximum number of interactions Leads must have had. none minimum_interaction_date timestamp The Unix timestamp of the earliest date of the last interaction. none maximum_interaction_date timestamp The Unix timestamp of the latest date of the last interaction. none minimum_created_date timestamp The Unix timestamp of the earliest date Leads are created. none maximum_created_date timestamp The Unix timestamp of the latest date Leads are created. none minimum_modified_date timestamp The Unix timestamp of the earliest date Leads are modified. none maximum_modified_date timestamp The Unix timestamp of the latest date Leads are modified. none Foonotes:
- Possible fields are: name, first_name, last_name, company_name, title, value, email, phone, date_modified, date_created, city, state, country, zip, inactive_days.
- date_modified and date_created: sorting is from oldest to newest
- inactive_days: sorting is from newest to oldest
- To get User IDs, see
List UsersunderAcount and Usersfolder. Enter -2 as an ID for no assignee. - To get lead status IDs, see
List Lead StatusesunderOther Resourcesfolder. - To get customer source IDs, see
List Customer SourcesunderOther Resourcesfolder. Enter -2 as an ID for no customer source.
- Possible fields are: name, first_name, last_name, company_name, title, value, email, phone, date_modified, date_created, city, state, country, zip, inactive_days.
