Copper v2

Provides integration with Copper CRM to search and retrieve records, maintain CRM data, manage relationships, and work with file metadata and webhook subscriptions through operation templates.

Revision History

0.0.1.13 - Initial release.

Connection

Use a Connection to store your Copper API key and the email address of the user who generated it.

Setup Notes

1. Generate an API key in Copper using an administrator account. See Copper's Generating an API Key instructions.
2. Enter the key in ApiKey and its owner's email address in UserName.
3. Run the Connection test. It performs a read-only user search limited to one result.
4. Select the Node Method, then select an operation template to populate OperationId and expose the operation's input fields.

Methods

Choose the method that matches the action you want to perform. Select a template instead of entering OperationId manually. Searches and email lookups remain read operations even when Copper uses HTTP POST for them.

Read methods accept operation-specific path and query values in Options. Search criteria belong in the single Filter object. Write methods take an Items array, with identifiers and body fields together in each item.

Query

Searches users, leads, people, companies, opportunities, projects, tasks, and activities. You can also search by custom fields or retrieve an entity's activities using the corresponding template. Results page automatically.

Retrieve

Retrieves a single record, account details, a custom definition, file metadata, a signed file-upload URL, or a webhook subscription.

Use the Fetch Current User template to retrieve the API key owner's user record without supplying an ID. User lookup by ID requires a numeric Options.id. Person lookup by email uses Filter for its lookup body.

List

Lists reference data and related records, including customer sources, lead statuses, contact types, loss reasons, pipelines and stages, activity types, tags, custom definitions, field layouts, relationships, attached files, and webhook subscriptions.

Create

Creates CRM records, activities, custom definitions, relationships, file attachments, or webhook subscriptions using the selected template.

Update

Updates CRM records or custom definitions. Record updates are partial: omitted fields remain unchanged, and an explicit null clears a supplied field. Required path identifiers cannot be null.

Delete

Deletes records, custom-field definitions, relationships, attached files, or webhook subscriptions using the selected template.

Upsert

Creates or updates a lead using matching criteria. Supply the lead's writable fields under properties and the matching criteria under match. The operation supports matching by a standard field or a custom field.

Convert

Converts a lead to a person, with optional company and opportunity overrides. Supply the lead ID in Items.id. Optional overrides belong under Items.details.person, Items.details.company, and Items.details.opportunity.

For a company override, supply either id or name; supplying both fails validation. Opportunity monetary values accept decimals.

Usage Notes

Pagination and streaming

Query manages page_number and page_size automatically. Do not supply these fields in Filter. Lead, person, and opportunity searches use pages of 25 records; other searches use pages of 200. Where the operation supports it, the default sort is date_created ascending unless you supply your own sort.

The first read completes before output streaming begins. Later search pages are fetched as downstream Nodes consume the results. Empty or short pages end the search. Repeated full pages fail the Node, and reaching the 100,000-record search window fails with a request to narrow the filter. Use smaller filter ranges for larger exports.

Filters and field values

String and integer collections exposed by templates use CSV strings on input and output. For example, supply Filter.ids as 1,2. Tags containing commas require CSV quoting, such as one,"two,three". Double any quote inside a quoted value. An empty CSV string means an empty collection; "" means one empty string.

Values preserve their spacing and case. Integer CSV fields reject whitespace, fractions, empty elements, and values outside the signed 64-bit range. Enum filters require exact values:

• Task statuses: Open,Completed.
• Opportunity statuses: Open,Won,Lost,Abandoned.
• Priorities: None,Low,Medium,High.

Use a string for company or person name searches. Company domain searches use Filter.email_domains as CSV; Filter.email_domain is not supported.

Nested objects and object collections, such as addresses and contact details, remain structured. Dynamic custom-field values retain their JSON types, including arrays, objects, scalars, and nulls. Read responses preserve nested objects and related-record types and IDs.

Writing records and handling failures

Each write method performs one request per item. The first item completes before output streaming begins, and later items are processed as the response is consumed. An empty input sends no write request.

If the first item fails, the Node fails. Handled validation, provider, or transport failures on later items produce a response with Flowgear.IsSuccess set to false; processing then continues with subsequent items. Check Flowgear.IsSuccess and Flowgear.StatusMessage downstream. Flowgear.Request contains the original input item so you can identify the affected record.

Validate complete source documents before starting writes when you need to reject an entire invalid document. Streaming input can allow an earlier item to be written before a later input error is discovered.

Writable record templates exclude computed fields and timestamps. Use relationship operations to change a person's company association instead of supplying company_id in a person update.

File uploads

Use Retrieve to obtain a signed upload URL. Complete the S3 upload separately using the returned upload details, then use the Copper file-attachment template under Create to relate the uploaded key to the entity. The Copper Node does not perform the S3 upload or send Copper credentials to S3.

Examples

Search companies by domain

Select the company-search template under Query. Supply this Filter to search two domains:

{
  "email_domains": "example.invalid,other.invalid"
}

Consume Response to receive company records. Pagination runs automatically; do not add paging fields to the filter.

Update a record and clear a field

Select the company-update template under Update. Supply this Items array, replacing 10 with your Copper company ID:

[
  {
    "id": 10,
    "details": null
  }
]

This request clears details and leaves omitted fields unchanged. Check the returned Flowgear.IsSuccess value before continuing with actions that depend on the update.

Known Issues

• Tag-name-only listing and the manual last_tag_value cursor are not supported. Large tag exports may be incomplete because tag pagination is not verified.