Features

Methods

GET

Retrieve Single Feature

/backend/api/v1/features/ID - fetch feature with specified ID.

List Features

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

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

/backend/api/v1/customers/ID/features/?includeNumbers - list features belonging to customer with specified ID, including those on numbers owned by the customer.

/backend/api/v1/numbers/ID/features/ - list features belonging to number with specified ID.

Additional Query Parameters

Search Example:

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

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

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

# Search within a specific number's features
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers/456/features?CRMReference=CRM-12345"

Search Notes:

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

POST

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

/backend/api/v1/numbers/ID/features/ - add a new feature to the specified number, the newly-added feature will be returned.

PATCH

/backend/api/v1/features/ID - update feature with specified ID. The modified feature will be returned.

DELETE

/backend/api/v1/features/ID - delete feature with specified ID.

Actions

Available Actions

drop

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

Parameters:

• status (required) - The status name for the dropped feature (e.g., “Dropped”)
• dateDrop (required) - The date the feature was dropped (format: YYYY-MM-DD)
• dateBillTo (optional) - Override the calculated bill-to date. If not provided, the system calculates the appropriate date based on the feature type, drop date, and notice period
• statusReason (optional) - Text explanation for dropping the feature

Example:

curl -X POST https://example.com/backend/api/v1/features/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 feature, returning it to active status.

Parameters:

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

Example:

curl -X POST https://example.com/backend/api/v1/features/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 feature 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