contactGet: Get the details of the contact

Function Description:

Get the details of the contact, get detailed information about multiple contacts at the same time.

Corresponding JS API:
contactGet(postion)
contactGet(begin, end)
Whether to support multiple devices:

No

Resource Information:

Method GET
URL .../devices/:device/contacts?position=:num&count=:count
Requires authentication? Yes


Method Parameters:

Parameter Type Required Description
device String Yes ID value of the device
position Int Yes The contact at the specified location. The minimum value is 1.
count Int No How many contacts to get, without filling in this parameter, get the details of a contact.


Response Parameters:

A JSON string representing an array of objects with the following fields:

Field Type Description
status Boolean Return true for success and null for failure
value Array/String String, If the value of status is a null object, an error message or empty string is returned.
Array, If the value of status is true,it returns the contact's details.
The returned array contains the following fields:The returned array contains the following fields:
  • contactId: Int, The contact ID, which is the unique identifier of the contact.
  • displayName: String, Contact name.
  • phone: Array, Contact number, contains fields phoneNumber and phoneType.
      - phoneNumber: Int, Phone number.
      - phoneType: Int, Type of phone number,
    1: Home Phone
    2: Mobile Phone
    3: Work Phone
    4: Work Fax
    5: Home Fax
    E.g:
    [{'phoneNumber':'028 8888 1111','phoneType':'1'},{'phoneNumber':'028 8888 1111','phoneType':'1'}]
  • email: Array, Email, contains fields emailValue and emailType.
      - emailValue: String, E-mail.
      - emailType: Int, Type of email.
    1: Home email
    2: Work email
    E.g:
    [{'emailType':'1','emailValue':'mobile@huawei.com'}]
  • organization: Array, it contains fields company and title.
      - company: Company name
      - title: Title
    E.g:
    [{'company':'sigma','title':'QA'}]
  • iconBytes: String, Contact image, represented by base64.


Request Example:
http://localhost:8090/TotalControl/v1/devices/device@1174886816/contacts?position=1&count=1&token=46M4JhgylT4Q1vmT
Response Example:

If this API executes successfully, it returns:

{
    "status": true,
    "value": [{
		'contactId': 2592,
		'displayName': 'Amy',
		'email': [{
			'emailType': '1',
			'emailValue': '15882431111@139.com'
		}, {
			'emailType': '2',
			'emailValue': 'amy@139.com'
		}],
		'iconBytes': '',
		'organization': [{
			'company': 'Sigma',
			'title': 'QA'
		}],
		'phone': [{
			'phoneNumber': '158 8243 1111',
			'phoneType': '2'
		}, {
			'phoneNumber': '158 8243 2222',
			'phoneType': '2'
		}, {
			'phoneNumber': '028 8888 6666',
			'phoneType': '1'
		}, {
			'phoneNumber': '028 8888 8888',
			'phoneType': '3'
		}]
	}]	
}

If the value of HTTP status code is 200, but the value of status is a null object, it returns:

{
    "status": null,
    "value": "<Error message>"
}


Example:

Warm tip:
Get the token needed for Total Control script development,see here.
Get the id value of the master device, see here.

RingoJS Example:
// Import the packages
var {request} = require("ringo/httpclient");
var base64 = require("ringo/base64");

// The username and password are separated by a single : and sent on the wire base64 encoded
var userpass = base64.encode("sigma:3D391497");

// First step: Get the API token
var gettoken = request({
	method: "GET",
	url: "http://localhost:8090/TotalControl/v1/login",
	headers: {
		"Authorization": userpass
	}
});
var ret_token = JSON.parse(gettoken.content); 
var token = ret_token.value.token; 
print("//The value of token is:" + token);

// Second step: Get the device id value of the master device
var getdevice = request({
	method: "GET",
	url: "http://localhost:8090/TotalControl/v1/devices/main?token=" + token
});
var device = JSON.parse(getdevice.content).id; 
print("//The value of device ID is:"+ device);

// Third step: Execute this REST API
var resp = request({
	method: "GET",
	url: "http://localhost:8090/TotalControl/v1/devices/" + device + "/contacts",
	data: {
		"count": 2,
		"position": 1,
		"token": token,
	}
});
var obj = JSON.parse(resp.content); 
var ret = obj.status;
if (ret == true) {
	print("//Executed successfully,Return value: \n"+resp.content);	
} else if (ret != true & resp.status == 200){
	print("An error message is returned: "+resp.content);
} else {
	print("This API failed to execute.");
}
The running result of the RingoJS:

