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.

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) - Date to also reinstate the customer’s numbers and features that were dropped on this date
• 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"
  }'

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