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. Features that were dropped automatically when the number was dropped are reinstated automatically.

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

suspend

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

Parameters:

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

Example:

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

Parameters:

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

Example:

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

makeNonBillable

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

Parameters:

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

Example:

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

Parameters:

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

Example:

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