Numbers

Methods

GET

Retrieve Single Number

/backend/api/v1/numbers/ID - fetch number with specified ID.

List Numbers

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

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

Additional Query Parameters

Search Example:

# Find number - spaces and dashes are automatically removed
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers?number=02079460000"

# Search works with formatted numbers too
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers?number=020%207946%200000"

# Alternative formatting
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers?number=020-7946-0000"

# Find only active numbers
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers?number=02079460000&active=true"

# Search within a specific customer's numbers
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers/123/numbers?number=02079460000"

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

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

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

Search Notes:

• The number parameter performs an exact match
• Spaces and dashes are automatically removed from the search term
• Formats like 020 7946 0000 and 020-7946-0000 will match 02079460000
• The CRMReference parameter performs an exact match
• Returns an array containing a single number (or empty array if not found)
• CRM references are unique, so only one result is expected
• Can be used with customer-specific endpoints: /backend/api/v1/customers/{id}/numbers?number={number} or /backend/api/v1/customers/{id}/numbers?CRMReference={reference}
• Combining with filters like active can exclude dropped numbers
• Optimised for performance using indexed fields

Expand with Filtering Example:

# Get number with only active features included
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/numbers/456?expandFeatures=true&featureActive=true"

# List customer's numbers with active features expanded
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "/backend/api/v1/customers/123/numbers?expandFeatures=true&featureActive=true"

POST

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

PATCH

/backend/api/v1/numbers/ID - update number with specified ID. The modified number will be returned.

DELETE

/backend/api/v1/numbers/ID - delete number with specified ID.

Actions

Available Actions

drop

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

Parameters:

• status (required) - The status name for the dropped number (e.g., “Dropped”)
• dateDrop (required) - The date the number 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 number
• ignoreTrafficNumberType (optional) - Name of the ignore traffic type to apply (automatically creates ignore traffic number entries for call data exclusion)

Example:

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

Parameters:

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

Example:

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