End user Operations

End user Operations

This section describes the APIs available to end users or when logged in as an end user. This section has two main sections. The Devices section documents the APIs to deal with devices and their attributes, the Customer section documents the APIs to obtain and change end user information. See also the End user Rules section

Devices

addDeviceToUser

Adds a device to a Customer Account.

Usage

You can only monitor and control a device once the device has been added to a Customer Account. After the device is added to the account, this is the only account that can monitor and control the device. Known issue: when calling addDeviceToUser the Device Name is ignored. If a valid Device ID is provided and that device is not claimed by any user, then the user will be able to claim that device which maps to that Device ID, regardless of whether the Device Name is correct. For example, suppose you have a device with Device ID 101 and Device Name ABC12345678. If you calladdDeviceToUser, provide 101 for deviceId, and provide XYZ123 for deviceName, the request will complete successfully and you will now own the device that maps to Device ID 101.

Preconditions

The Device Code has been authenticated by calling deviceAuth. The deviceAuth response will contain an element called devId. Use this for the value of the deviceId argument when calling addDeviceToUser.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userId int The User ID of a Customer Account or System Account.
deviceId int The Device ID of the device. CalldeviceAuth to retrieve the Device ID.
deviceName string The Device Name of the device.
typeName string The Device Type name.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
HTTP

Note that the type parameter must match the name of the Device Type of your particular device, as it has been defined in the Configurator.

https://example.arrayent.com:8081/zdk/services/zamapi/addDeviceToUser?
secToken=000-123456789&userId=819&deviceId=42&deviceName=foo&typeName=bar
<ns1:addDeviceToUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:addDeviceToUserResponse>
Python

deviceAuth

Authenticates a Device Code.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
name string The Device Name.
password string The Device Password.

The diagram below explains the relationship between the terms Device Code, Device Password, and Device Name.

Response
Element Name Data Type Description
devId int The Device ID of the device.
Examples
HTTP

The name parameter corresponds to the Device Name of the device. The password parameter corresponds to the Device Password of the device.

https://example.arrayent.com:8081/zdk/services/zamapi/deviceAuth?secToken=
28954789257fg897245687ab987frt&name=1234569150234&password=25KBA
<ns1:deviceAuthResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <devId>19212</devId>
</ns1:deviceAuthResponse>
Python

getDeviceAttribute

Retrieves the current value for a single attribute of a single device.

Usage

This operation is documented for legacy purposes. For retrieving device attrbute values see getDeviceValueList.

Warning

If you need to retrieve the values of two or more attributes then you should use getDeviceValueList, rather than callinggetDeviceAttribute once for each attribute. The batch operation is significantly more efficient.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
devId int The Device ID of the device.
name string The name of the Device Attribute.
Response
Element Name Data Type Description
value string The current value of the attribute.
updTime int A timestamp indicating when the value was updated.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceAttribute?
secToken=000-12345678&devId=12345&name=foo
<ns1:getDeviceAttributeResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <value>30</value>
 <updTime>1829402054</updTime>
</ns1:getDeviceAttributeResponse>

getDeviceAttributesWithValues

Retrieves the list of device attribute definitions for a single device, in addition to the current value of each device attribute. This includes any global attributes that have been defined for the specified device data model.

Parameters
Parameter Name Data Type Description
secToken string The security token.
deviceTypeId int The Device Type ID.
devId int The Device ID.
Response
Parameter Name Data Type Description
typeId int The Device Type ID. Same asdeviceTypeId from your request.
typeName string The Device Type name.
configurations configuration Miscellaneous device configurations. See below.
presenceInfo boolean The current connection status of the device.
attrList DeviceAttr A list of DeviceAttr elements. See below.

configuration

Parameter Name Data Type Description
property string The name of the configuration property.
value string The value of the configuration property.

attrList

Parameter Name Data Type Description
id int The Device Attribute ID.
name string The Device Attribute name.
displayName string The Device Attribute display name, A.K.A. friendly name.
device boolean Indicates whether attribute updates are sent down to the device.
presistent boolean Old feature that is no longer supported.
ts boolean Time series.
global boolean Special type of Device Attribute in which the attribute value is the same for all devices of this type.
tsValueType int The data type of the attribute.
hardwareIOType string The typical direction in which the attribute is sent, i.e. from device or from web application. In reality all attributes can be sent in either direction. Values: Output,Input. Output means the attribute is typically sent from web application to cloud. Input means the attribute is typically sent from device to cloud.
enumeratedAlias int An integer alias for the attribute name. Required if using multi-attribute messages in your device.
value string The current value of the attribute.
updTime long A timestamp representing when the attribute value was last updated. Format is UNIX time, in milliseconds.
Examples
HTTP
https://DevKit-api.arrayent.com:8081/zdk/services/zamapi/
getDeviceAttributesWithValues?deviceTypeId=1016&
devId=19300&secToken=912-1769025809
Python

