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

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