openapi: 3.0.3
info:
  title: Commusoft Authentication Customers API
  description: The Commusoft API is a RESTful JSON-based API designed to allow third parties to integrate products and applications with Commusoft's field service management platform. It enables programmatic management of jobs, customers, engineers, quotes, invoices, parts, and service histories for trades businesses including HVAC, plumbing, electrical, and building maintenance contractors. The API supports integrations with accounting tools (QuickBooks, Xero, Sage), payment processors (Stripe, GoCardless), and workflow automation platforms (Zapier).
  version: 1.0.0
  contact:
    url: https://www.commusoft.com/
  x-api-id: commusoft-api
  x-audience: external-partner
servers:
- url: https://api.commusoft.com/api/v1
  description: Commusoft production API server
security:
- ApiTokenHeader: []
- ApiTokenQuery: []
tags:
- name: Customers
  description: Manage customer records including addresses, contacts, and property details
paths:
  /customers:
    get:
      operationId: listCustomers
      summary: List Customers
      description: Retrieve a list of customers from the Commusoft system.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/UuidParam'
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCustomer
      summary: Create Customer
      description: Add a new customer record to the Commusoft system.
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{uuid}:
    get:
      operationId: getCustomer
      summary: Get Customer
      description: Retrieve a specific customer record by UUID.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/UuidPath'
      responses:
        '200':
          description: Customer record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCustomer
      summary: Update Customer
      description: Edit an existing customer record identified by UUID.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/UuidPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: Customer updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCustomer
      summary: Delete Customer
      description: Soft-delete a customer record. Commusoft never permanently deletes a customer; instead the record's Deleted field is set to 1.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/UuidPath'
      responses:
        '200':
          description: Customer soft-deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: integer
          description: Internal numeric ID
          readOnly: true
        uuid:
          type: string
          format: uuid
          description: Universally unique identifier for the customer
          readOnly: true
        title:
          type: string
          description: Title (Mr, Mrs, Dr, etc.)
        firstName:
          type: string
          description: Customer first name
        lastName:
          type: string
          description: Customer last name
        companyName:
          type: string
          description: Company name for business customers
        email:
          type: string
          format: email
          description: Primary email address
        telephone:
          type: string
          description: Primary telephone number
        mobile:
          type: string
          description: Mobile telephone number
        address:
          $ref: '#/components/schemas/Address'
        propertyDetails:
          $ref: '#/components/schemas/PropertyDetails'
        accountingSettings:
          $ref: '#/components/schemas/AccountingSettings'
        deleted:
          type: integer
          enum:
          - 0
          - 1
          description: Soft-delete flag; 1 indicates the record has been deleted
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message
        code:
          type: integer
          description: Error code
    PropertyDetails:
      type: object
      properties:
        propertyType:
          type: string
          description: Type of property (residential, commercial, etc.)
        numberOfBedrooms:
          type: integer
          description: Number of bedrooms
        yearBuilt:
          type: integer
          description: Year the property was built
        boilerMake:
          type: string
          description: Make of the boiler installed
        boilerModel:
          type: string
          description: Model of the boiler installed
    AccountingSettings:
      type: object
      properties:
        accountingReference:
          type: string
          description: External accounting system reference code
        vatNumber:
          type: string
          description: VAT registration number
        paymentTerms:
          type: integer
          description: Payment terms in days
    CustomerInput:
      type: object
      required:
      - uuid
      - lastName
      properties:
        uuid:
          type: string
          format: uuid
          description: UUID for the new customer record
        title:
          type: string
          description: Title (Mr, Mrs, Dr, etc.)
        firstName:
          type: string
          description: Customer first name
        lastName:
          type: string
          description: Customer last name
        companyName:
          type: string
          description: Company name for business customers
        email:
          type: string
          format: email
          description: Primary email address
        telephone:
          type: string
          description: Primary telephone number
        mobile:
          type: string
          description: Mobile telephone number
        address:
          $ref: '#/components/schemas/Address'
        propertyDetails:
          $ref: '#/components/schemas/PropertyDetails'
        accountingSettings:
          $ref: '#/components/schemas/AccountingSettings'
    Address:
      type: object
      properties:
        addressLine1:
          type: string
          description: First line of the address
        addressLine2:
          type: string
          description: Second line of the address
        town:
          type: string
          description: Town or city
        county:
          type: string
          description: County or region
        postcode:
          type: string
          description: Postcode or zip code
        country:
          type: string
          description: Country
  parameters:
    UuidParam:
      name: uuid
      in: query
      required: false
      description: Filter by UUID
      schema:
        type: string
        format: uuid
    UuidPath:
      name: uuid
      in: path
      required: true
      description: Unique identifier (UUID) of the record
      schema:
        type: string
        format: uuid
  responses:
    Unauthorized:
      description: Authentication token missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiTokenHeader:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: API token obtained from the /getToken endpoint
    ApiTokenQuery:
      type: apiKey
      in: query
      name: token
      description: API token passed as a query parameter