Cellcast Documentation

Appearance

Purchase Virtual Number (Postpaid) ​

This API is used to purchase a virtual number for postpaid billing accounts. Postpaid users receive a consolidated invoice at the end of each month for all their dedicated numbers, without requiring a credit card at the time of purchase.

Prerequisites ​

  • Your account must be enabled for postpaid dedicated number billing by a Cellcast administrator
  • Contact Cellcast support to enable postpaid billing for your account

Parameters for Purchasing Virtual Number (Postpaid) ​

Headers Parameters ​

ParametersDescription
AuthorizationPlease add provided Bearer token - linked to your Cellcast account. Check here
Content-Typeapplication/json

Request Body Parameters ​

NameExampleDescription
number66ea98514f0c1a121c76ec17Required. The ID of the virtual number to purchase.
resubscribefalseOptional. Whether this is a resubscription of a previously owned number.

Postpaid Billing Notes

  • No payment is required at the time of purchase
  • A consolidated invoice will be sent at the end of each month
  • The invoice includes all dedicated numbers purchased during the billing period
  • Pro-rated charges apply for numbers purchased mid-month
  • GST is calculated and added to the invoice for Australian customers

Code Samples ​

Post https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase-postpaid

bash
curl --location 'https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase-postpaid' \
--header 'authorization: Bearer {{API_KEY}}' \
--header 'content-type: application/json' \
--data '{
    "number": "66ea98514f0c1a121c76ec17",
    "resubscribe": false
}'
javascript
const response = await fetch(
  "https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase-postpaid",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {{API_KEY}}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      number: "66ea98514f0c1a121c76ec17",
      resubscribe: false
    })
  }
);

const data = await response.json();
console.log(data);
php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase-postpaid',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer {{API_KEY}}',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'number' => '66ea98514f0c1a121c76ec17',
        'resubscribe' => false
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
?>
python
import requests

url = "https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase-postpaid"

headers = {
    "Authorization": "Bearer {{API_KEY}}",
    "Content-Type": "application/json"
}

payload = {
    "number": "66ea98514f0c1a121c76ec17",
    "resubscribe": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Replace with the actual API key that you own.

Responses ​

200 Success

json
{
  "app_type": "web",
  "app_version": "1.0",
  "maintainence": 0,
  "new_version": 0,
  "force_update": 0,
  "invalid_token": 0,
  "refresh_token": "",
  "show_message": 1,
  "is_enc": false,
  "status": true,
  "message": "Dedicated Number has been assigned to your account. You will receive an invoice at the end of the billing period.",
  "message_type": "toast",
  "data": {
    "dedicatedNumber": {
      "_id": "66ea98514f0c1a121c76ec17",
      "number": "+61412345678",
      "billingType": "postpaid",
      "expirationDate": "2024-01-31T23:59:59.999Z"
    }
  },
  "error": {}
}

400 Bad Request - Account Not Enabled for Postpaid

json
{
  "status": false,
  "message": "Your account is not enabled for postpaid dedicated number billing. Please contact support.",
  "message_type": "inline",
  "data": {},
  "error": {
    "billing": "Account not enabled for postpaid billing"
  }
}

400 Bad Request - Missing Parameters

json
{
  "status": false,
  "message": "product, number and recurring_time parameters are required",
  "message_type": "inline",
  "data": {},
  "error": {
    "params": "Missing required parameters"
  }
}

400 Bad Request - Number Not Available

json
{
  "status": false,
  "message": "This virtual number is not available for purchase",
  "message_type": "inline",
  "data": {},
  "error": {
    "number": "Number not available"
  }
}

401 Unauthorized

json
{
  "code": 401,
  "message": "Token expired",
  "stack": "APIError: Token expired ...."
}

How Postpaid Billing Works ​

  1. Purchase: When you purchase a virtual number using this API, the number is immediately assigned to your account with no upfront payment required.

  2. Billing Period: The billing period runs from the 1st to the last day of each month.

  3. Pro-rated Charges: If you purchase a number mid-month, you will only be charged for the remaining days in that month.

  4. Invoice Generation: At the end of each month, a consolidated invoice is generated that includes:

    • All dedicated numbers active during the billing period
    • Pro-rated charges for any numbers purchased mid-month
    • GST (for Australian customers)

  5. Invoice Delivery: The invoice is sent via email and is also available in Stripe for payment.

See Also ​