API Version: Development

Company

Permissions

Requires System-Admin permissions for create, delete or container operations, but company read and update may be used by company administrators (scope must specify a company).

command 'create'

Path: /rest/ops/create/
Create a new company, container and administrative community.
{
    "type": "company",
    "values": {
        "company": "company-id",
        "name": "company name",
        "description": "company description"
    }
}
Return value is a copy of the newly created company:
{
    "result": "success",
    "values": {
        "company id": {
            "id": 1234,    /* Company unique ID */
            "name": "Company Name",
            "data": {}
        }
    }
}
For example:
{
    "type": "company",
    "values": {
        "company": "testcompany",
        "name": "My Test Company"
    }
}
{
    "result": "success",
    "values": {
        "testcompany": {
            "id": 1235,
            "name": "My Test Company",
            "data": {}
        },
        ...
    }
}

command 'read'

Path: /rest/ops/read/
Read a list of companies and their details from the system. May optionally be filtered by company id (the company uname).
{    
    "type": "company",
    "scope": {
        "company": "company-id"
    }
}
Return value:
{
    "result": "success",
    "values": {
        "company id": {
            "id": 1234,    /* Company unique ID */
            "name": "Company Name",
            "data": {
                "record": 15,
                "nm_password": "0000",
                "ivr_password": "0000",
                "zone": "US/Pacific",
                "hs_nm": "",
                "hs_access": "",
                "hs_access_nm": "",
                "hs_webrtc": "",
                "fid": "",
                "phonebook": "",
                "crm_url": "",
                "vm_silent": "",
                "barge_pin": "",
                "callerid": "",
                "vm_callback": 0
            }
        }
    }
}
For example:
{
    "type": "company",
    "scope": {
        "company": "testcompany"
    }
}
{
    "result": "success",
    "values": {
        "testcompany": {
            "id": 1234,
            "name": "A Test Company",
            "data": {
                "record": 15,
                "nm_password": "0000",
                "ivr_password": "0000",
                "zone": "US/Pacific",
                "hs_nm": "",
                "hs_access": "",
                "hs_access_nm": "",
                "hs_webrtc": "",
                "fid": "",
                "phonebook": "",
                "crm_url": "",
                "vm_silent": "",
                "barge_pin": "",
                "callerid": "",
                "vm_callback": 0
            }
        },
        ...
    }
}

command 'update'

Path: /rest/ops/update/
Update an existing company's name / attributes. Many attributes can be modified by a company administrator. A null parameter will be left untouched. An empty parameter returns it to the default of using a system default.
{
    "type": "company",
    "scope": {
        "company": "company-id"
    },
    "values": {
        "name": "company name",
        "description": "company description",
        "nm_password": "numeric nightmode pin",
        "ivr_password": "numeric ivr pin",
        "barge_pin": "numeric barge pin",
        "zone": "timezone string",
        "hs_nm": "Handset nightmode ('' or 0-9)",
        "hs_access": "Default handset access level",
        "hs_access_nm": "Nightmode handset access level",
        "fid": "Block handset forwards ('' = system default, 0 = no, 1 = yes)",
        "vm_callback": "Enable call-return from voicemail (-1 = no, 0 = system default, 1 = yes)",
        "phonebook": "Default phonebook visibility (0 = none, 1 = company, 2 = logged-in, 3 = public)",
        "callerid": "Override caller-id default value (prefix with '-' for cid blocking)",
        "vm_silent": "Silence voicemail instructins ('' = default, 'no' = say instructions, 'yes' = silence)",
        "vm_maxmsgs": "Max voicemail messages per mailbox ('' = Global Default, 50, 100, 200, 300, 500))",
        "q_ringtime": "Queue ring time ('' or 5 to 30)",
        "q_pausetime": "Queue pause time ('' or 2 to 10)",
        "q_wraptime": "Queue wrapup time ('' or 2 to 240)",
        "q_per_ann_int": "Periodic announce interval seconds ('', 30, 60, 90)",
        "q_per_pos_int": "Periodic position interval seconds ('', 30, 60, 90)",
        "pre_queue_ring": "Pre-queue ring time ('' or 1 to 999)",
        "crm_url": "(Deprecated) CRM popup URL",
        "hs_webrtc": "Default keevio phone status ('' = Global default, no = None, yes = keevio phone, phone = keevio mobile, both = Both)"
    }
}
Return value is a copy of the updated company:
{
    "result": "success",
    "values": {
        "company id": {
            "id": 1234,    /* Company unique ID */
            "name": "Company Name",
            "data": {
                "nm_password": "",
                "ivr_password": "",
                "zone": "",
                "hs_nm": "",
                "hs_access": "",
                "hs_access_nm": "",
                "fid": "",
                "vm_callback": 0,
                "phonebook": "",
                "callerid": "",
                "vm_silent": "",
                "vm_maxmsgs": "",
                "q_ringtime": "",
                "q_pausetime": "",
                "q_wraptime": "",
                "q_per_ann_int": "",
                "q_per_pos_int": "",
                "pre_queue_ring": "",
                "barge_pin": "",
                "crm_url": "",
                "hs_webrtc": ""
            }
        }
    }
}
For example:
{
    "type": "company",
    "scope": {
        "company": "testcompany"
    },
    "values": {
        "name": "My Test Company"
    }
}
{
    "result": "success",
    "values": {
        "testcompany": {
            "id": 1235,
            "name": "My Test Company",
            "data": {
                "nm_password": "1234",
                "ivr_password": "1234",
                "zone": "",
                "hs_nm": "",
                "hs_access": "external",
                "hs_access_nm": "",
                "fid": "1",
                "vm_callback": 0,
                "phonebook": "",
                "callerid": "",
                "vm_silent": "",
                "vm_maxmsgs": "",
                "q_ringtime": "",
                "q_pausetime": "",
                "q_wraptime": "",
                "q_per_ann_int": "",
                "q_per_pos_int": "",
                "pre_queue_ring": "",
                "barge_pin": "",
                "crm_url": "",
                "hs_webrtc": ""
            }
        },
        ...
    }
}

