API local numbers provisioning ·

Home ›Features ›API Hub ›API local numbers provisioning ·

DID Number Provisioning API

Search available DIDs, assign numbers to your account, configure forwarding, list purchased numbers, and release DIDs programmatically. Build number management directly into your application.

Create Account Back to API Hub

What Is DID Provisioning?

DID (Direct Inward Dialing) provisioning is the process of programmatically acquiring a local phone number and configuring where inbound calls are delivered. Using the PBXMe API, your application can list available DIDs, assign a selected DID to your account, configure its forwarding destination, list purchased DIDs, and release a DID when it is no longer required.

API Endpoint Reference

Before using the API, whitelist the source IP address of the server making the requests in the user’s account portal. The initial Login call uses HTTP POST with a JSON body, the account-specific username/password, and the fixed x-auth-token published in the API documentation. A successful Login returns the account id, account_token, and a generated session x-auth-token. Use that session x-auth-token in the request header for all subsequent API calls in the same session, while the returned id and account_token are sent in the request body as the documented id and token values. Base URL: https://newsip.israelnumber.com

EndpointWhat It DoesKey Parameters
POST /api/login/Log in and receive id, account_token, and the generated session x-auth-token used by subsequent callsusername, password
POST /customer/did_crud/Search available DIDs in a country (action=available_list)action, parent_id, country_id (optional), id, token
POST /customer/did_management/Purchase and assign a DID to your account (action=assign)action, did_id, accountid, reseller_id, id, token
POST /customer/did_crud/List all DIDs purchased on your account (action=purchase_list)action, id, token
POST /customer/did_management/Set call forwarding — always, on busy, not registered, or no answeraction, did_id, call_type, call_type_value, always, user_busy, user_not_registered, no_answer, extensions, call_type_vm_flag, always_destination, always_vm_flag, user_busy_destination, user_busy_vm_flag, user_not_registered_destination, user_not_registered_vm_flag, no_answer_destination, no_answer_vm_flag, id, token
POST /customer/did_management/Release a DID and remove it from your account (action=release)action, did_id, accountid, id, token

Complete Flow: Search → Order → Configure → Release

Full Python example walking through the entire DID lifecycle.

import requests

BASE = "https://newsip.israelnumber.com"

# Before calling the API, whitelist this server's source IP
# in the user's PBXMe account portal.
INITIAL_HEADERS = {
    "x-auth-token": "YOUR_INITIAL_X_AUTH_TOKEN",
    "Content-Type": "application/json"
}

# ── 1. Login with the fixed initial x-auth-token ─────────────
res = requests.post(
    f"{BASE}/api/login/",
    headers=INITIAL_HEADERS,
    json={
        "username": "YOUR_ACCOUNT_NUMBER",
        "password": "YOUR_PASSWORD"
    }
)
res.raise_for_status()

login_data = res.json()
account_id = login_data["id"]
token = login_data["account_token"]
session_x_auth_token = login_data["x-auth-token"]

# Use the generated session x-auth-token after Login.
SESSION_HEADERS = {
    "x-auth-token": session_x_auth_token,
    "Content-Type": "application/json"
}

# ── 2. List available DIDs ──────────────────────────────────
# country_id is the optional numeric country ID provided in the Country List reference/example.
avail = requests.post(
    f"{BASE}/customer/did_crud/",
    headers=SESSION_HEADERS,
    json={
        "action": "available_list",
        "parent_id": "0",
        "country_id": "YOUR_COUNTRY_ID",
        "id": account_id,
        "token": token
    }
)
available_data = avail.json()
print("Available DIDs:", available_data)

# ── 3. Assign a DID ─────────────────────────────────────────
# did_id comes from the DID Available List response.
chosen_id = "YOUR_DID_ID"

assign = requests.post(
    f"{BASE}/customer/did_management/",
    headers=SESSION_HEADERS,
    json={
        "action": "assign",
        "did_id": chosen_id,
        "accountid": account_id,
        "reseller_id": "0",
        "id": account_id,
        "token": token
    }
)
print("Assigned:", assign.json())

# ── 4. Set DID forwarding ───────────────────────────────────
# The supplied reference example uses call_type=2 and a trunk IP
# as call_type_value. did_id here should be the purchased DID ID.
forwarding = requests.post(
    f"{BASE}/customer/did_management/",
    headers=SESSION_HEADERS,
    json={
        "action": "forward",
        "did_id": "YOUR_PURCHASED_DID_ID",
        "call_type": "2",
        "call_type_value": "YOUR_TRUNK_IP",
        "always": "5",
        "user_busy": "5",
        "user_not_registered": "5",
        "no_answer": "5",
        "extensions": "",
        "call_type_vm_flag": "",
        "always_destination": "",
        "always_vm_flag": "",
        "user_busy_destination": "",
        "user_busy_vm_flag": "",
        "user_not_registered_destination": "",
        "user_not_registered_vm_flag": "",
        "no_answer_destination": "",
        "no_answer_vm_flag": "",
        "id": account_id,
        "token": token
    }
)
print("Forwarding configured:", forwarding.json())

# ── 5. List purchased DIDs ──────────────────────────────────
my_dids = requests.post(
    f"{BASE}/customer/did_crud/",
    headers=SESSION_HEADERS,
    json={
        "action": "purchase_list",
        "id": account_id,
        "token": token
    }
)
print("Purchased DIDs:", my_dids.json())

# ── 6. Release a DID ────────────────────────────────────────
release = requests.post(
    f"{BASE}/customer/did_management/",
    headers=SESSION_HEADERS,
    json={
        "action": "release",
        "did_id": "YOUR_PURCHASED_DID_ID",
        "accountid": account_id,
        "id": account_id,
        "token": token
    }
)
print("Released:", release.json())

More API Guides

FAQ — DID Provisioning API

How do I buy a virtual phone number via API?

First whitelist the source IP of the server making the API calls in your account portal. Log in with your account username/password and the fixed initial x-auth-token from the API documentation. A successful Login returns your account id, account_token, and a generated session x-auth-token. Use the session x-auth-token in subsequent request headers. Then call DID Available List (/customer/did_crud/, action=available_list) using the optional numeric country_id provided in the Country List reference/example. Use DID Assign (/customer/did_management/, action=assign) with the selected did_id, your accountid, reseller_id, id, and token.

Can I release a number programmatically when I no longer need it?

Yes. The documented release call uses /customer/did_management/ with action=release, the purchased did_id, accountid, id, and token. The supplied API reference confirms the release operation; billing timing should follow the commercial terms of your account.

What forwarding destination types are supported?

The DID Forward Setting endpoint supports always, user_busy, user_not_registered, and no_answer conditions. The supplied API example uses call_type=2 with call_type_value set to a trunk IP. Other destination types should be used only with the corresponding supported call_type values.

In which countries can I provision numbers via API?

Use the optional numeric country_id provided in the Country List reference/example, then pass that value to DID Available List to see currently available numbers for the selected country. Availability varies by country and number inventory. The current API reference marks the Country List call as disabled and provides the country IDs in its example.

Start Provisioning Numbers Today

Create an account, authenticate through the Login call, and start searching available DIDs by country ID.

Create Account Back to API Hub

    Sales, click to chat