

Devices

Devices#

Device document structure#

Key	Type	Required	Description
id	string	Yes	The ESN/MEID of the device in hexadecimal format that acts as the device ID in TOP.
name	string	Yes	A name for the device.
model	object	Yes	An object containing information about the device's model. This is set automatically and can not be updated with the APIs below.
model.name	string	Yes	The device's model name.
model.number	string	Yes	The device's model number.
model.manufacturer	string	Yes	The device's manufacturer.
msl	string	Yes	The MSL (Master Subsidy Lock) of that device.
voice	object	Yes	An object containing all the information related to call routing.
voice.sip	object	Yes	An object containing the sip credentials for call routing.
voice.sip.realm	string	Yes	The sip realm of the device used for call routing.
voice.sip.username	string	Yes	The sip username of the device used for call routing.
voice.sip.password	string	Yes	The sip password of the device used for call routing.
voice.sip.uri	string	No	A set URI that the device should always route to. This is a very specific and uncommon usecase.
voice.dns	boolean	No	A boolean determining whether the sip realm should be resolved for routing. This defaults to false and should only be set to true when routing to an external IP or resolvable URI set in voice.sip.realm
voice.cluster_id	string	No	The ID of an existing cluster in the Routing Database. This should only be set if you want to route a device to an established cluster that is different from the cluster this device was activated on (e.g device activated on Kazoo Hosted and routing to Sandbox).
data	object	No	Settings for the device data usage restrictions.
data.throttling	object	No	Settings for throttling the device.
data.throttling.cap	int	Yes	Data cap, in `bytes`, which will trigger device throttling once it's reached.
data.throttlign.rate	string	Yes	Maximum bandwith restriction while device throttling is active. Accepted values are `"64k"`, `"128k"`, `"256k"`, and `"512k"`.
data.blocking	object	No	Settings for blocking the data on the device.
data.blocking.cap	int	Yes	Data cap, in `bytes`, which will block data usage on the device once it's reached.
porting	object	No	[Deprecated] An object containing information related to any current port request for that device. This is now deprecated and has been moved to the Subscription document
porting.id	string	No	The port ID of a currently ongoing port request for that device.

API Index#

Change the product owner of a Device (POC Swap)
List Devices
Get a Device
Patch a Device
Force a device PRL refresh
Add a Foreign Device

The following APIs are now deprecated. The equivalent Subscriptions API should be used instead.#

Validate a Device
Activate a new Device
Deactivate a Device
List Blocked Devices
List Throttled Devices
Change the Device's subscription
Sync the device doc with the carrier
Suspend a Device
Un-suspend a Device
Replace a device with a new valid device
Move a device to a different account

APIs#

Change the product owner of a Device (POC Swap)#

Required Authentication Level: basic

POST http://{SERVER}:{PORT}/v2/devices/{ESN}/ownership

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/devices/{ESN}/ownership \
    -d '{ "data": {} }'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {},
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Optional parameters:#

Key	Value	Description
carrier	"sprint"	Choose which carrier to validate against. Depending on your MVNO, this may be ignored. When sent, this parameter must be in the envelope (outside of the `data` object).
owner	"mvno", "carrier"	Choose which system should own the device. Will default to "mvno".

List Devices#

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{DEVICE_ID}",
            "mdn": "+15550001111",
            "name": "Joe's Mobile Phone",
            "carrier": "sprint",
            "data": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        }
    ],
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Get a Device#

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Patch a Device#

Required Authentication Level: basic

PATCH http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

