ConnectWise PSA API Patterns

Overview

The ConnectWise PSA REST API provides access to all PSA entities including tickets, companies, contacts, projects, and time entries. This skill covers authentication, query syntax, pagination, rate limiting, and best practices for API integration.

Anti-triggers

"ConnectWise" is an umbrella brand over three products with three unrelated APIs. Loading the wrong one produces auth failures that read like permission problems:

• ConnectWise Automate — on-premise RMM server, /cwa/api/v1/ base

path, Bearer-token auth, and singular condition= filters. PSA public/private keys will not authenticate against it. Use connectwise-automate-api-patterns.

• ConnectWise CPQ (Sell/Quosal) — its own host and credential set

again; use connectwise-cpq-api-patterns.

Base URLs

Replace {codebase} with your company identifier (e.g., v4_6_release or custom).

Legacy URLs

Some instances may use legacy URLs:

https://api-na.myconnectwise.net/v4_6_release/apis/3.0/
https://api-staging.connectwisedev.com/v4_6_release/apis/3.0/

Authentication

Public/Private Key + Client ID

ConnectWise PSA uses Basic Authentication with a combined credential string plus a Client ID header.

Credential Format

Authorization: Basic base64({companyId}+{publicKey}:{privateKey})
clientId: {your-client-id}

Step-by-Step Authentication

1. Combine credentials:

   companyId + "+" + publicKey + ":" + privateKey
   Example: company+publickey:privatekey

1. Base64 encode:

   base64("company+publickey:privatekey") = "Y29tcGFueStwdWJsaWNrZXk6cHJpdmF0ZWtleQ=="

1. Set headers:

   Authorization: Basic Y29tcGFueStwdWJsaWNrZXk6cHJpdmF0ZWtleQ==
   clientId: your-registered-client-id
   Content-Type: application/json

Example Request

GET /v4_6_release/apis/3.0/service/tickets
Host: api-na.myconnectwise.net
Authorization: Basic Y29tcGFueStwdWJsaWNrZXk6cHJpdmF0ZWtleQ==
clientId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/json

See references/examples.md for a JavaScript authentication example and recommended environment variable setup.

Obtaining Credentials

1. API Member: Create in System > Members > API Members
2. Public/Private Keys: Generate for API member
3. Client ID: Register at ConnectWise Developer Portal

Conditions Query Syntax

Basic Syntax

conditions=field operator value

Supported Operators

Field References

Use / to reference nested fields:

company/id=12345
status/name="New"
contact/firstName contains "John"

Combining Conditions

AND (default):

conditions=company/id=12345 and status/id!=5 and priority/id<=2

OR:

conditions=status/id=1 or status/id=2

Complex:

conditions=(status/id=1 or status/id=2) and company/id=12345

Date Conditions

Date format: YYYY-MM-DD or ISO 8601

conditions=dateEntered>=[2024-01-01]
conditions=dateEntered>=[2024-01-01T00:00:00Z] and dateEntered<[2024-02-01T00:00:00Z]

String Conditions

Exact match:

conditions=summary="Email not working"

Contains:

conditions=summary contains "email"

Like (wildcards):

conditions=summary like "%email%"
conditions=company/identifier like "AC%"

Null Checks

conditions=contact=null
conditions=assignedResource!=null

URL Encoding

Special characters must be URL-encoded:

Example:

GET /service/tickets?conditions=company/id%3D12345%20and%20status/id!%3D5

Pagination

Request Parameters

Example Request

GET /service/tickets?page=1&pageSize=100

Response Headers

Paginate by incrementing page until the response has fewer records than pageSize. See references/examples.md for a full fetch-all-pages implementation.

Getting Total Count

GET /service/tickets?conditions=status/id!=5&pageSize=1&fields=id

Check X-Total-Count header or use /count endpoint:

GET /service/tickets/count?conditions=status/id!=5

Rate Limiting

Limits

Rate Limit Headers

429 Response

When rate limited, you receive HTTP 429:

{
  "code": "RateLimitExceeded",
  "message": "Rate limit exceeded. Try again in 30 seconds."
}

Implement exponential backoff with jitter on 429s using the Retry-After header. See references/examples.md for a retry strategy implementation.

Best Practices for Rate Limits

1. Implement exponential backoff - Don't hammer the API
2. Check headers - Monitor remaining requests
3. Batch operations - Reduce total requests
4. Use webhooks - Instead of polling for changes

Error Handling

Errors return the relevant HTTP status code plus a JSON body with code and message fields, and per-field detail in errors[]. See references/errors.md for the complete HTTP status code table, error response format, and common error codes.

Common API Patterns

Field Selection

Request specific fields only:

GET /service/tickets?fields=id,summary,status/name,company/name

Ordering

GET /service/tickets?orderBy=priority/id asc, dateEntered desc

Child Collections

Include child records:

GET /service/tickets?childconditions=notes/text contains "update"

Custom Fields

GET /service/tickets?customFieldConditions=customField1 contains "value"

Webhook Configuration

ConnectWise can POST entity-change events to a registered callback URL. See references/webhooks.md for the callback payload shape and the registration request.

Best Practices

1. Store credentials securely - Never commit to source control
2. Handle errors gracefully - Retry transient failures
3. Use pagination - Don't fetch unbounded results
4. Select needed fields - Reduce payload size
5. Log API calls - For debugging and audit
6. Monitor usage - Track API call patterns

API Documentation

• ConnectWise Developer Portal
• REST API Reference
• API Schema Browser

Related Skills

• ConnectWise Tickets - Ticket management
• ConnectWise Companies - Company management
• ConnectWise Contacts - Contact management
• ConnectWise Projects - Project management
• ConnectWise Time Entries - Time tracking