command 'readContainer'

Path: /rest/ops/readContainer/
Read a list of containers of companies and their details from the system. May optionally be filtered by company id (the company uname) and/or container id.
{    
    "type": "company",
    "scope": {
        "company": "company-id",
        "container": "container-id"
    }
}
Return value:
{
    "result": "success",
    "values": {
        "container id": {
            "id": 999,    /* Container unique ID */
            "name": "Container Name",
            "data": {},    /* Containers currently have no data */
            "members: {
                "company id": {
                    "id": 1234,    /* Company unique ID */
                    "name": "Company Name",
                    "data": {
                        "record": 15,
                        "nm_password": "0000",
                        "ivr_password": "0000",
                        "zone": "US/Pacific",
                        "hs_nm": "",
                        "hs_access": "",
                        "hs_access_nm": "",
                        "hs_webrtc": "",
                        "fid": "",
                        "phonebook": "",
                        "crm_url": "",
                        "vm_silent": "",
                        "barge_pin": "",
                        "callerid": "",
                        "vm_callback": 0
                    }
                },
                ...
            }
        }
    }
}
For example:
{
    "type": "company",
    "scope": {
        "company": "testcompany"
    }
}
{
    "result": "success",
    "values": {
        "test": {
            "id": 2345,
            "name": "Test Container",
            "data": {},
            "members": {
                "testcompany": {
                    "id": 4567,
                    "name": "Test Co",
                    "data": {
                        "nm_password": "0000",
                        "ivr_password": "0000",
                        "zone": "",
                        "hs_nm": "",
                        "hs_access": "",
                        "hs_access_nm": "",
                        "hs_webrtc": "",
                        "fid": "",
                        "phonebook": "",
                        "crm_url": "",
                        "vm_silent": "",
                        "barge_pin": "",
                        "callerid": "123456",
                        "record": 15,
                        "vm_callback": 0,
                        "vm_maxmsgs": "300"
                    }
                }
            }
        }
    }
}

command 'group'

Path: /rest/ops/group/
Group one company in a container with another.
{       
        "type": "company",
        "scope": {
                "company": "company-id"        /* Company to 'move' */
        },
        "values": {
                "company": "company-id"        /* Target company */
        }
}
Return value:
{
    "result": "success",
    "message": "grouped okay",
    "containermoves": 0        /* How many other companies were relocated as a side effect - ignore */
}

command 'ungroup'

Path: /rest/ops/ungroup/
Ensure a company is no-longer in a group.
{
        "type": "company",
        "scope": {
                "company": "company-id"         /* Company to 'ungroup' */
        }
}
Return value:
{
        "result": "success",
        "message": "un-grouped okay",
        "containermoves": 0             /* How many other companies were relocated as a side effect - ignore */
}