curl -v -X PATCH \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID} \
    -d '{ \
        "data": { \
            "name": "Bob's Mobile Phone", \
            "data": { \
                "blocking": { \
                    "cap": 2000000000 \
                }, \
                "throttling": { \
                    "cap": 1800000000, \
                    "rate": "256k" \
                } \
            }, \
            "voice": { \
                "sip": { \
                    "realm": "sip.mycompany.com", \
                    "username": "another_softphone", \
                    "password": "abcdef123456" \
                }  \
            } \
        }, \
        "recursive": true \
    }'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Bob's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "blocking": {
                "cap": 2000000000
            },
            "throttling": {
                "cap": 1800000000,
                "rate": "256k"
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "another_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Note: Only the name, data and voice fields can be patched. As with all PATCH requests, the recursive flag can be sent in the payload envelope to perform a recursive PATCH. This flag will be set to false by default if not specified.

Force a device PRL refresh#

Required Authentication Level: basic

POST http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/refresh

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/refresh \
    -d '{ "data": {}}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Add a Foreign Device#

Required Authentication Level: reseller

This API allows you to add a device that is not currently recognized/supported by the Carrier into their database. If successful, this will the allow you to activate that device as if it were natively supported.

PUT http://{SERVER}:{PORT}/v2/devices/foreign

curl -v -X PUT \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/devices/foreign \
    -d '{ \
        "data": { \
            "esn": {ESN}, \
            "carrier_data": { \
                "sku_type": "NEW" \
            } \
        }, \
        "carrier": "sprint" \
    }'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {},
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Note: This API currently only works with the Carrier sprint. The carrier specific properties carrier_data.brand_code and carrier_data.sku_type may be specified. If none is, carrier_data.brand_code will be defaulted to "PLD". Below are the possible values for either properties.

Carrier-specific properties in data.carrier_data
Carrier	Property	Authorized Values	Description
Sprint	brand_code	"ASW" "BST" "SPP" "VMU" "SPR" "PLD"	Assurance Wireless Boost Sprint Prepaid Virgin Mobile US Sprint Retail Postpaid Wholesale
Sprint	sku_type	"INTL" "BYO" "NEW"	International Bring Your Own New device to Sprint
Sprint	part_number	String (20 chars max)	Part number associated with the manufacturer and Sprint SKU.

The following APIs are now deprecated:#

Validate a Device#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/devices/{ESN}/validity

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/devices/{ESN}/validity
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "esn": "{ESN_HEX}",
        "model" {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
        },
        "valid": false,
        "reason": "fed_not_met",
        "message": "FED not met",
        "sim_required": false,
        "ownership_change_required": false
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Optional query string parameters:#

Key	Value	Description
carrier	sprint	Choose which carrier to validate against. Depending on your MVNO, this may be ignored.

Possible values for reason/message:#

reason	message
valid	This device is valid and ready for activation.
invalid	This device is not valid and can not be activated.
lost_or_stolen	This device was reported lost or stolen.
in_use	This device is currently in use.
fraud	Fraudulent activity was reported for this device.
not_in_db	This device was not found it the allowed devices database.
not_owned	This device is not currently owned by the MVNO. A change of ownership is required for activation.
prepaid	This is a prepaid device.
not_financially_eligible	The Financial Eligibility Date has not been met yet.

Activate a new Device#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

PUT http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices

curl -v -X PUT \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices \
    -d '{ "data": { \
        "esn": "{ESN}", \
        "name": "Joe's Mobile Phone", \
        "postal_code": "94108",
        "voice": { \
            "sip": { \
                "realm": "sip.mycompany.com", \
                "username": "my_softphone", \
                "password": "abcdef123456" \
            } \
        } \
    }}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
        },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Optional parameters:#

Key	Value	Description
carrier	"sprint"	Choose which carrier to activate on. Depending on your MVNO, this may be ignored. When sent, this parameter must be in the envelope (outside of the `data` object).
sim	{SIM_ID}	The phone's SIM card ID. Only needed when the validation returns "sim_required":false
data	{OBJECT}	Set the data policies on the device. If not specified, will used the account default or will default to no cap. See usage policies doc for more information.
carrier.plan	"260PLAN21"	Choose a carrier plan. If not specified, your MVNO's default plan for this carrier will be used. Depending on your MVNO, this may be ignored.
carrier.features	["mms", "lte", "sip", "international"]	Choose the features to enable on this device. Depending on your MVNO, this may be ignored.

Deactivate a Device#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

DELETE http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

curl -v -X DELETE \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID} \
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

List Blocked Devices#

DEPRECATED: Please use this API instead.

This API list all the devices within the specified account that had their data usage blocked.

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/blocked

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/blocked
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{DEVICE_ID}",
            "mdn": "+15550001111",
            "source": "automatic",
            "reason": "device_cap_reached",
            "account_id": "{ACCOUNT_ID}",
            "created": 63660618801
        }
    ],
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

