Services

Methods

GET

Retrieve Single Service

/backend/api/v1/services/ID - fetch service with specified ID.

List Services

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

/backend/api/v1/customers/ID/services/ - list services belonging to customer with specified ID.

Additional Query Parameters

Parameter	Type	Required	Description
CRMReference	string	No	Search for services by exact CRM reference
dropped	flag	No	Show only dropped services
active	flag	No	Show only active services
serviceType	string	No	Show services of the specified type
droppedSince	datetime	No	Only include services dropped since
reinstatedSince	datetime	No	Only include services reinstated since
featureActive	flag	No	When expanding features, only include active features

Search Example:

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

# Find only active services by CRM reference
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/services?CRMReference=CRM-12345&active=true"

# Search within a specific customer's services
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers/123/services?CRMReference=CRM-12345"

# Expand features but only show active ones
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/services/123?expandFeatures=true&featureActive=true"

Search Notes:

• The CRMReference parameter performs an exact match
• Returns an array containing a single service (or empty array if not found)
• CRM references are unique, so only one result is expected
• Can be used with customer-specific endpoints
• Combining with filters like active can exclude dropped services
• Use featureActive with expandFeatures to filter expanded feature data
• Optimised for performance using indexed fields

POST

/backend/api/v1/customers/ID/services/ - add a new service to the specified customer, the newly-added service will be returned.

PATCH

/backend/api/v1/services/ID - update service with specified ID. The modified service will be returned.

DELETE

/backend/api/v1/services/ID - delete service with specified ID.

Actions

Available Actions

drop

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

Parameters:

• status (required) - The status name for the dropped service (e.g., “Dropped”)
• dateDrop (required) - The date the service was dropped (format: YYYY-MM-DD)
• cancellationNoticeGivenDate (optional) - The date cancellation notice was given (may affect notice period billing)
• statusReason (optional) - Text explanation for dropping the service

Example:

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

reinstate

Reinstate a previously dropped service, returning it to active status. Features that were dropped automatically when the service was dropped are reinstated automatically.

Parameters:

• status (required) - The status name for the reinstated service (e.g., “Active”)
• dateReinstate (required) - The date the service is reinstated (format: YYYY-MM-DD)
• statusReason (optional) - Text explanation for reinstating the service

Example:

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

suspend

Suspend a service. This moves the service to a suspended status. Recurring charges on the service’s features are suppressed while the service is suspended, but usage charges still apply.

Parameters:

• status (required) - The status name for the suspended service (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 service

Example:

curl -X POST https://example.com/backend/api/v1/services/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 service. The platform back-fills any recurring charges that were missed during the suspension period.

Parameters:

• status (required) - The status name for the unsuspended service (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 service

Example:

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

makeNonBillable

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

Parameters:

• status (required) - The status name for the non-billable service (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 service non-billable

Example:

curl -X POST https://example.com/backend/api/v1/services/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 service back to a billable status. The platform back-fills any recurring charges that were missed while the service was non-billable. The service’s active and suspended state is preserved.

Parameters:

• status (required) - The status name for the billable service (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 service billable

Example:

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

Response Format

Actions return the updated service 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

Field	Name	Type	Description
customerID	Customer	Text	The ID of the customer who owns this service
serviceType	Service Type	Preset Value	The type of this service
serviceName	Service Name	Text	A short name or reference for this service
description	Description	Text	Description of this service
site	Site	Text	Site where this service is provided or billed
campaign	Campaign	Text	Marketing campaign associated with this service
status	Service Status	Preset Value	Status name for this service
statusChangedStamp	Status Changed Date	Date	Date when the status of this service was last changed
updatedDate	Dropped / Reinstated Date	Date	Date when this service was most recently dropped or reinstated
statusReason	Status Reason	Preset Value	Reason for the current status of this service
cancellationNoticeGivenDate	Cancellation Notice Given	Date	Date when cancellation notice was given for this service
annualIncreaseReferenceDate	Annual Increase Reference Date	Date	Reference date used for annual increases for this service. Depending on how annual increases are managed, this can be the next increase date or the previous increase date.
annualIncreaseProfile	Annual Increase Profile	Preset Value	Annual increase profile name for this service
customerProducts	Customer Products	Preset Value(s)	Products associated with this service
internalUse	Internal Use	Text	Internal notes or references for this service
CRMReference	CRM Reference	Text	Reference for this service in the CRM system
soldBy	Sold By	Preset Value	User who sold this service
soldDate	Date Sold	Date	Date when this service was sold
enteredDate	Entered Date	Date	Date when this service was entered into the system
saleType	Sale Type	Preset Value	Type of sale for this service
postcode	Postcode	Text	Postcode associated with this service
contractEndDate	Contract End Date	Date	Date when the contract for this service ends
provisionStatus	Provision Status	Number	Internal provisioning status for this service
provider	Provider	Preset Value	Provider/carrier used for this service
providerReference	Provider Reference	Text	Reference used by the provider for this service
providerServiceType	Provider Service Type	Text	Provider-specific service type or product code
providerSubAccount	Provider Sub-account	Text	Provider sub-account reference, if applicable
fixedFeeTariff	Default Fixed Fee Tariff	Preset Value	Default fixed fee tariff to use for features attached to this service
id	Service ID	Text	The unique identifier for this service