User | IPCortex API

API Version: 6.4

Permissions

Requires System-Admin or Company-Admin permissions.

Note regarding role ID

When creating, updating or querying a user, the roleid field may be specified as either the internal ID number, or the short lower-case string name of the role.

If the roleid field is included in the output of a user query, then an additional field of rolename is output to represent the short lower-case string name of the role.

command 'create'

Path: /rest/ops/create/

Create a new user on the system. 'uname' and 'name' are minimum required parameters.

{
	"type": "user",
	"values": {
		"uname": "unique-login-name",
		"name": "Real Name",
		"password": "initial password or null for none",
		"pwhash": "initial blowfish hashed password or null for none (from version 6.3.23)",
		"company": "Company-ID or null for default",
		"owned_extension": "extension number",
		"owned_phoneid": "mac and port ID number",
		"can_hotdesk": bool or null for default,
		"can_forward": bool or null for default,
		"xmpp_flags_add": bool or null for default,
		"xmpp_flags_auth": bool or null for default,
		"can_webrtc": (-1 | 0 | 1),
		"email": "email address",
		"email_vm": bool to send email for voicemail,
		"email_vm_att": bool to attach message to email,
		"email_vm_del": bool to delete on emailing,
		"email_mon": bool to email call recordings,
		"email_mon_del": bool to delete on emailing,
		"vmail_mon": bool to store call recordings as voicemail,
		"call_by_all": bool to set user as linkable in other companies,
		"vacation": "number",
		"vacation_mode": "(off | all | myext | owned)",
		"admin_company: ["company-id", ...],
		"roleid": role-id or null for user-role
	}
}

Return value:

{
    "result": "success",
    "values": {
        "contact_id": new_contact_id,
        "uname": "unique-login-name"
    }
}

For example:

{
    "type": "user",
    "values": {
        "uname": "newuser",
        "name": "Mr New User",
        "password": "Secur3passwordhere!",
    }
}

{
    "result": "success",
    "values": {
        "contact_id": 1992,
        "uname": "newuser"
    }
}

command 'read'

Path: /rest/ops/read/

Query on any columns by specifying a 'scope' object. Columns may be selected using an Array of column names, or blank for all.

{
    "type": "user",
    "scope": {
        "contact_id": "contact-id",
        "uname": "unique-login-name",
        ...
        "column-name": "column value"
    },
    "columns": ["column-name", ...]
}

{
    "type": "user",
    "scope": {
        "company":"test"
    },
    "columns": ["uname","owned_phoneid"]}
}

The return value is of the form:

{
    "result": "success",
    "values": [
        {
            "column": "column-value",
            ...
        },
        ...
    ],
    "numrows": number-of-rows
}

command 'update'

Path: /rest/ops/update/

Update a contact based on contact ID. It is possible to modify all columns from the 'create' operation except company which is fixed. null columns are left unchanged.

If logged in as the user to be edited, and if no other permissions are available then the user may modify the following fields on their own record: 'name', 'email', 'email_vm', 'email_vm_att', 'email_vm_del', 'email_mon', 'email_mon_del', 'vmail_mon' if other fields are provided they will be silently ignored.

{
    "type": "user",
    "scope": {
        "contact_id": "contact-id",
    },
    "values": {
        "uname": "unique-login-name",
        "password": "password",
        "pwhash": "blowfish hashed password (from version 6.3.23)",
        ...
        "column-name": "column value"
    }
}

{
    "type": "user",
    "scope": {
        "contact_id":123
    },
    "values": {
        "name":"My New Name"
    }
}

The return value is of the form:

{
    "result": "success",
    "numrows": number-of-rows
}

command 'delete'

Path: /rest/ops/delete/

Using either contact_id or uname of a user, delete all records for the contact

{
    "type": "user",
    "scope": {
        "contact_id": "contact-id",
        "uname": "unique-login-name" /* if contact_id not provided */
    }
}

{
    "type": "user",
    "scope": {
        "uname": "newuser"
    }
}

command 'setpass'

This command has additional permissions that the user may use it on their own contact.

Path: /rest/ops/setpass/

Using either contact_id or uname of a user, update their password.

{
    "type": "user",
    "scope": {
        "contact_id": "contact-id",
        "uname": "unique-login-name" /* if contact_id not provided */
    },
    "values": {
        "password": "new-password"
    }
}

{
    "type": "user",
    "scope": {
        "uname": "newuser"
    },
    "values": {
        "password": "NewSecurepassw0rdhere!"
    }
}