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.

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

JavaScript Authentication Example

const companyId = process.env.CONNECTWISE_COMPANY_ID;
const publicKey = process.env.CONNECTWISE_PUBLIC_KEY;
const privateKey = process.env.CONNECTWISE_PRIVATE_KEY;
const clientId = process.env.CONNECTWISE_CLIENT_ID;

const credentials = `${companyId}+${publicKey}:${privateKey}`;
const base64Credentials = Buffer.from(credentials).toString('base64');

const headers = {
  'Authorization': `Basic ${base64Credentials}`,
  'clientId': clientId,
  'Content-Type': 'application/json'
};

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

Pagination Example

async function fetchAllTickets(conditions) {
  const allTickets = [];
  let page = 1;
  const pageSize = 250;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `${baseUrl}/service/tickets?conditions=${conditions}&page=${page}&pageSize=${pageSize}`,
      { headers }
    );

    const tickets = await response.json();
    allTickets.push(...tickets);

    hasMore = tickets.length === pageSize;
    page++;
  }

  return allTickets;
}

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."
}

Retry Strategy

async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 30;
      const jitter = Math.random() * 1000;
      await sleep(retryAfter * 1000 + jitter);
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

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. Cache reference data - Queues, statuses, members
5. Use webhooks - Instead of polling for changes

Error Handling

HTTP Status Codes

Error Response Format

{
  "code": "InvalidArgument",
  "message": "The value 'invalid' is not valid for field 'status/id'.",
  "errors": [
    {
      "code": "InvalidArgument",
      "message": "status/id must be a valid integer",
      "field": "status/id"
    }
  ]
}

Common Errors

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

Webhook Callback

ConnectWise can POST to your endpoint on entity changes:

{
  "Action": "updated",
  "ID": 54321,
  "Type": "ticket",
  "MemberID": 123,
  "Callback": {
    "ID": 54321,
    "Type": "ticket"
  }
}

Registering Callbacks

POST /system/callbacks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "objectId": 0,
  "type": "ticket",
  "level": "owner",
  "description": "Ticket updates webhook"
}

Environment Configuration

Recommended Environment Variables

export CONNECTWISE_COMPANY_ID="your-company-id"
export CONNECTWISE_PUBLIC_KEY="your-public-key"
export CONNECTWISE_PRIVATE_KEY="your-private-key"
export CONNECTWISE_CLIENT_ID="your-client-id"
export CONNECTWISE_SITE="api-na.myconnectwise.net"

Configuration Object

const config = {
  companyId: process.env.CONNECTWISE_COMPANY_ID,
  publicKey: process.env.CONNECTWISE_PUBLIC_KEY,
  privateKey: process.env.CONNECTWISE_PRIVATE_KEY,
  clientId: process.env.CONNECTWISE_CLIENT_ID,
  site: process.env.CONNECTWISE_SITE || 'api-na.myconnectwise.net',
  apiPath: '/apis/3.0'
};

Best Practices

1. Store credentials securely - Never commit to source control
2. Use environment variables - For configuration
3. Implement rate limit handling - Don't get blocked
4. Cache reference data - Reduce API calls
5. Handle errors gracefully - Retry transient failures
6. Use pagination - Don't fetch unbounded results
7. Select needed fields - Reduce payload size
8. Log API calls - For debugging and audit
9. Test in sandbox - Before production changes
10. 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