getDeviceAttributesWithValuesUpdatesSince

Retrieves the list of device attributes for a single device. The operation only returns device attributes whose values have been updated after the specified timestamp in your request. This operation does not return global attributes whose values have been updated after the specified timestamp.

Usage

Make sure your timestamp is UNIX Epoch format, in milliseconds, GMT timezone. You can set timestamp to 0 to retrieve all attributes. This is functionally equivalent to calling getDeviceAttributesWithValues. The benefit of this would be only needing to maintain and implement one web service operation, rather than two. The reason that this web service operation does not return global attributes whose values have been updated on or after the specified timestamp is because the Arrayent Cloud does not track the update timestamps of global attributes. If you callgetDeviceAttributesWithValues and look at the updTime timestamp of your global attributes, they will always be set to 0.

Parameters
Parameter Name Data Type Description
secToken string The security token.
deviceTypeId int The Device Type ID.
devId int The Device ID.
timestamp long The timestamp indicating which values to retrieve. All attributes whose values were updated after this timestamp will be returned. The timestamp must be in UNIX Epoch format, in the GMT timezone, and in milliseconds.
Response
Parameter Name Data Type Description
typeId int The Device Type ID. Same asdeviceTypeId from your request.
typeName string The Device Type name.
attrList DeviceAttr A list of DeviceAttr elements. See below.

attrList

Parameter Name Data Type Description
id int The Device Attribute ID.
name string The Device Attribute name.
displayName string The Device Attribute display name, A.K.A. friendly name.
device boolean Indicates whether attribute updates are sent down to the device.
presistent boolean Old feature that is no longer supported.
ts boolean Time series.
global boolean Special type of Device Attribute in which the attribute value is the same for all devices of this type.
tsValueType int The data type of the attribute.
hardwareIOType string The typical direction in which the attribute is sent, i.e. from device or from web application. In reality all attributes can be sent in either direction. Values: Output,Input. Output means the attribute is typically sent from web application to cloud. Input means the attribute is typically sent from device to cloud.
enumeratedAlias int An integer alias for the attribute name. Required if using multi-attribute messages in your device.
value string The current value of the attribute.
updTime long A timestamp representing when the attribute value was last updated. Format is UNIX time, in milliseconds.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/ getDeviceAttributesWithValuesUpdatesSince?secToken=11817-1497471072&
devId=184554197&deviceTypeId=1515&timestamp=1427140819395

getDeviceAttrList

Retrieves the list of device attribute definitions for a single device data model. This includes any global attributes that have been defined for the specified device data model.

Usage

The key difference between getDeviceAttrList and getDeviceAttributesWithValues is that getDeviceAttrList only returns the device attribute definitions and does not require access to a device, whereas getDeviceAttributesWithValues returns both the device attribute definitions and the current values of each attribute for a single device, and therefore requires access to a device.

Parameters
Parameter Name Data Type Description
secToken string A valid security token.
typeName string The Device Type name.
Response
Parameter Name Data Type Description
typeId int The Device Type ID.
typeName string The Device Type name.
attrList DeviceAttr A list of DeviceAttr elements. See below.

attrList

Parameter Name Data Type Description
id int The Device Attribute ID.
name string The Device Attribute name.
displayName string The Device Attribute display name, A.K.A. friendly name.
device boolean Indicates whether attribute updates are sent down to the device.
presistent boolean Old feature that is no longer supported.
ts boolean Time series.
global boolean Special type of Device Attribute in which the attribute value is the same for all devices of this type.
tsValueType int The data type of the attribute.
hardwareIOType string The typical direction in which the attribute is sent, i.e. from device or from web application. In reality all attributes can be sent in either direction. Values: Output,Input. Output means the attribute is typically sent from web application to cloud. Input means the attribute is typically sent from device to cloud.
enumeratedAlias int An integer alias for the attribute name. Required if using multi-attribute messages in your device.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceAttrList?
secToken=912-177582234&typeName=globalattributes

