Available on:
UK: Customer Journey, Automation
US: Customer Journey, Field Automation
Currently in a closed Beta.
The Commusoft API lets you connect your Commusoft data to your own tools, like internal dashboards, reports, or automations. You get access by creating a private application. It gives your developer an API key and, if you need them, webhooks that tell your system when something changes.
Before you start
You need a developer: Your developer builds and maintains your integration. Commusoft support doesn't build integrations or help with code.
Developer documentation: Your developer will find endpoints, authentication, rate limits, and webhook details at developer.commusoft.com.
Your account only: A private application only connects to your own Commusoft account.
No developer? The Zapier integration connects Commusoft to thousands of other apps without code. Learn more about the Zapier integration.
How to create a private application
âĄď¸ Click Settings > Private applications
The Private applications page lists any applications your business already has.
Step 1: Add basic details
Click Add new private application.
Enter an Application name. It appears in audit history when the application creates or updates records, so make it easy to recognize.
Enter a Description that reminds you what the application is for.
Click Next.
Step 2: Choose scopes
Scopes control what the API key can do. Each area has separate read, write, and delete scopes, for example jobs.jobs.read.
Click Add new scopes.
Select the scopes your integration needs, then click Save.
Check the list of selected scopes. To remove one, click Delete next to it.
Click Next.
Only choose the scopes your integration needs. If a key is ever exposed, fewer scopes limit what it can reach. You can add more later.
Step 3: Set up webhooks (optional)
Webhooks notify your system when a job, opportunity, or property is created, updated, or deleted. Your system doesn't need to keep checking Commusoft for changes.
Under Do you need to setup webhooks?, select Yes or No.
If you select Yes, enter the Target URL your developer gives you. It must start with
https://.Under Contact details for webhook failures, enter the email address to notify if a webhook fails.
Click Continue.
Step 4: Copy your API key
The last step shows your API Key and, if you set up webhooks, your Webhook Secret.
Click Copy next to API Key. Store the key somewhere secure, like a password manager.
If you set up webhooks, click Copy next to Webhook Secret. Your developer uses it to check that notifications really come from Commusoft.
Click Finish.
Treat your API key like a password. Anyone who has it can reach your Commusoft data within its scopes. Only share it through a secure channel, and never in a support chat.
Manage your private applications
âĄď¸ Click Settings > Private applications
Each application shows its name, description, last updated date, and owner. Use View, Edit, or Delete next to an application to manage it.
View activity and logs
Click View next to an application. It has four tabs:
Overview: Charts of API calls and webhook calls over the last 7 active days, split into successful calls and client errors
Authentication: Your API key and webhook secret, and the scopes each one has
API logs: Each request your integration made, with the time, method, request URL, and response
Webhook logs: Each webhook Commusoft sent, with the time, event, event ID, and response
Find errors in your logs
Your logs show exactly what your integration sent and what came back. Start here when something isn't working.
Click View next to the application.
On the Overview tab, check the charts for client errors. They show which days had problems.
Click the API logs tab. Search by request URL, or click Add filter to narrow the list.
Check the Response column to see what Commusoft returned, then look up the status code in the status codes table below.
For webhooks, click the Webhook logs tab. Search by event ID, or click Add filter to narrow the list. The Response column shows how your system replied to each notification.
Note the time, status code, and request URL of any error. Your developer needs them, and so does Commusoft support for a 5xx error.
Change scopes or webhook settings
Click Edit next to the application to update its details, scopes, or webhook settings.
Regenerate an API key
Regenerate your key straight away if it's lost or might have been exposed.
Click View next to the application.
Click the Authentication tab.
Click Regenerate next to the API key.
Update your integration with the new key.
Your old key stops working as soon as you regenerate it. Your integration can't connect until it uses the new key.
Delete a private application
Click Delete next to the application.
Type Delete in the box, then click Delete.
Deleting an application is permanent. It removes the application, its API credentials, and its webhook settings. Any integration using it stops working.
What Commusoft support covers
Your developer owns your integration, from building it to fixing its errors. Commusoft support steps in when the API itself has a problem.
Commusoft support can help with:
Server errors: Any 5xx status code, or the API not working the way the developer documentation describes
Your private application: Setting it up in Commusoft, choosing scopes, and finding your logs
Your developer handles:
Your integration: Building it, testing it, and keeping it running
Request errors: 4xx status codes, like 400, 401, 403, 404, and 429
Data changes: Repairing records your integration created, changed, or deleted by mistake. If you'd like Commusoft's help, it's a chargeable service.
Test your integration carefully before you run it on your live account. A small mistake, like a loop that repeats the same request, can create thousands of unwanted records.
API status codes and errors
Every API response includes a status code. It tells your developer whether the request worked and, if it didn't, why.
Status code | What it means | What to do |
200 OK | The request worked. Commusoft returned or updated the data. | Nothing. If your tool doesn't show the data, your developer checks how it reads the response. |
201 Created | The request worked. Commusoft created a new record. | Nothing. |
400 Validation failed | Data in the request was missing or invalid. The error message names the field. | Your developer corrects the data and sends the request again. |
401 Unauthorized | The API key is missing, invalid, or expired. | Your developer checks they're using your current key and the right address for your region, UK or US. |
403 Forbidden | The API key doesn't have permission for this action, usually because a scope is missing. | Edit the private application and add the missing scope. |
404 Resource not found | The record ID doesn't exist. | Your developer checks the ID is correct and belongs to your account. |
429 Too many requests | Your integration went over the rate limit. | Your developer spaces out requests and waits for the limit to reset. |
5xx, for example 500 | Something went wrong on Commusoft's side. | Check status.commusoft.com. If there's no known issue, contact Commusoft support with the time, status code, and request URL from your API logs. |
Rate limits and 429 errors
The API allows 60 requests per minute for each API key, counted over a rolling 60 seconds. Every response tells your developer how many requests are left and when the limit resets.
If your integration keeps sending requests after a 429, it can be blocked for longer. Your developer should pause until the limit resets, then space out requests. Using webhooks instead of repeatedly checking for changes also helps.
If your integration regularly needs more than 60 requests a minute, talk to your Success Partner about options.
Common questions
Which plans include the Commusoft API?
Which plans include the Commusoft API?
The Commusoft API is included on Customer Journey and Automation in the UK, and on Customer Journey and Field Automation in the US. If you're on a different plan, your Success Partner can talk you through upgrading.
Can Commusoft support help build or fix my integration?
Can Commusoft support help build or fix my integration?
Commusoft support can't build, review, or fix integrations or code. Your developer handles this, using the developer documentation at developer.commusoft.com. Support can help with 5xx server errors and with setting up your private application.
What data can the Commusoft API access?
What data can the Commusoft API access?
The Commusoft API covers customers and properties, contacts, scheduled activities, opportunities, and jobs, plus some settings lists. The scopes you choose control what each key can reach. Your developer can check the current list in the developer documentation.
Can I have more than one private application?
Can I have more than one private application?
Yes, you can have more than one private application, for example one for each integration. Give each one a clear name and description so you can tell them apart.
What should I do if my API key is exposed?
What should I do if my API key is exposed?
If your API key is exposed, regenerate it straight away from the application's Authentication tab. Then update your integration with the new key.
Why have my webhook notifications stopped?
Why have my webhook notifications stopped?
Webhook notifications stop when your system doesn't accept them. Your Webhook logs tab shows each notification and how your system replied. Commusoft retries a failed notification up to 10 times over 24 hours. If your endpoint keeps failing for more than 48 hours, Commusoft pauses the webhook and emails your failure contact. Notifications from the paused period aren't resent, so your developer should fetch any missed changes through the API. Once the endpoint is fixed, unpause the webhook from your private application.