Connectwise Developer Documentation

REST based integrations have three methods of authentication.  The recommended method, is using an API Member account to create API Keys specific to the integration.  The second method is to use impersonation.  Impersonation uses either an Integrator Login (Legacy) or another Member to create API Keys programmatically for other members.  The third method which is only support for internal integrations, uses username and passwords for individual members.  Due to this method requiring a user to enter their ConnectWise Manage username and password into another application, we do not support vendors utilizing this method.

ConnectWise Manage utilizes the "Basic Auth" standard with Public and Private keys and the authorization header that are unique to ConnectWise Manage members.  This means you can use the benefits of ConnectWise Manage security roles and give granular access to the APIs.

Your header must be base64 encoded and has to include a username:password.  The username will always begin with CompanyId+ and then use either the public key, integrator username or MemberId.  The password will be the private key, integrator password or member hash.

Method 1 - API Keys - Member Authentication
It is recommended to create API Members versus using API Keys tied to a specific member.
Authorization: Basic base64(companyid+publickey:privatekey)
(Authorization: Basic Y29tcGFueWlkK3B1YmxpY2tleTpwcml2YXRla2V5)

Method 2 - Integrator Login - Impersonation
This method should only be used for legacy integrations in a transition period.
Authorization: Basic base64(companyid+integratorlogin:integratorpassword)
(Authorization: Basic Y29tcGFueWlkK2ludGVncmF0b3Jsb2dpbjppbnRlZ3JhdG9ycGFzc3dvcmQ=)

Method 3 - Member ID and Password - Cookie Authentication (Not intended for 3rd party products unless using Hosted API)
This method uses 3 cookie headers.
Cookie: companyName=YourLoginCompany
Cookie: memberHash=Generated by POST to login.aspx or via Hosted API
Cookie: memberId=YourUsername

Important Note: SSL is required on production PSA servers when accessing the API. Any calls received via regular HTTP will be denied on production systems.

Are you connecting to the Cloud or Staging?  If so you must include API- in front of the ConnectWise Manage site:

api-au.myconnectwise.net
api-eu.myconnectwise.net
api-na.myconnectwise.net
api-staging.connectwisedev.com

Otherwise you will run into this error:

{
  "code": "Security",
  "message": "SSL is required.",  
  "errors": null
}

Security

When working with the Manage REST API, security is based off the Security Roles table within Manage.  This table determines each type of entity and the level of access associated.  We do not recommend requesting Admin access for an integration.  Instead integrators are highly encouraged to only enable the security roles for access that they need.

Click here to view our Security Role Matrix

When looking at the REST API documentation, you may notice that some items are considered a Setup Table value.  These are denoted with the lock icon.  These endpoints will return an inquire level of access without actually having access to the table.  This matches the UI functionality in that you can create listings of available statuses and boards without having access to the setup table associated for those values.

https://api-na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets/5000

https://api-na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets?conditions=board/name="Integration"%20and%20status/name="new"&page=1&pageSize=10

POST /v4_6_release/apis/3.0/service/tickets/search HTTP/1.1
Host: YOURCONNECTWISESITE
Authorization: Basic AUTHKEY=
Content-Type: application/json

Body:
{
     "conditions": "summary like 'test'"
}

https://api-na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets/5000

[
  {
    "op": "string",
    "path": "string",
    "value": "string"
  }
]

[
    {
        "op": "replace",
        "path": "summary",
        "value": "New Summary"
    },
    {
        "op": "replace",
        "path": "company",
        "value": {
            "identifier": "New Company"
        }
    },
    {
       "op": "replace",
       "path": "customFields",
       "value": [
            {
                 "id": 5,
                 "caption": "CloudPlus",
                 "type": "Checkbox",
                 "entryMethod": "EntryField",
                 "numberOfDecimals": 0,
                 "value": false
            },
               {          
                 "id": 28,
                 "caption": "test",
                 "type": "Text",
                 "entryMethod": "List",
                 "numberOfDecimals": 0,
                 "value": "test"
            }
        ]
    }
]

When updating an Object such as Company, you cannot specify a location inside of the object.  You have to replace the whole object like the example above. (Do not use "path":"company/identifier")  If you try to update the Object incorrectly, you may receive a false 200 message.

Successful patch requests will return a 200 status response for success

Delete

Delete requests are used for removing records from the ConnectWise Manage system.  Please take care when removing items as they cannot be recovered.  The id for the record to be deleted needs to be included in the request URL.

https://api-na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets/5000

Successful delete requests will return a 204 status response for No Content.  204 is a success response.

Post

Post is used when creating new records.  The body of the request must be send in a JSON format.  When sending a Post the response body will include the newly created record id as well as a Get request for the record.  If you pass a post request without filling out every possible value, the system will attempt to default all required information and anything that does not require a value, will be set to Null.

Put

Put requests are designed to completely replace an entity.  They work the in same manner as a Post request with the exception that you must specify an already created entity in your URL.  When you use Put to update a record, any field that has not been specified will be overridden with the system defaults or set to Null.

Escaping Characters

