Customers

Methods

GET

Retrieve Single Customer

/backend/api/v1/customers/ID - fetch customer with specified ID.

List Customers

/backend/api/v1/customers/ - list all customers.

Additional Query Parameters

Search Example:

# Find customer by account number
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers?accountNumber=C12345"

# Find customer by CRM reference
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers?CRMReference=CRM-12345"

# Exclude dropped customers from search
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers?accountNumber=C12345&active=true"

Search Notes:

• The accountNumber parameter performs an exact match
• The CRMReference parameter performs an exact match
• Returns an array containing a single customer (or empty array if not found)
• Both account numbers and CRM references are unique, so searches return only one result
• Combining with filters like active can exclude dropped customers
• Optimised for performance using indexed fields

Expand with Filtering Example:

# Get customer with only active numbers included
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers/123?expandNumbers=true&numberActive=true"

# Get customer with active numbers and active features
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers/123?expandNumbers=true&numberActive=true&expandFeatures=true&featureActive=true"

# List customers with only active services expanded
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers?expandServices=true&serviceActive=true"

POST

/backend/api/v1/customers/ - add a new customer, the newly-added customer will be returned.

PATCH

/backend/api/v1/customers/ID - update customer with specified ID. The modified customer will be returned.

DELETE

/backend/api/v1/customers/ID - schedule deletion of customer with specified ID. The current details of the customer will be returned, and the customer record (including all resources linked to the customer) will be completely purged in 30 days.

Actions

Available Actions

drop

Drop (deactivate) a customer. This action changes the customer’s status to dropped and records the drop date.

Parameters:

• status (required) - The status name for the dropped customer (e.g., “Ex-Customer”)
• dateDrop (required) - The date the customer was dropped (format: YYYY-MM-DD)
• cancellationNoticeGivenDate (optional) - The date cancellation notice was given
• statusReason (optional) - Text explanation for dropping the customer
• ignoreTrafficNumberType (optional) - How to handle traffic on the customer’s numbers after dropping

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=drop \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Ex-Customer",
    "dateDrop": "2025-01-24",
    "statusReason": "Customer requested cancellation"
  }'

reinstate

Reinstate a previously dropped customer, returning them to active status. Numbers, services, and features that were dropped automatically when the customer was dropped are reinstated automatically.

Parameters:

• status (required) - The status name for the reinstated customer (e.g., “Active”)
• dateReinstate (required) - The date the customer is reinstated (format: YYYY-MM-DD)
• dateReinstateNumbersFeatures (optional) - Also reinstate numbers and features that were dropped independently on this date, in addition to those reinstated automatically
• statusReason (optional) - Text explanation for reinstating the customer

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=reinstate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active",
    "dateReinstate": "2025-01-24"
  }'

finalBill

Mark the customer as ready for their final bill. The actual final bill will be generated during the next billing run.

Parameters:

• status (required) - The status name for the final bill status (e.g., “Final Bill”)
• dateFinalBill (required) - The date the customer will be billed until (format: YYYY-MM-DD)
• cancellationNoticeGivenDate (optional) - The date cancellation notice was given
• statusReason (optional) - Text explanation for setting this customer to final bill status

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=finalBill \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Final Bill",
    "dateFinalBill": "2025-01-24"
  }'

suspend

Suspend a customer. This moves the customer to a suspended status. Recurring charges are suppressed while the customer is suspended, but usage charges still apply.

Parameters:

• status (required) - The status name for the suspended customer (e.g., “Suspended”)
• dateSuspend (optional) - The date the suspension takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for suspending the customer

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=suspend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Suspended",
    "dateSuspend": "2025-01-24"
  }'

unsuspend

Unsuspend a previously suspended customer, returning them to a non-suspended status. The platform back-fills any recurring charges that were missed during the suspension period.

Parameters:

• status (required) - The status name for the unsuspended customer (e.g., “Active”)
• dateUnsuspend (optional) - The date the unsuspension takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for unsuspending the customer

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=unsuspend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active",
    "dateUnsuspend": "2025-01-24"
  }'

makeNonBillable

Move a customer to a non-billable status. Automated billing runs skip the customer while non-billable, but manual invoices can still be raised. The customer’s active and suspended state is preserved.

Parameters:

