ConnectWise

What’s supported

Supported actions

This connector supports:

• Read Actions, including full historic backfill and incremental read. Please note that incremental read is unreliable due to ConnectWise API limitations. You may get more data than what is within the time range.
• Subscribe Actions.
• Write Actions.
• Proxy Actions, using the base URL https://{{.region}}.myconnectwise.net.

The ConnectWise connector supports reading from all standard objects and writing to most standard objects, including the following:

Object	Read	Write	Subscribe

See the official OpenAPI file for the complete list. (Requires ConnectWise Developer Network account)

Connector supports write operations using a JSON Patch document passed in record.patch. When performing an update, record.id must also be provided so the connector can resolve which record to patch.

Write payload example for the contacts object:

{
  "groupRef": "{{connectWiseGroupID}}",
  "type": "update",
  "record": {
    "id": "58016",
    "patch": [
      {"op": "replace", "path": "/firstName", "value": "John"}
    ]
  }
}

Custom Fields

The connector supports reading and writing custom fields on supported objects, and they behave like native fields. For reads, they’re available through scheduled reads, historical backfills, and subscriptions.

Each custom field is exposed as customField<ID>. Map it to a more readable name in your configuration with mapToName.

Example: a field with ID 59 representing a marketing preference is selected as customField59 and can be mapped to marketingEmailOn.

read:
  objects:
    - objectName: contacts
      requiredFields:
        - fieldName: customField59
          mapToName: marketingEmailOn
        - fieldName: customField83
          mapToName: hobby

For writes, provide custom fields as if they were native fields; the connector converts them to the ConnectWise format automatically:

{
  "firstName": "Estella",
  "customField59": true,
  "customField83": "Traveling"
}

You only need to include the custom fields you want to set or change. To clear a field, set its value to null.

To find a custom field’s ID, check a read response, custom fields are returned with their IDs in the customFields array.

Example integration

For an example manifest file of a ConnectWise integration, visit our samples repo on Github.

Contact Communication Items

ConnectWise stores a contact’s email, phone, and fax numbers inside a nested communicationItems array, which isn’t directly mappable. To make these easy to read and write, the connector exposes the default email, phone, and fax of a contact as flat fields, which you can map like any other contact field.

Field	Description
AMPERSAND-defaultEmail	The contact’s default email address
AMPERSAND-defaultEmailId	The communication type of that email
AMPERSAND-defaultPhone	The contact’s default phone number
AMPERSAND-defaultPhoneId	The communication type of that phone
AMPERSAND-defaultFax	The contact’s default fax number
AMPERSAND-defaultFaxId	The communication type of that fax

Only the default item of each category is exposed. If a contact has several emails, only the one marked as default appears in AMPERSAND-defaultEmail.

Reading

Map these fields in a read action just like standard contact fields:

read:
  objects:
    - objectName: contacts
      requiredFields:
        - fieldName: AMPERSAND-defaultEmail

A contact whose default email is [e-mail] reads back as:

{
  "AMPERSAND-defaultEmail": "[e-mail]",
  "AMPERSAND-defaultEmailId": "15"
}

The ...Id field identifies which communication type the default value belongs to. This matters when a contact has more than one item in the same category.

Writing

Map a value to AMPERSAND-defaultEmail (or phone/fax) to set it when creating or updating a contact:

• Set just the value, and the connector uses the customer’s default type for that category.
• Set the matching ...Id field too if you want to target a specific type (for example, a Work email vs a Home email). The value is applied to that type and marked as the default.

Updates replace the fields you send. Any fields you omit will be cleared. For partial updates, see the JSON Patch section below.

Example — replace a contact:

{
  "firstName": "John",
  "lastName": "Smith",
  "AMPERSAND-defaultEmail": "[e-mail]"
}

The ...Id fields refer to ConnectWise “communication types” configured in the customer’s ConnectWise account. You only need them when a contact has more than one email, phone, or fax and you want to target a specific one.

Advanced: partial updates with JSON Patch

If you call the write API directly, you can send a JSON Patch to change a single field, including these virtual fields:

{
  "type": "update",
  "record": {
    "id": "58117",
    "patch": [
      { "op": "replace", "path": "/AMPERSAND-defaultEmail", "value": "[e-mail]" }
    ]
  }
}

• replace on a value updates the current default item.
• replace on an ...Id field switches which communication type is the default, (used together with AMPERSAND-defaultEmail, etc.)
• remove deletes the current default item for that category.

The connector translates these into the correct changes on the underlying communicationItems array.

Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with ConnectWise:

• Create a manifest file like the example above.
• Deploy it using the amp CLI.
• Embed the InstallIntegration UI component. The UI component will prompt the customer for their username and password.
• Start making Proxy Calls, and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector’s base URL is https://{{.region}}.myconnectwise.net.

Credential format for ConnectWise

ConnectWise uses a non-standard format for Basic Auth. The username and password fields do not correspond to the actual username and password that a customer uses to log in. Instead:

• Username: The username will always begin with CompanyId+ (the plus sign is literal) and then use either the public key, integrator username, or MemberId (e.g. mycompany+8mr4fDio4MBPsER2).
• Password: The password will be the private key, integrator password, or member hash.

Click here for more information about the expected credential format for ConnectWise. The UI components will display this link, so that your users can successfully provide their credentials.