Requests and responses

The Commusoft v2 API follows RESTful principles, using standard HTTP methods and JSON for all data exchange.

Request Fundamentals

Content Type
All requests that include a body (POST and PATCH) must include the following header:
Content-Type: application/json

Naming Convention
We use camelCase for all JSON keys in both request bodies and response payloads.

Correct: "firstName": "John"
Incorrect: "first_name": "John"

Response Structure

Success Responses
Standard successful requests return a 200 OK (for fetches/updates) or 201 Created (for new resources).

Error Handling
When a request fails, the API returns a relevant HTTP status code and a JSON error object to help you identify the issue.

400 - Validation failed
The request data is missing or invalid.

401 - Unauthorized
The API Key is missing, invalid, or expired.

403 - Forbidden
You do not have permission to access this specific resource.

404 - Resource not found
The requested ID does not exist.

429 - Too many requests
You have exceeded your rate limit quota.

Error payload example

{
  "error": {
    "code": "validationFailed",
    "message": "The request contained invalid data.",
    "details": [
      {
        "field": "postcode",
        "reason": "Postcode is a required field"
      }
    ]
  }
}

Date & time format
All timestamps are returned and expected in ISO 8601 UTC format:
YYYY-MM-DDTHH:MM:SS.SSSZ (e.g., 2026-03-02T10:42:00.000Z).

Request Fundamentals#

Response Structure#

Request Fundamentals

Response Structure