The source field may be set to "automatic" if the block was done automatically by TOP, or "manual" if it was done by a user (via API). The reason field describes why the block was done, and the possible values are "device_cap_reached", "account_cap_reached", and "credit_declined" when the srouce is automatic. If the source is manual, the reason may be set to any string describing why the device is being blocked.

List Throttled Devices#

DEPRECATED: Please use this API instead.

This API list all the devices within the specified account that had their data usage throttled.

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/throttled

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/throttled
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{DEVICE_ID}",
            "mdn": "+15550001111"
            "rate": "256k",
            "source": "automatic",
            "reason": "device_cap_reached",
            "account_id": "{ACCOUNT_ID}",
            "created": 63660619640
        }
    ],
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

The source field may be set to "automatic" if the throttling was done automatically by TOP, or "manual" if it was done by a user (via API). The reason field describes why the throttling was done, and the possible values are "device_cap_reached", "account_cap_reached", and "credit_declined" when the srouce is automatic. If the source is manual, the reason may be set to any string describing why the device is being throttled.

Change the Device's subscription#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

POST http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/subscription

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/subscription \
    -d '{ "data": { \
        "plan": "{NEW_PLAN_ID}", \
        "features": { \
            "add": ["tether"], \
            "remove": ["international"] \
        } \
    }}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "{NEW_PLAN_ID}",
            "features": ["sip", "mms", "lte", "tethering"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Note: only one of the following parameters is required: plan, features.add, features.remove. If features.add and features.remove are both provided and share a common feature, that feature will be removed.

Sync the device doc with the carrier#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

POST http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID} \
    -d '{ "data": {}}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Suspend a Device#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

PUT http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/suspension

curl -v -X PUT \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/suspension \
    -d '{ "data": {}}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },,
            "activation_date": 63648957842
            "suspended": true
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Un-suspend a Device#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

DELETE http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/suspension

curl -v -X DELETE \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/suspension \
    -d '{ "data": {}}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Replace a device with a new valid device#

DEPRECATED: Please use this API instead.

Required Authentication Level: basic

POST http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/replace

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/replace \
    -d '{ "data": { \
        "esn": {NEW_DEVICE_ESN}, \
        "sim": {NEW_DEVICE_SIM_ID} \
    }}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{NEW_DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "{NEW_DEVICE_SIM_ID}",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Move a device to a different account#

DEPRECATED: Please use this API instead.

Required Authentication Level: reseller

POST http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/move

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}/move \
    -d '{ "data": { \
        "target_account_id": {TARGET_ACCOUNT_ID} \
    }}'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{DEVICE_ID}",
        "name": "Joe's Mobile Phone",
        "model": {
            "name": "SAMSUNG L300 HANDSET KIT",
            "number": "SPHL300KTS",
            "manufacturer": "SAMSUNG"
            },
        "subscription": {
            "esn": "{ESN}",
            "mdn": "+15550001111",
            "sim": "01234567890123456789",
            "imsi": "9876543210",
            "plan": "260PLAN21",
            "features": ["international", "sip", "mms", "lte"],
            "carrier_data": {
                "msid": "{MSID}",
                "csa": "SFRSFR415"
            },
            "activation_date": 63648957842
        },
        "data": {
            "caps": {
                "blocking": {
                    "cap": 0
                },
                "throttling": {
                    "cap": 0,
                    "rate": "256k"
                }
            }
        },
        "voice": {
            "sip": { 
                "realm": "sip.mycompany.com", 
                "username": "my_softphone", 
                "password": "abcdef123456" 
            } 
        }
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

KAZOO Support Channels

Devices

Devices#

Device document structure#

API Index#

The following APIs are now deprecated. The equivalent Subscriptions API should be used instead.#

APIs#

Change the product owner of a Device (POC Swap)#

Optional parameters:#

List Devices#

Get a Device#

Patch a Device#

Force a device PRL refresh#

Add a Foreign Device#

The following APIs are now deprecated:#

Validate a Device#

Optional query string parameters:#

Possible values for reason/message:#

Activate a new Device#

Optional parameters:#

Deactivate a Device#

List Blocked Devices#

List Throttled Devices#

Change the Device's subscription#

Sync the device doc with the carrier#

Suspend a Device#

Un-suspend a Device#

Replace a device with a new valid device#

Move a device to a different account#