If it executes successfully, it will return:

//The value of token is:R6x0t15Wt7aN97Y9
//The value of device ID is:device@33254183
//Executed successfully,Return value: 
{'status': true, 'value': [{'contactId': 2592, 'displayName': 'Amy', 'email': [{'emailType': '1', 'emailValue': '15882431111@139.com'}, {'emailType': '2', 'emailValue': 'amy@139.com'}], 'iconBytes': '', 'organization': [{'company': 'Sigma', 'title': 'QA'}], 'phone': [{'phoneNumber': '158 8243 1111', 'phoneType': '2'}, {'phoneNumber': '158 8243 2222', 'phoneType': '2'}, {'phoneNumber': '028 8888 6666', 'phoneType': '1'}, {'phoneNumber': '028 8888 8888', 'phoneType': '3'}]}, {'contactId': 2590, 'displayName': 'Tom', 'email': [], 'iconBytes': '', 'organization': [], 'phone': [{'phoneNumber': '028 8888 1111', 'phoneType': '1'}, {'phoneNumber': '028 8888 1111', 'phoneType': '1'}]}]}
Python Example:
#!/user/bin/python
#-*- coding:utf-8 -*-
import base64
import requests

# The username and password are separated by a single : and sent on the wire base64 encoded
user_pass = 'sigma:3D391497'
encodeStr = base64.b64encode(user_pass.encode("UTF-8"))

# First step: Get the API token
LoginUrl = "http://localhost:8090/TotalControl/v1/login"
response = requests.get(LoginUrl, headers={'Authorization':encodeStr})
print("Get the token,Return value: ",response.json())
token = response.json()['value']['token']
print("The value of token is: ",token)

# Second step: Get the device id value of the master device
if token is not None:
    GetDeviceUrl = "http://localhost:8090/TotalControl/v1/devices/main?token=" + token
    response = requests.get(url=GetDeviceUrl)
    print("Get the device id,Return value: ", response.json())
    device = response.json()['id']
    print("The value of device id is: ", device)
    if device is not None:
        # Third step: Execute this REST API
        APIUrl = "http://localhost:8090/TotalControl/v1/devices/" + device + "/contacts"
        data = {
            "count": 2,
            "position": 1,
            "token": token
        }
        response = requests.get(url=APIUrl, params=data)
        ret = response.json()['status']
        # Determine if this REST API is executed successfully
        if ret is True:
            print("Executed successfully,Return value: ", response.json())
        elif response.status_code == 200 and ret is not True:
            print("An error message is returned: ",response.json())
        else:
            print("This API failed to execute.")
    else:
        print("Failed to get device id.")
else:
    print("Failed to get token.")
The running result of the python:

If it executes successfully, it will return:

Get the token,Return value:  {'status': True, 'value': {'token': 'R6x0t15Wt7aN97Y9'}}
The value of token is:  R6x0t15Wt7aN97Y9
Get the device id,Return value:  {'id': 'device@33254183'}
The value of device id is:  device@33254183
Executed successfully,Return value:  {'status': True, 'value': [{'contactId': 2592, 'displayName': 'Amy', 'email': [{'emailType': '1', 'emailValue': '15882431111@139.com'}, {'emailType': '2', 'emailValue': 'amy@139.com'}], 'iconBytes': '', 'organization': [{'company': 'Sigma', 'title': 'QA'}], 'phone': [{'phoneNumber': '158 8243 1111', 'phoneType': '2'}, {'phoneNumber': '158 8243 2222', 'phoneType': '2'}, {'phoneNumber': '028 8888 6666', 'phoneType': '1'}, {'phoneNumber': '028 8888 8888', 'phoneType': '3'}]}, {'contactId': 2590, 'displayName': 'Tom', 'email': [], 'iconBytes': '', 'organization': [], 'phone': [{'phoneNumber': '028 8888 1111', 'phoneType': '1'}, {'phoneNumber': '028 8888 1111', 'phoneType': '1'}]}]}