getDeviceList

Retrieves the list of devices currently owned by a user.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userId int The User ID of a Customer Account or System Account.
Response
Element Name Data Type Description
devList DeviceInfo Zero or more DeviceInfo elements.

Each DeviceInfo element contains the following elements:

Element Name Data Type Description
devId int The Device ID of the device.
devName string The Device Name of the device.
typeId int The Device Type ID.
sleepMode string The Sleep Mode of the device. This is an internal configuration parameter used by Arrayent.
appID int The Application ID of the user account.
userID int The User ID of a Customer Account or System Account.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceList?
secToken=000-123456789&userId=42
Python

getDevicePresenceInfo

Retrieves the current network connection status of a device.

Preconditions

The device must be owned by a user account.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
devId int The Device ID of the device.
Response
Element Name Data Type Description
state int The connection state of the device. A value of 0 means the device is not currently connected to the Arrayent Cloud. A value of 1 means the device is currently connected.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/getDevicePresenceInfo?
secToken=123-123456789&devId=1234
<ns1:getDevicePresenceInfoResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <state>0</state>
</ns1:getDevicePresenceInfoResponse>

getDeviceTS2

Retrieves historical data for a single attribute.

Usage

The range of values returned is determined by the values of the parameters start and end. All values that were recorded between these two parameters will be retrieved. However, there is a limit to the number of return values that is configurable per tenant. It is set to 500 by default, but it may be changed if you contact your Arrayent account team or support.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
devId int The Device ID of the device.
propName string The name of the attribute.
start long A timestamp indicating the beginning of the range of values to retrieve. The timestamp must in UNIX Time format.
end long A timestamp indicating the end of the range of values to retrieve. The timestamp must in UNIX Time format.
Response
Element Name Data Type Description
devId int The Device ID of the device.
propName string The name of the attribute.
tsData tsData Zero or more tsData elements.

Each tsData element contains the following elements:

Element Name Data Type Description
time long The timestamp indicating when the value was recorded. The timestamp is in UNIX Time format.
strValue string The string value of the attribute that was recorded at the moment indicated bytime.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceTS2?secToken=
909839405890adf9829384&devId=225468567&propName=temp&start=1244673079000&
end=1247265079000

getDeviceTypeByID

Given a Device Type ID, returns the name, display name, and App ID (A.K.A. System Account ID) for that ID.

Parameters
Parameter Name Data Type Description
secToken string A valid security token.
deviceTypeID int The Device Type ID.
Response
Element Name Data Type Description
id int The Device Type ID. Same asdeviceTypeID from your request.
name string The name of the Device Type.
displayName string The display name of the Device Type.
appID int The App ID (A.K.A. System Account ID) under which the Device Type exists.
Examples
HTTP
https://DevKit-api.arrayent.com:8081/zdk/services/zamapi/getDeviceTypeByID?
secToken=8804-818809396&deviceTypeID=1515
<ns1:getDeviceTypeByIDResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <id>1515</id>
 <name>Test</name>
 <displayName>Test</displayName>
 <appID>2165</appID>
</ns1:getDeviceTypeByIDResponse>

getDeviceTypeList

Retrieves the list of currently defined Device Types.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
Response
Element Name Data Type Description
typeNameList AttrName Zero or more typeNameList elements.

Each typeNameList element will contain the following elements. Note that the generic name for this complex element is AttrName, but in this operation each element is listed as “typeNameList”.

Element Name Data Type Description
id int The ID of the Device Type.
name string The name of the Device Type.
displayName string A human-readable description of the Device Type.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceTypeList?
secToken=2935849adf8g9081q308dhjagfh203h

getDeviceValueList

Retrieves the current values for all attributes of a single device.

Usage

Note that when you use web service operations like getDeviceValueList to view information about a device, you are actually retrieving the Arrayent Cloud’s database record for the device. When the Arrayent Cloud receives a getDeviceValueList request from an app, the cloud just reads its database and forwards the values recorded in the database to the app. The Arrayent Cloud is not connecting to the device and forcing it to send its information to the cloud on demand, as that would be extremely expensive.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
deviceId int The Device ID of the device.
type int The type of attributes that will be returned. A value of 0 instructs the Arrayent Cloud to return Non-Hardware Attributes and Hardware Attributes. A value of 1 returns Non-Hardware Attributes only. A value of2 instructs the cloud to return Hardware Attributes only.
Response
Element Name Data Type Description
deviceId int The Device ID of the device.
presenceInfo int A boolean value indicating the current connectivity status of the device. 0 means offline. 1 means online.
valist AttrValue A list of zero or more AttrValueelements.

