ConnectWise PSA Contact Management

Overview

Contacts in ConnectWise PSA represent individuals at your client companies. Contacts can be ticket requestors, agreement signers, project stakeholders, and portal users. This skill covers contact CRUD operations, communication items, contact types, and portal access management.

Anti-triggers

• The organisation itself — company type, status, sites and billing

defaults hang off the company record, not its contacts; use connectwise-psa-companies.

• Your own technicians — internal staff are /system/members, a

separate entity that contact searches never return; query it through connectwise-psa-api-patterns.

API Endpoint

Base: /company/contacts

Contact Types

Standard contact types in ConnectWise PSA:

Note: Contact types are configurable. Query /company/contacts/types for your instance's types.

Complete Contact Field Reference

Core Fields

Contact Information

Address Fields

Portal Access Fields

Tracking Fields

Communication Items

Communication items store contact methods (email, phone, fax, etc.) for a contact.

Communication Item Endpoint

/company/contacts/{contactId}/communications

Communication Item Fields

Communication Types

Communication type ids and names are per tenant. Never assume {"id": 1} is Email. Your tenant may have "Email", "Work Email", "Direct", "Mobile", and so on, with different ids.

Each type is a row from GET /company/communicationTypes. These fields say what it is for:

Call cw_list_communication_types (read-only) to see the types and their flags before building communication items or patching them. In the examples below, 12345 (email) and 12346 (phone) are placeholders: replace them with ids returned by cw_list_communication_types.

communicationType on an item is the category (Email, Phone, Fax). It is not the type name. A type named "Direct" still has communicationType: "Phone".

Add Communication Item

POST /company/contacts/{contactId}/communications
Content-Type: application/json

{
  "type": {"id": 12345},
  "value": "[email protected]",
  "defaultFlag": true,
  "communicationType": "Email"
}

Add Phone Number

POST /company/contacts/{contactId}/communications
Content-Type: application/json

{
  "type": {"id": 12346},
  "value": "555-123-4567",
  "extension": "101",
  "defaultFlag": true,
  "communicationType": "Phone"
}

MCP Tools

cw_list_communication_types

Read-only. Lists the tenant's communication types with their flags. No required params.

cw_create_contact

Creates a contact, optionally with an email and phone. The MCP resolves the communication types itself from /company/communicationTypes and caches them per connection:

• Email: a type with emailFlag=true; prefers defaultFlag, then the name "Email".
• Phone: a type with phoneFlag=true; prefers the name "Direct", then defaultFlag.

If no type resolves, it returns an error listing the available types. Override with optional params (an id wins over a name; an unknown name errors):

Example (override params only; add the usual contact fields as normal):

{
  "emailTypeId": 12345,
  "phoneTypeName": "Mobile"
}

cw_update_contact

When changing communication items, use type: { "id": <typeId> } with an id from cw_list_communication_types.

Portal Access

Portal Security Levels

Enable Portal Access

PATCH /company/contacts/{id}
Content-Type: application/json

{
  "portalSecurityLevel": 2,
  "disablePortalLoginFlag": false
}

Portal Password Reset

Portal passwords are managed through the ConnectWise portal. The API does not expose password fields.

Portal Invitation

To invite a contact to the portal:

1. Ensure contact has valid email
2. Set portalSecurityLevel > 0
3. Set disablePortalLoginFlag = false
4. Portal sends automatic invitation email

API Operations

Create Contact

POST /company/contacts
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Smith",
  "company": {"id": 12345},
  "title": "IT Director",
  "type": {"id": 4}
}

Create Contact with Communication Items

POST /company/contacts
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Smith",
  "company": {"id": 12345},
  "title": "IT Director",
  "type": {"id": 4},
  "communicationItems": [
    {
      "type": {"id": 12345},
      "value": "[email protected]",
      "defaultFlag": true
    },
    {
      "type": {"id": 12346},
      "value": "555-123-4567",
      "extension": "101",
      "defaultFlag": true
    }
  ]
}

Get Contact

GET /company/contacts/{id}

Update Contact

PATCH /company/contacts/{id}
Content-Type: application/json

{
  "title": "CTO",
  "type": {"id": 2}
}

Search Contacts

GET /company/contacts?conditions=company/id=12345 and inactiveFlag=false

Delete Contact

DELETE /company/contacts/{id}

Note: Contacts with related records (tickets, etc.) cannot be deleted. Mark as inactive instead.

Common Query Patterns

All contacts for a company:

conditions=company/id=12345

Active contacts only:

conditions=inactiveFlag=false

Contacts by type:

conditions=type/id=2

Contacts with portal access:

conditions=portalSecurityLevel>0 and disablePortalLoginFlag=false

Search by name:

conditions=firstName contains "John" or lastName contains "Smith"

Contacts by email:

conditions=communicationItems/value="[email protected]"

Primary contacts only:

conditions=type/id=2 and inactiveFlag=false

Contact Relationships

Related Entities

Contact Notes

GET /company/contacts/{id}/notes
POST /company/contacts/{id}/notes

Note Fields:

Best Practices

1. Always include company - Contacts must belong to a company
2. Add communication items - Email/phone essential for notifications
3. Set contact type - Helps identify primary contacts
4. Use portal access wisely - Grant minimum necessary access
5. Link to site - Important for multi-site companies
6. Avoid duplicates - Search before creating new contacts

Error Handling

Related Skills

• ConnectWise Companies - Company management
• ConnectWise Tickets - Service tickets
• ConnectWise API Patterns - Query syntax and auth