• status (required) - The status name for the non-billable customer (e.g., “Active - Do Not Bill”)
• dateMakeNonBillable (optional) - The date the change takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for making the customer non-billable

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=makeNonBillable \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active - Do Not Bill",
    "dateMakeNonBillable": "2025-01-24"
  }'

makeBillable

Move a customer back to a billable status. The platform back-fills any recurring charges that were missed while the customer was non-billable. The customer’s active and suspended state is preserved.

Parameters:

• status (required) - The status name for the billable customer (e.g., “Active”)
• dateMakeBillable (optional) - The date the change takes effect (format: YYYY-MM-DD). Defaults to today.
• statusReason (optional) - Text explanation for making the customer billable

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=makeBillable \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Active",
    "dateMakeBillable": "2025-01-24"
  }'

generatePIN

Generate a new PIN for the customer.

Response: Returns only the generated PIN, not the full customer record.

{
  "pin": "1234"
}

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=generatePIN \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

addSharedContact

Add a shared contact to the customer.

Parameters:

• sharedContactID (required) - The ID of the shared contact to add

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=addSharedContact \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sharedContactID": 456
  }'

removeSharedContact

Remove a shared contact from the customer.

Parameters:

• sharedContactID (required) - The ID of the shared contact to remove

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=removeSharedContact \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sharedContactID": 456
  }'

linkToXero

Link the customer to Xero accounting system.

Parameters:

• xeroID (required) - The UUID of the customer in Xero

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=linkToXero \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "xeroID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

unlinkFromXero

Unlink the customer from Xero accounting system.

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=unlinkFromXero \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

restoreCalls

Restore deleted calls for the customer.

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=restoreCalls \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

writeOffDebt

Write off any outstanding debt for the customer. This action creates a credit note for the full outstanding amount, leaving the customer’s balance at zero. The customer must be dropped before performing this action.

Parameters:

• dateWriteoff (required) - The date the debt is written off (format: YYYY-MM-DD)
• vatTreatment (optional) - How VAT should be handled on the write-off:
  • standard (default) - Apply VAT pro-rata based on original transactions
  • vat_exempt - Create VAT-exempt write-off (no VAT reclaim)

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=writeOffDebt \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateWriteoff": "2025-01-24"
  }'

writeOffCredit

Write off any outstanding credit balance for the customer. This action creates a debit note to reclaim the customer’s credit, leaving the balance at zero. The customer must be dropped and must have a credit balance (no outstanding debt) before performing this action.

Parameters:

• dateWriteoff (required) - The date the credit is written off (format: YYYY-MM-DD)
• vatTreatment (optional) - How VAT should be handled on the write-off:
  • standard (default) - Apply VAT pro-rata based on original transactions
  • vat_exempt - Create VAT-exempt write-off

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=writeOffCredit \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateWriteoff": "2025-01-24"
  }'

generatePaymentLinks

Generate no-login payment URLs for the customer. The customer must have a MyAccount profile assigned.

Response: Returns the payment link UUID and an array of available links (not the full customer record). The available links depend on the customer’s MyAccount profile and configured payment providers.

{
  "success": true,
  "paymentLinkUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "links": [
    {
      "type": "cardPayment",
      "providerName": "Stripe",
      "label": "Card Payment (Stripe)",
      "url": "https://..."
    },
    {
      "type": "directDebitSetup",
      "providerName": "GoCardless",
      "label": "Direct Debit Setup (GoCardless)",
      "url": "https://..."
    }
  ]
}

If no payment methods are enabled, the response contains an empty links array:

{
  "success": true,
  "paymentLinkUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "links": []
}

Error codes:

• 500521 - Payment link generation failed

Example:

curl -X POST https://example.com/backend/api/v1/customers/123?action=generatePaymentLinks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Format

Unless otherwise stated (e.g., generatePIN, generatePaymentLinks), actions return the updated customer object in JSON format, using the same structure as GET requests.

Error Handling

If an action fails, the API will return an appropriate HTTP status code with error details:

{
    "error": "Invalid Action",
    "error_code": 400502,
    "hint": "The action was not performed"
}

Common error codes:

• 400501 - Action not recognised
• 400502 - Action failed to execute
• 400503 - Missing required parameters
• 403xxx - Permission denied

Fields