Each AttrValue element contains the following elements:

Element Name Data Type Description
deviceId int The Device ID of the device.
name string The name of the attribute.
value string The value of the attribute.
updTime long The time the current value was recorded in the Arrayent Cloud.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceValueList?
secToken=000-123456789&deviceId=42&type=0

removeDeviceFromUser

Disassociates a device from a user account.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
deviceId int The Device ID of the device.
userId int The User ID of a Customer Account or System Account.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/removeDeviceFromUser?
secToken=000-123456789&userId=543&deviceId=42
<ns1:removeDeviceFromUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:removeDeviceFromUserResponse>

setDeviceAttribute

Sets the value of a Device Attribute.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
devId int The Device ID of the device.
name string The name of the attribute.
value string The value of the attribute.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
updTime int A timestamp indicating when the latest value for the attribute was recorded in the Arrayent Cloud.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/setDeviceAttribute?
secToken=9238498a0dsf92348098gg3&devId=4234562&name=led1&value=0
<ns1:setDeviceAttributeResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
 <updTime>1370583931</updTime>
</ns1:setDeviceAttributeResponse>

setMultiAttributeBy

Sets multiple device attributes.

Preconditions
  • If you are referencing Device Attributes by enumerated aliases, then the enumerated aliases must be defined in the device’s data model.
Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
devId int The Device ID of the device.
by string NAME or ENUM````NAME: in parameterattribute each attribute is referenced by its string name.“ENUM“: in parameterattribute each attribute is referenced by its enumerated alias.
persist Boolean Boolean flag to indicate whether the attribute update should be saved to Cloud.
attribute string A sequence of key-value pairs in the form of key:value where key is the name of an attribute defined in your device data model and value is the new value for that attribute. You can repeat this parameter up to 25 times, meaning you can set 25 different attributes with a single request.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/setMultiAttributeBy?
secToken=5TPx3v24&devId=42&by=NAME&attribute="led1":"1"&attribute=
"led2":"0"&attribute="setpoint":"72"

Assuming that you had defined the 100 to be the enumerated alias of led1, 101 to be the enumerated alias of led2, and 105 to be the enumerated alias of setpoint, then the following request is equivalent to the request above.

https://example.arrayent.com:8081/zdk/services/zamapi/setMultiAttributeBy?
secToken=5TPx3v24&devId=42&by=ENUM&attribute=
"100":"1"&attribute="101":"0"&attribute="105":"72"

A return code of “0” indicates that the multi-attribute message has been successfully sent to the device.

<ns1:setMultiAttributeBy xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:setMultiAttributeBy>

setMultiDeviceAttributes2

Sets the values of up to 15 Device Attributes with a single call.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
devId int The Device ID of the device.
name1 string The name of the attribute.
value1 string The value of the attribute.

Repeat the pattern up to 15 times. E.g. name2 and value2, all the way up to name15 and value15.

Response
Element Name Data Type Description
retCode int

User Accounts

deleteUser

Deletes a Customer Account.

Parameters
Parameter Name Data Type Description
sysSecToken string A system security token.
userId int The User ID of the Customer Account to delete.
Response
Element Name Data Type Description
retCode int 0 means success. All other values should be treated as failure.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/deleteUser?
sysSecToken=000-123456789&userId=1234
<ns1:deleteUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:deleteUserResponse>
Python

getACCVersion

Retrieve the version of the Arrayent Cloud.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
Response
Element Name Data Type Description
releaseVersion string The release version of the Arrayent Cloud.
buildTimestamp string A timestamp in the format of YYYYMMDD-HHMM (year, month, day, hour, minute). The timestamp represents when this build of the Arrayent Cloud was internally created.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/getACCVersion?
secToken=md96mtpavu95682s
<ns1:getACCVersionResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <releaseVersion>1.22.0</releaseVersion>
 <buildTimestamp>20140321-1900</buildTimestamp>
</ns1:getACCVersionResponse>

getMobilePhonesByUserId

