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.

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"
  }'

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