CommTrak API

Overview

To access the CommTrak API, a short-lived access token (valid for 1 hour) is required for authentication. This article explains how to obtain and use the access token when interacting with various API endpoints. All requests to the API must include the required authentication headers, as described below.

The complete API reference is available at https://resources.commtrak.com.au/api/v1/

Client ID and Client Secret

Before you can obtain an access token, you will need to create a Client ID and a Client Secret for your application. You can learn how do this in the Applications article.

Base URL

All API endpoints are accessed via the base URL:

https://yourorg.commtrak.com.au:443/api/v1

Authentication: Obtaining an Access Token

To authenticate and use the API, you need to first obtain an access token using the OAuth2 client_credentials grant. The access token is valid for 1 hour, after which a new token must be requested.

Endpoint for Access Token Request

Request URL:

POST https://yourorg.commtrak.com.au/api/oauth2

Headers:

  • Authorization: Basic {client_credentials}

    The credentials must be sent as a Base64-encoded string in the format:

    client_id:client_secret .

  • Content-Type: application/x-www-form-urlencoded

Body Parameters:

grant_type=client_credentials

Example Request:

bash curl -X POST https://yourorg.commtrak.com.au/api/oauth2 \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials"

Response:

A successful response will return an access token in JSON format:

json { "access_token": "your-access-token", "token_type": "Bearer", "expires_in": 3600 }

Using the Access Token

Once you have obtained the access token, it must be included in the Authorization header of all API requests to authenticate.

Required Headers for API Requests

For any request to the API, include the following headers:

  • Authorization: Bearer {access_token}

    Replace {access_token} with the token obtained from the previous step.

  • Content-Type: application/json

    For POST, PUT, or PATCH requests, ensure that you set the Content-Type to application/json .

Example API Requests

The following are examples of using CommTrak API endpoints for reading and updating a CommTrak customer record. Please refer to the CommTrak API reference for details of all available endpoints: https://resources.commtrak.com.au/api/v1/

1. Searching for Customers

API reference:

https://resources.commtrak.com.au/api/v1/#/Customer/get_search_customer

Endpoint:

GET https://yourorg.commtrak.com.au:443/api/v1/search/customer?company_name={companyName}

Headers:

  • Authorization: Bearer {access_token}

Example Request:

bash curl -X GET "https://yourorg.commtrak.com.au:443/api/v1/search/customer?company_name=AcmeCorp" \ -H "Authorization: Bearer your-access-token"

Response:

A successful response will return a list of customers in JSON format:

[ { "company_name": "Acme Corporation", "customer_id": 12345 }, ... ]

2. Fetching Customer Details

API Reference:

https://resources.commtrak.com.au/api/v1/#/Customer/get_customer_existing__customer_id_

Endpoint:

GET https://yourorg.commtrak.com.au:443/api/v1/customer/existing/{customerId}

Headers:

  • Authorization: Bearer {access_token}

Example Request:

bash curl -X GET "https://yourorg.commtrak.com.au:443/api/v1/customer/existing/12345" \ -H "Authorization: Bearer your-access-token"

Response:

A successful response will return the customer's details in JSON format:

{ "company_name": "Acme Corporation", "customer_id": 12345, "address1": "123 Main St", "email": "info@acmecorp.com.au", "phone": "0893150000" }

3. Updating Customer Details

API Reference:

https://resources.commtrak.com.au/api/v1/#/Customer/put_customer_existing__customer_id_

Endpoint:

PUT https://yourorg.commtrak.com.au:443/api/v1/customer/existing/{customerId}

Headers:

  • Authorization: Bearer {access_token}
  • Content-Type: application/json

Example Request:

bash curl -X PUT "https://yourorg.commtrak.com.au:443/api/v1/customer/existing/12345" \ -H "Authorization: Bearer your-access-token" \ -H "Content-Type: application/json" \ -d '{ "company_name": "Updated Acme Corporation", "state": "NSW" }'

Response:

If the update is successful, you will receive a confirmation response in JSON format:

{ "customer_id": 12345, company_name": "Updated Acme Corporation" }

Token Expiry and Renewal

The access token will expire after 1 hour (3600 seconds). When the token expires, you must obtain a new token by following the steps under Authentication: Obtaining an Access Token.