Retrieves a list of mobile devices that have been registered to receive push notifications.

Usage

getMobilePhonesByUserId retrieves a list of mobile devices that a Customer Account has registered to receive push notifications.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userId int The User ID of a Customer Account or System Account.
Response
Element Name Data Type Description
phoneList PhoneInfo A list of PhoneInfo elements. EachPhoneInfo element contains the Arrayent Cloud’s recorded information for a single mobile device.

The response will contain zero or more of the following PhoneInfo elements:

Name Data Type Description
ID int The ID for the mobile device. This value is generated by the Arrayent Cloud upon successful registrating of the device viaregisterMobilePhone. This is the value that you should provide when any web service operation requires phoneId as a parameter.
userID int The User ID of a Customer Account or System Account.
nativeID string A permanent, unique identifier for the device, such as a MAC address.
nativeSecurityToken string The device identifier for the mobile device. This is the ID that the Arrayent Cloud sends to the Google Cloud Messaging Service or Apple Push Notification Service to identify the device. For Android this is the registration_id of the device. For iOS this is the device token.
operatingSystem string The operating system of the mobile device. Valid options are android orios (assume case-sensitivity). This value is not sent to the Google Cloud Messaging Service or Apple Push Notification Service.
friendlyName string A friendly descriptor for the mobile device.
Examples

The request below returns a list of all mobile devices that a particular user has registered to receive push notifications.

https://example.arrayent.com:8081/zdk/services/zamapi/getMobilePhonesByUserId?
secToken=123-1009933734&userId=123

getMobilePhonesByUserId returns the list of all registered mobile devices for this user. To search for a specific device, find the listing that contains your mobile device’s nativeId, which is the permanent identifier for the device which you provided as a parameter to registerMobilePhone. In this example, the nativeId is the MAC address of the mobile device.


getServerTime

Retrieves the current time, as recorded by the Arrayent Cloud.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
Response
Element Name Data Type Description
time long A timestamp containing the current time. The timestamp is formatted as milliseconds since the UNIX Epoch.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/getServerTime?
secToken=908f293084f98uadvf9890235908
<ns1:getServerTimeResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <time>1394756397059</time>
</ns1:getServerTimeResponse>
Python

getUserValueList

Returns the current value of all user attributes for this particular user.

Usage

This is the preferred operation for retrieving user information.

This operation returns an attribute called customerName. This represents the username of the Customer Account. The Arrayent Cloud created this attribute and assigned its value when your app created the Customer Account via createNewUser.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userName string Optional – use either userName oruserId. The username of the Customer Account.
userId int Optional – use either userName oruserId. The User ID of a Customer Account or System Account.
Response
Element Name Data Type Description
userId int The User ID of a Customer Account or System Account.
valist AttrValue Zero or more valist elements. Eachvalist will contain two elements, name, which is the name of the attribute, andvalue, which is the value for that attribute.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/getUserValueList?
secToken=000-123456789&userName=ford.prefect&userId=819
Python

logout

Log out a user session in the Arrayent Cloud.

Usage

logout invalidates the security token of the specified account. This effectively logs out that user from the Arrayent Cloud. If the user attempts to use the old security token after logout has been called, the Arrayent Cloud will reject the request and return Error Code 106 (“Invalid security token.”).

A Customer Account can only use this operation to log itself out. It cannot logout any other Customer Accounts. A System Account can use this operation to log out any Customer Account, in addition to itself.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
username string The username of the account that will be logged out.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/logout?
secToken=134578sd8gf73q4tn783469081&username=john%40example.com

A successful logout request will receive the following response:

<ns1:logoutResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:logoutResponse>
<soapenv:Reason xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
 <soapenv:Text xml:lang="en-US">The endpoint reference (EPR) for the Operation
 not found is /zdk/services/zamapi/logout?secToken=134578sd8gf73q4tn783469081&
 username=john%40example.com and the WSA Action = null. If this EPR was previously
 reachable, please contact the server administrator.</soapenv:Text>
</soapenv:Reason>

A Customer Account attempting to logout another Customer Account will trigger a permission denied error.

<ns1:requestFault xmlns:ns1="http://arrayent.com/zamapi/">
 <errorCode>107</errorCode>
 <errorMsg>Permission denied.</errorMsg>
</ns1:requestFault>
Python

registerMobilePhone

