Overview
The Copper CRM integration provides a set of ready-made functions you can call when building mappings. They handle common lookups and conversions for Copper CRM, such as finding a Copper customer or company by email or name, resolving an activity type ID, and reading a specific email, phone number, address value, or custom field from an iPaaS.com customer, so you don't have to write that logic yourself.
Where you can use these functions
These functions are available anywhere you write a formula for the Copper CRM integration:
Dynamic Formula mappings: where a destination field's value is produced by a formula rather than mapped directly from a source field.
Mapping collection filters: where a formula decides whether a record should be processed.
Error filters: a mapping collection's error filter, which sits alongside its collection filter. When the error filter's formula resolves to true, the transfer raises an error that is held in the Error Logs for review and is not retried automatically.
Translation collections: where a translation entry uses a formula as its source value.
How to use them
Call a function by name and pass the values it needs in parentheses, for example:
await GetCustomerIdByEmail(emailAddress).Each function's signature shows its name, the parameters it accepts (with their types), and the type of value it returns. Use it as the reference for exactly how to call the function.
Function names and formula syntax are case-sensitive, so type each name exactly as shown. Whether the values a function matches are treated as case-sensitive varies by function, and is called out in the relevant parameter's description.
Every function that returns a
Taskis asynchronous and must be called withawait, as shown in each How to call it example.Optional parameters are marked in the parameter table, along with the value used when you omit them.
Each function runs at sync time, against the data in your connected Copper CRM account and your iPaaS.com subscription.
The functions are grouped below by the area of the integration they support.
Customers
Use these to look up a Copper customer, or to read details from an iPaaS.com customer while mapping to Copper.
GetCustomerIdByEmail
What it does: Looks up a Copper customer (person) by email address and returns the Copper customer ID. Returns nothing if no customer matches.
Signature: Task<string> GetCustomerIdByEmail(object emailAddress)
How to call it: await GetCustomerIdByEmail(emailAddress)
Parameter | Type | Required | Default | Description |
emailAddress |
| Yes | N/A | The iPaaS.com customer email address to look up the Copper customer by. |
Returns: string. The Copper customer ID, or nothing if no customer matches.
Example: await GetCustomerIdByEmail("user@example.com") returns the Copper customer ID for that email.
When to use it: When mapping a record to a Copper customer and you have the customer's email but need the Copper customer ID.
GetCustomerByEmail
What it does: Looks up a Copper customer (person) by email address and returns the full customer record. Returns nothing if the lookup fails.
Signature: Task<object> GetCustomerByEmail(object emailAddress)
How to call it: await GetCustomerByEmail(emailAddress)
Parameter | Type | Required | Default | Description |
emailAddress |
| Yes | N/A | The iPaaS.com customer email address to search Copper by. |
Returns: object. The Copper customer record, or nothing if the lookup fails.
Example: await GetCustomerByEmail("user@example.com") returns the Copper customer record for that email.
When to use it: When you need the full Copper customer details for an email, not just the ID.
GetEmailFromList
What it does: Returns an email address from an iPaaS.com customer's list of emails, preferring the one whose category matches. If no category matches, the first email is returned.
Signature: Task<string> GetEmailFromList(object myObj, string category)
How to call it: await GetEmailFromList(myObj, category)
Parameter | Type | Required | Default | Description |
myObj |
| Yes | N/A | The iPaaS.com customer's list of email addresses. |
category |
| Yes | N/A | The email category to match, for example |
Returns: string. The email address for the matching category, or the first email if none matches.
Example: await GetEmailFromList(emails, "Work") returns the work email, or the first email if there is no work email.
When to use it: When mapping a specific category of email address to Copper from an iPaaS.com customer.
GetPhoneFromList
What it does: Returns a phone number from an iPaaS.com customer's list of phone numbers, preferring the one whose category matches. If no category matches, the first number is returned.
Signature: Task<string> GetPhoneFromList(object myObj, string category)
How to call it: await GetPhoneFromList(myObj, category)
Parameter | Type | Required | Default | Description |
myObj |
| Yes | N/A | The iPaaS.com customer's list of phone numbers. |
category |
| Yes | N/A | The phone category to match, for example |
Returns: string. The phone number for the matching category, or the first number if none matches.
Example: await GetPhoneFromList(phones, "Office") returns the office phone number, or the first number if there is no office number.
When to use it: When mapping a specific category of phone number to Copper from an iPaaS.com customer.
GetValueFromList
What it does: Reads a named property (for example city) from an iPaaS.com customer's address list, choosing the billing or shipping address by the flags you pass. If no address matches, the first address is used.
Signature: Task<string> GetValueFromList(object addressListData, string propertyName, bool isBilling = false, bool boolValue = false)
How to call it: await GetValueFromList(addressListData, propertyName)
Parameter | Type | Required | Default | Description |
addressListData |
| Yes | N/A | The iPaaS.com customer's list of addresses. |
propertyName |
| Yes | N/A | The address property to read (for example |
isBilling |
| No |
| When |
boolValue |
| No |
| The value the chosen primary flag (billing or shipping) must equal for an address to be selected. |
Returns: string. The requested property value, or an empty string if it is not found.
Example: await GetValueFromList(addresses, "City", isBilling: true, boolValue: true) returns the city of the primary billing address.
When to use it: When mapping a value from an iPaaS.com customer's billing or shipping address to Copper.
GetValueFromCustomField
What it does: Reads the value of a Copper custom field from an iPaaS.com customer's custom fields, matching the field by name against the Copper custom field definitions. Returns an empty string if the field is not found.
Signature: Task<object> GetValueFromCustomField(object customFieldObj, object textFieldName)
How to call it: await GetValueFromCustomField(customFieldObj, textFieldName)
Parameter | Type | Required | Default | Description |
customFieldObj |
| Yes | N/A | The iPaaS.com customer's custom fields to read from. |
textFieldName |
| Yes | N/A | The Copper custom field name to match. The match is not case-sensitive and matches a definition whose name contains this value. |
Returns: object. The custom field's value, or an empty string if the field is not found.
Example: await GetValueFromCustomField(customFields, "Membership Level") returns the value of the Membership Level custom field, for example "Gold".
When to use it: When mapping a Copper custom field value from an iPaaS.com customer's custom fields.
Companies
Use these to resolve a Copper company from a company name.
GetCompanyIdByName
What it does: Looks up a Copper company by name and returns the Copper company ID. The match is not case-sensitive. Returns nothing if no company matches.
Signature: Task<string> GetCompanyIdByName(object companyName)
How to call it: await GetCompanyIdByName(companyName)
Parameter | Type | Required | Default | Description |
companyName |
| Yes | N/A | The iPaaS.com company name to look up the Copper company by. |
Returns: string. The Copper company ID, or nothing if no company matches.
Example: await GetCompanyIdByName("Acme Inc") returns the Copper company ID for "Acme Inc".
When to use it: When mapping a record to a Copper company and you have the company name but need the Copper company ID.
GetCompanyByName
What it does: Looks up a Copper company by name and returns the full company record. The match is not case-sensitive. Returns an empty company record if no company matches.
Signature: Task<object> GetCompanyByName(object companyName)
How to call it: await GetCompanyByName(companyName)
Parameter | Type | Required | Default | Description |
companyName |
| Yes | N/A | The iPaaS.com company name to search Copper by. |
Returns: object. The Copper company record, or an empty company record if no company matches.
Example: await GetCompanyByName("Acme Inc") returns the Copper company record for "Acme Inc".
When to use it: When you need the full Copper company details for a name, not just the ID.
Activities
Use this to resolve a Copper activity type by name.
GetCopperActivityTypeIdByName
What it does: Looks up a Copper activity type by name and returns its numeric activity type ID. The match is not case-sensitive. If the name is empty or no activity type matches, a non-positive fallback is returned (-1 when the name is empty or the activity types cannot be loaded, 0 when the types load but no name matches).
Signature: Task<int> GetCopperActivityTypeIdByName(object activityName)
How to call it: await GetCopperActivityTypeIdByName(activityName)
Parameter | Type | Required | Default | Description |
activityName |
| Yes | N/A | The Copper activity type name, for example |
Returns: int. The Copper activity type ID, or a non-positive fallback (-1 or 0) when the name is empty or no activity type matches.
Example: await GetCopperActivityTypeIdByName("Call") returns the activity type ID for "Call".
When to use it: When mapping an activity to Copper and you have the activity type name but need its Copper ID.