When working with JSON, you may find that you need to use characters that require escaping.  This comes into play primarily when quotes are involved as we do not support many of the characters that require escaping.  Refer to the chart below:

 URL Encoding is required for when using conditions and other URL parameters that have symbols that would denote new query parameters or strings.

Partial Responses

The API allows you to specify which information you want returned.  You do this by listing the request fields or columns on your endpoint URL.  Partial responses work for both GET and POST requests..

Custom Fields

Screens that have custom fields in the ConnectWise Manage UI will have an array of fields on the respective endpoint.  This array can be both queried and updated via the API.  When updating custom fields, you must pass in the entire array object, which means that you cannot patch a single custom field record.  Wondering if an endpoint supports custom fields?  Supported endpoints will have customFields(CustomFieldValue[]) listed at the end of the documentation.

There are two methods of adding new custom fields to the ConnectWise Manage environment.  The first method will require access to the ConnectWise Manage thick client and the second method is available in the system/userDefinedFields endpoint within the REST API.

Refer to the GET section on how to search custom fields.  Searching custom fields uses customFieldConditions instead of conditions.

In order to access the custom fields via the thick client, navigate to System > Setup Tables > Custom fields,

The ConnectWise Manage API provides a vast wealth of information for developers to consume.  Most of the time, you will find that there is far more information than is needed for an integration.  In order to ensure server availability, the API automatically sets page size to 25 results.  The maximum page size for any request can be up to 1,000 records if properly specific in the request URL.

When using paging, the response will include a Link header that looks like this:

If you notice, the header contains two separate URLs in this instance.  The first one is "next" and the second one is "last".  These refer to the next set of results and the final set of results.  If we navigate to the next page, we will get some additional URLs in the response Link header.

Now that we have navigated to the second page, we will find two additional URLs.  These are "prev" and "first" and in total we now have four including the original "next" and "last".

*We will not return the next or prev links if there isn't a next or prev respectively.

In the above examples, we have four pages of results and depending on the pagesize, that number can change.  For instance, lets say we switch to the default page size of 25.  Instead of returning four pages, we actually get back 7 pages as there are only 160 results.

The goal of pagination is not to pull every possible result, every single time.  Instead it is designed to be in conjunction with a UI component to create a set of navigation links.

Navigable Pagination closely follows RFC 5988.

ConnectWise Manage callbacks are payloads of information that are similar to webhooks.  When a record is saved within ConnectWise Manage, a summarized payload is sent to a specified location. 

https://webhook.site/xxxxxxx-xxxx-xxxx-af13-855ab85aebae

Troubleshooting with the REST API requires login access to the ConnectWise Manage UI.  Additionally the account being used to login, must have access to information relating to the account for integration.  In the case of the integration using API Members, the account accessing logs, must have the security roles to view members enabled.  This requirement has to do with the API Keys used for integrations, being tied to a specific member.

Logging with the REST API must be specifically turned on and there is a time limit of 1440 minutes or 24 hours that can be recorded in a single session.  During this time, all requests that are processed by the server and are associated to the member you are running logs from, will appear in the UI.  If you are getting errors from the API and logs are not appearing, it may be a server side issue.

To get started with logging, you will need to access the API Log tab found on every ConnectWise Manage member.  Open the UI and navigate to either System > Members or My Account and after you select the respective account, click on the API Logs tab.

Once you have found the API Logs tab, the next step will be to press "Start Debug Mode" and from there, select the amount of time you would like to record for.

Debugging will only run for a maximum of 1440 minutes per queue.  You can restart the timer at anytime by hitting "Start Debug Mode" again.

Do some asynchronous operation.
retries = 0
    DO
        wait for (2^retries * 100) milliseconds
        status = Get the result of the asynchronous operation.
        IF status = SUCCESS
            retry = false
        ELSE IF status = NOT_READY
            retry = true
        ELSE IF status = THROTTLED
            retry = true
        ELSE         
            Some other error occurred, so stop calling the API.         
            retry = false     
        END IF     
        retries = retries + 1 
WHILE (retry AND (retries < MAX_RETRIES))

When making calls to the ConnectWise Manage API, we have a URL that will give you the exact codebase to target in place of v4_6_release.  This is useful to see if someone is on a cloud environment programmatically.  Additionally the request can be routed directly to the correct ConnectWise Manage version for the partner without it going through another source.

"https://" + ConnectWiseSite + "/login/companyinfo/" + LoginCompanyId
https://na.myconnectwise.net/login/companyinfo/connectwise

{  
   "CompanyName":"ConnectWise",
   "Codebase":"v2017_3/",
   "VersionCode":"v2017.3",
   "VersionNumber":"v4.6.38842",
   "CompanyID":"CW",
   "IsCloud":"True" *Added in 2016.5
}

"https://" + ConnectWiseSite + "/" + codebase + "apis/3.0/company/companies"
https://api-my.myconnectwise.net/v2017_3/apis/3.0/company/companies

https://na.myconnectwise.net
https://eu.myconnectwise.net
https://au.myconnectwise.net
https://aus.myconnectwise.net
https://za.myconnectwise.net
https://staging.connectwisedev.com