Registers device identifier information for a mobile device (an iOS or Android smartphone or tablet), so that the Arrayent Cloud can send push notifications to the mobile device.

Usage

After the end user first installs your app and opts in to the push notification service, you need to register the mobile device with the Arrayent Cloud, so that the cloud has the device identifier information that it needs to send push notifications to the mobile device. If the registration is successful, the Arrayent Cloud will generate a random ID for the mobile device, called the phoneId. Your app will need to reference the mobile device by phoneId whenever it wants to perform subsequent operations on the device, such as updating the device’s information, or registering the device to receive push notifications.

The Arrayent Cloud requires two forms of device identification when registering a mobile device via the registerMobilePhone web service operation. These two identifiers are called the nativeId and the nativeSecurityToken. nativeId can be any form of permanent identification for the device, such as a MAC address. nativeSecurityToken is the opaque identifier that is generated by the Google Cloud Messaging Service (GCMS) or Apple Push Notification Service (APNS), distributed to the device from the service, and then delivered to the Arrayent Cloud via your app. Whenever the Arrayent Cloud wants to send a push notification to a device via the GCMS or APNS, it identifies the device using the nativeSecurityToken. The nativeSecurityToken can change. Your app should periodically check that the Arrayent Cloud’s record for the mobile device by retrieving the Arrayent Cloud’s record for the device, locating the device using the nativeId, and then comparing what the Arrayent Cloud has recorded for the nativeSecurityTokenagainst the true security token, which your app can retrieve from the mobile device’s operating system. If the Arrayent Cloud’s record is still accurate, then you do nothing. If the Arrayent Cloud’s record is out of date, then you update it via the updateMobilePhone web service operation.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userId int The User ID of a Customer Account or System Account.
nativeId string A permanent, unique identifier for the device, such as a MAC address.
operatingSystem string The operating system of the mobile device. Valid options are android orios (assume case-sensitivity). This value is not sent to the Google Cloud Messaging Service or Apple Push Notification Service.
nativeSecurityToken string The device identifier for the mobile device. This is the ID that the Arrayent Cloud sends to the Google Cloud Messaging Service or Apple Push Notification Service to identify the device. For Android this is the registration_id of the device. For iOS this is the device token.
friendlyName string Optional. A friendly descriptor for the mobile device.
mobileAppName string Optional. A permanent, unique identifier for the mobile application, previously “registered” withupdateApplicationConfiguration() .
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
phoneId int A unique integer identifying the mobile device, typically referred to as phoneId. The Arrayent Cloud generates this ID upon successful completion ofregisterMobilePhone. Subsequent operations on the mobile device, such as updating the Arrayent Cloud’s record for the device or creating alerts that send push notifications to this mobile device, require that you identify the mobile device by its phoneId.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/registerMobilePhone?
secToken=123-1234567890&userId=12345&nativeId=123456789ABCDEF123&
operatingSystem=ios&nativeSecurityToken=
1234567890abcdef1234567890abcdef1234567890abcdef
<ns1:registerMobilePhoneResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
 <phoneId>123</phoneId>
</ns1:registerMobilePhoneResponse>

setUserAttribute

Sets the value of a Customer Attribute.

Usage

This operation updates the value of a single Customer Attribute of a single Customer Account. By update we mean that you are writing a new value to the Arrayent Cloud’s database record of this attribute for this particular user.

You need to reference the Customer Account by its User ID. This value is returned in the response of userLogin. Your app should store it in a variable when you first login to the Arrayent Cloud on behalf of the user.

Parameters

The security token for this user’s Arrayent Cloud session.

Parameter Name Data Type Description
secToken string
userId int The User ID of a Customer Account or System Account.
name string The name of the attribute.
value string The value of the attribute.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/setUserAttribute?
secToken=000-123456789&userId=42&name=DeepThought&value=42

A return code of 0 indicates that the attribute value was successfully updated.

<ns1:setUserAttributeResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:setUserAttributeResponse>
Python

unregisterMobilePhone

Deletes the Arrayent Cloud’s record for a mobile device.

Usage

Deleting a mobile device record is a rare use case. unregisterMobilePhone deletes the Arrayent Cloud’s database record for the mobile device. This implies that you will never need to send a push notification to the mobile device again.

If you just want to disable a particular push notification alert, you can do so with removeTrigger, which deletes the alert, orupdateTriggerEnableState, which enables you to disable the alert.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userId int The User ID of a Customer Account or System Account.
phoneId int A unique integer identifying the mobile device, typically referred to as phoneId. The Arrayent Cloud generates this ID upon successful completion ofregisterMobilePhone. Subsequent operations on the mobile device, such as updating the Arrayent Cloud’s record for the device or creating alerts that send push notifications to this mobile device, require that you identify the mobile device by its phoneId.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples

To review, the phoneId that is being used to reference the mobile device is a random integer generated by the Arrayent Cloud upon registration of the mobile device. The phoneId can be retrieved via getMobilePhonesByUserId, and searching for the mobile device record that matches your mobile device ID (the value that you provided for nativeId when you called registerMobilePhone).

https://example.arrayent.com:8081/zdk/services/zamapi/unregisterMobilePhone?
secToken=818-230199725&userId=818&phoneId=461

A return code of 0 means that the operation was successful.

<ns1:unregisterMobilePhoneResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:unregisterMobilePhoneResponse>

updateMobilePhone

Updates the Arrayent Cloud’s information for a mobile device.

Usage

updateMobilePhone updates the Arrayent Cloud’s set of recorded information for a single mobile device. This information is called the mobile device record. The Arrayent Cloud uses this information to send push notifications to the mobile device.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
userId int The User ID of a Customer Account or System Account.
phoneId int A unique integer identifying the mobile device, typically referred to as phoneId. The Arrayent Cloud generates this ID upon successful completion ofregisterMobilePhone. Subsequent operations on the mobile device, such as updating the Arrayent Cloud’s record for the device or creating alerts that send push notifications to this mobile device, require that you identify the mobile device by its phoneId.
nativeSecurityToken string The device identifier for the mobile device. This is the ID that the Arrayent Cloud sends to the Google Cloud Messaging Service or Apple Push Notification Service to identify the device. For Android this is the registration_id of the device. For iOS this is the device token.
friendlyName string Optional. A friendly descriptor for the mobile device.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
https://example.arrayent.com:8081/zdk/services/zamapi/updateMobilePhone?
secToken=818-230199725&userId=818&phoneId=461&nativeSecurityToken=
checkOutThisNewNativeSecurityToken&friendlyName=android
<ns1:updateMobilePhoneResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:updateMobilePhoneResponse>

updatePassword

Updates the password of a user account.

Usage

Because this operation requires the old password in addition to the new password, you will not be able to use this operation for scenarios in which a user has forgotten the account password and wishes to reset the account password.

Parameters
Parameter Name Data Type Description
secToken string The security token for this user’s Arrayent Cloud session.
username string The username of the user account.
oldPassword string The current password of the user account.
newPassword string The new password of the user account.
Response
Element Name Data Type Description
retCode int A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/updatePassword?
secToken=1mrc96ac&oldPassword=Hello&newPassword=Goodbye&username=
john%40example.com

A return code of 0 indicates that the password has been successfully updated.

<ns1:updatePasswordResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:updatePasswordResponse>
Python

userLogin

Logs in to the Arrayent Cloud as a Customer Account.

Usage

Your app logs in to the Arrayent Cloud on behalf of an end user via the web service operations userLogin or systemLogin. If the provided user credentials are valid, then the cloud generates a security token and returns it to your app. Whenever your app wants to perform subsequent operations on behalf of the user, your app provides the security token as a parameter to the request. The cloud uses this security token to verify that your app is authorized to make requests on behalf of this user. A security token is valid for 15 minutes. If your app makes no requests to the Arrayent Cloud for 15 minutes, then the token goes stale and you will need to re-login as the user and get another security token. Every time that you perform a web service request, the current security token is renewed for another 15 minutes. A security token will remain indefinitely valid, so long as you are making one request every 15 minutes.

Parameters
Parameter Name Data Type Description
name string The username of the Customer Account.
password string The password of the Customer Account.
appId int The Application ID of the user account.
Response
Element Name Data Type Description
userId int The User ID of a Customer Account or System Account.
securityToken string The security token for this user’s Arrayent Cloud session.
Examples
HTTP
https://example.arrayent.com:8081/zdk/services/zamapi/userLogin?
name=john%40example.com&password=Hello1234&appId=1
<ns1:userLoginResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <userId>42</userId>
 <securityToken>897345hjaf234ggagdse25345</securityToken>
</ns1:userLoginResponse>
Python