Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

VIZpin API Specification v4.3

Note


In order to use this API you will need to have an account first. Please contact VIZpin Inc in order to become a partner.

The following features, even though they are available on our standard product through the use of the VIZpin Portal, they are note yet available through the API:

  • VIZpin Roles

  • Full support for FOB’s and CARDs

The following features, even though they are available on our OEM API, they are not available on out standard product through the use of the VIZpin Portal:

  • Multiple Sites/locations per account

NOTE: If you need to use any of these features you should only use the API or the Portal. If you need to use both, please do not use these features because you might reach some data inconsistancy.

 REVISION HISTORY

Table of Contents
outlinetrue

Overview

The VIZpin OEM API is a programmatic interface to many of the commonly used VIZpin platform functions. It is expected that the major uses of the API will be customized applications of VIZpin platform but from the server or applications of the implementing OEM partner.

Assumptions

The API is based on the JSON-RPC 2.0 Specification (http://www.jsonrpc.org/specification). In general, this specification will not repeat information in the JSON-RPC specification. We will be using named, not positional parameters.
Sessions and access tokens may expire after inactivity and you may need to re-authenticate.
Authentication will be a combination user login/JWT Token and pre-authorized IP addresses as required.
All other parameters are required. Responses will always contain all attributes.

VIZpin OEM API URLs

Access to the VIZpin API will use the following production URL: {+}https://www.vizpin.net/services/apexrest/oem-api+
You may also be given a test sandbox for use in development with a specific URL.
You will also be given an OEM_KEY similar to this: e6f90bc9e228a6d5b054cdb89c7eb550

VIZpin OEM API Version

OEM Partners will follow a specific API version depending on the requirements needed.
This API document is build for API version 2. App version will be validated per partner.

VIZpin OEM API Authentication

Authentication is restricted by IP address.
Here is an example of how to use curl to authenticate a session with the authenticate method:

Code Block
languagebash
curl -H 'Content-Type: application/json' \ -d '{ "!version":"2", "id":1491396942, "method":"com.vizpin.user.authenticate", "jsonrpc":"2.0", "params":{"username":"user@test.com", "password":"notarealpassword", "oem_key":"63C81EF5398EFEDE9D0AE93E551AAF29"}}' \ <<SANDBOX URL>>/VIZpin/services/apexrest/oem-api


Parameters:

Name

Description

Remarks

!version

Api version

Required
Actual Value: 2.0

id

Message id used as reference for request and response calls

Required
Maximum of 10 alphanumeric

method

"com.vizpin.user.authenticate"

Required
Actual Input

username

Username set

Required
Assign per OEM partner

password

Password set

Required
Assign per OEM partner

oem_key

Oem Key assigned

Required
Assign per OEM partner


This will return a JSON response similar to this ("token" below has been shortened):

Code Block
languagejs
{ 
"result": { 
"message": "User successfully authenticated and verified", 
"code": 9, 
"now": 1560932375, 
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9FTUFQSSJ..." 
}, 
"jsonrpc": "2.0", 
"id": 1491396943, 
"status": 1 
}


You can then use the token as Header property to make VIZpin API calls, like this:

Code Block
languagebash
curl _-H "token: 00D50TrZ!AR8AQAPolUJR.dgM2co9D_OkVn9QoGtPemlt3q5HT3sv.C0W" -H 'Content-Type: application/json' -d { "!version":"1", "id":1491396942, "method":"com.vizpin.time", "jsonrpc":"2.0, "params":{"oem_key": OEM_KEY}} \<<SANDBOX URL>>/VIZpin/services/apexrest/oem-api 


And you should get a response similar to this:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS,
"result":{ 
"now":1437910464,
"code":API_VIZPIN_TIME_SUCCESS,
"message":" User requested time"
},
"Jsonrpc":"2.0", "!version" : "2",
"id":1491396942
} 


High-level Object Relationship Diagram

Account

An ACCOUNT has a 1-to-many relationship with LOCATION, while READER is referenced to LOCATION ID. Each READER has a child READER SETTINGS. However, if a Reader is set to first-in mode, a SCHEDULE is required.
ACCOUNTLOCATIONREADERReader SettingsSchedule_Schedule Element_First-in Schedule1...n1...n

Sample Structure:
Sample Diagram of Account and Location Association_Account_1Location_1Location_2Location_3Reader_1Reader_nReader_4Reader_3Reader_5Reader_6Reader_7Reader_n_Schedule_Schedule Element_first_in = "on"

Card Number

A USER may have several unique credentials with Wiegand representation.
UserCredential1...nAccount1...n

VIZpin/PLUS

A USER may have VIZpins for Mobile Access. Each VIZpin is scheduled, in a daily or daily multi-timespan mode. A VIZpin is related to a READER is related to LOCATION and LOCATION to an ACCOUNT.
UserVIZpinREADERScheduleSchedule Element"Custom" or "24x7"1...n1...nLocationAccount


Entity Relationship Diagram



Diagram showing relationship of entities and its properties

VIZpin OEM API Methods

  • All API calls must be made via OAuth 2.0 authenticated clients.

  • All data API calls must contain an OEM_KEY which limits results to your OEM objects.

  • All calls return an attribute of "status" which represents success (value = 1) or failure (value = 0).

  • All successful calls return an attribute of "result" which contains attributes for "code" and "message" which describes the result as well as request specific response attributes.


Sample Result:

Code Block
languagejs
{ 
"status": 1 
"result": { 
"message": "User successfully authenticated and verified", 
"code": 9, 
"now": 1561086713 
} 
}


  • All failed calls return an attribute of "error" which contains attributes for "code" and "message" which describes the error as well as request specific response attributes.


Sample Result:

Code Block
languagejs
{ 
"status": 0 
"result": { 
"message": "Missing or invalid password or username", 
"code": 4 
} 
}


  • All successful calls return an attribute of "now" in the "result" attribute that represents the server's current time.

  • All error codes and status codes are defined in the appendix.

API METHODS

Authenticate

This method is used to create a session, and return an authentication token.

  • Method Name: com.vizpin.user.authenticate

  • Request Parameters:"oem_key" – Unique key to limit data results to your OEM
    "username" - assigned username.
    "password" - assigned password

  • Response Attributes: "token" – access token in making API calls.


Sample Request:

Code Block
languagejs
{ 
"id":"2272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.authenticate", 
"params":{ 
"oem_key":"OEM_KEY", 
"username":"test@user.com", 
"password":"notarealpassword" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":1, 
"result":{ 
"message":"User successfully authenticated and verified", 
"code":API_VIZPIN_AUTENTICATE_SUCCESS, 
"now":1502744478, 
"token":"00D50TrZ!AR8AQAPolUJR.dgM2co9D_OkVn9QoGtPemlt3q5HT3sv.C0W…" 
} 
}"jsonrpc":"2.0" 
"id":1491396942 
}


Sample Code:

Code Block
languagejava
public string GetVizpinAuthenticationToken() 
{ 
string token = string.Empty; 
string userName = ConfigurationHelper.Vizpin_USERNAME; 

var httpWebRequest = (HttpWebRequest)WebRequest.Create(<<SANDBOX URL>>/VIZpin/services/apexrest/oem-api); 

httpWebRequest.Method = "POST"; 
httpWebRequest.ContentType = contenttype; 
httpWebRequest.Credentials = CredentialCache.DefaultCredentials; 

string json = new JavaScriptSerializer().Serialize(new 
{ 
!version = "2", 
id = "1234567", 
method = "com.vizpin.user.authenticate", 
jsonrpcs = "2.0", 
param = new 
{ 
username = "test@user.com", 
password = "mypassword", 
oem_key = "245aa68490c94hafg199d62c5b6f7f77" 
} 
}); 

token = SendHttpWebRequest(httpWebRequest, json); 

var result = JsonConvert.DeserializeObject<Result_Authenticate>(token); 

return result.token; 
}


Get Time

This method is used to get the server time and test that your credentials are working.

  • Method Name: com.vizpin.time

  • Request Parameters: "oem_key" - predefined oem key

  • Response Attributes: "now" - server time in GMT

Sample Request:

Code Block
languagejs
{ 
"id":"1272", 
"Jsonrpc":"2.0", "!version" : "2" 
"method":com.vizpin.time", 
"params":{ 
"oem_key":OEM_KEY 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_TIME_SUCCESS, 
"message":" User requested time" 
}, 
"Jsonrpc":"2.0" 
"id":1272 
}


Sample Code:

Code Block
languagejava
public string GetVizpinTime() { 
string result = string.Empty; 

string token = GetVizpinAuthenticationToken(); 

var httpWebRequest = (HttpWebRequest)WebRequest.Create(OEM_URL); 

httpWebRequest.Method = "POST"; 
httpWebRequest.Headers["token"] = token; 
httpWebRequest.ContentType = contenttype; 
httpWebRequest.Credentials = CredentialCache.DefaultCredentials; 

string json = new JavaScriptSerializer().Serialize(new 
{ 
!version = "2", 
id = id, 
method = "com.vizpin.time", 
jsonrpc = "2.0", 
param = new 
{ 
oem_key = "OEM_KEY" 
} 
}); 

result = SendHttpWebRequest(httpWebRequest, json); 

var datenow = JsonConvert.DeserializeObject<Result_GetTime>(result); 

return datenow.result.serverdate.Tostring(); 
}



List Accounts

This method is used to get a list of Accounts currently on the specified account.

  • Method Name:com.vizpin.account.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM

  • Response Attributes: "accounts" – Array of Account objects (see Appendix for objects)


Sample Request:

Code Block
languagejs
{ 
"Id":"2272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.account.list", 
"params":{ 
"oem_key":OEM_KEY 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_ACCOUNT_LIST_SUCCESS, 
"message":" Successful listing of accounts", 
"accounts":[ 
ACCOUNT_OBJECT_1, 
ACCOUNT_OBJECT_2……. 
] 
}, 
"Jsonrpc":"2.0" 
"id":"2272" 
}

Get Account

This method is used to get Account to your OEM.

  • Method Name: com.vizpin.account.get

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "accountid" – Account to retrieve.

  • Response Attributes: "account" – newly created Account object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"3272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.account.get", 
"params":{ 
"oem_key":OEM_KEY, 
"id":accountid 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_ACCOUNT_GET_SUCCESS, 
"message":" Successful getting of account", 
"account":ACCOUNT_OBJECT_1 
}, 
"Jsonrpc":"2.0", 
"id":"3272" 
}

Add Account

This method is used to add a new Account to your OEM.

  • Method Name: com.vizpin.account.add

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "account" – Account object to create (see Appendix for objects)

  • Response Attributes: "account" – newly created Account object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"3272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.account.add", 
"params":{ 
"oem_key":OEM_KEY, 
"add_account":ACCOUNT_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_ACCOUNT_ADD_SUCCESS, 
"message":" Successful adding of account", 
"account":ACCOUNT_OBJECT_1 
}, 
"Jsonrpc":"2.0", 
"id":"3272" 
}

Edit Account

This method is used to edit an existing Account in your OEM.

  • Method Name: com.vizpin.account.edit

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "account" – Account object to create (see Appendix for objects)

  • Response Attributes: "account" – newly created Account object (see Appendix for objects)


Sample Request:

Code Block
languagejs
{ 
"id":"3272", 
"Jsonrpc":"2.0", "!version" : "2" 
"method":com.vizpin.account.edit", 
"params":{ 
"oem_key":OEM_KEY, 
"account":ACCOUNT_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_ACCOUNT_EDIT_SUCCESS, 
"message":" Successful editing of account", 
"account":ACCOUNT_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"3272" 
}

List Locations By Account

This method is used to get a list of Locations of the specified account.

  • Method Name:com.vizpin.location.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM
    "accountid" – Account to retrieve locations

  • Response Attributes: "locations" – Array of Location objects (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"2272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.location.list", 
"params":{ 
"oem_key":OEM_KEY, 
"accountid":accountid, 
} npotio
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_LOCATION_LIST_SUCCESS, 
"message":" Successful listing of locations", 
"locations":[ 
LOCATION_OBJECT_1 
LOCATION_OBJECT_2……. 
] 
}, 
"jsonrpc":"2.0", 
"id":"2272" 
}

Get Location

This method is used to get a Location object per location.

  • Method Name: com.vizpin.location.get

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "id" – location object to create (see Appendix for objects)

  • Response Attributes: "locations" – newly created Account object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"3272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.location.get", 
"params":{ 
"oem_key":OEM_KEY, 
"id":LOCATION_ID 
}}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_LOCATION_GET_SUCCESS, 
"message":" Successful getting of location", 
"locations":[ 
LOCATION_OBJECT_1 
] 
}, 
"jsonrpc":"2.0", 
"id":"3272" 
}

Add Location

This method is used to add a new location to an Account.

  • Method Name: com.vizpin.location.add

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "location" – single location object to create (see Appendix for objects)
    Set id = "" for new object

  • Response Attributes: "locations" – newly created location object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"3272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.location.add", 
"params":{ 
"oem_key":OEM_KEY, 
"location":LOCATION_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_LOCATION_ADD_SUCCESS , 
"message":" Successful adding of location", 
"locations":LOCATION_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"3272" 
}


Edit Location

This method is used to edit an existing location to an Account.

  • Method Name: com.vizpin.location.edit

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "location" – location object to edit (see Appendix for objects)

  • Response Attributes: "locations" – newly created Account object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"3272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.location.edit", 
"params":{ 
"oem_key":OEM_KEY, 
"location":LOCATION_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_LOCATION_EDIT_SUCCESS, 
"message":" Successful adding of location", 
"locations":LOCATION_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"3272" 
}


List Readers

This method is used to get a list of Readers currently on the specified Location.

  • Method Name: com.vizpin.reader.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "locationid" – locationID from previous Add or List Locations response

  • Response Attributes: "readers" – Array of Reader objects (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"4272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.reader.list", 
"params":{ 
"oem_key":OEM_KEY, 
"locationid":"a0G3300030aYQaF" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_READER_LIST_SUCCESS, 
"message":" Successful listing of readers", 
"readers":[ 
READER_OBJECT_1, 
READER_OBJECT_2 
] 
}, 
"jsonrpc":"2.0", 
"id":"4272" 
}

Get Reader

This method is used to get a Reader object.

  • Method Name: com.vizpin.reader.get

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "readerid" – readerID from previous Add or List Reades response

  • Response Attributes: "readers" – Reader object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"4272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.reader.get", 
"params":{ 
"oem_key":OEM_KEY, 
"readerid":"a0G3300030aYQaF" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_READER_GET_SUCCESS, 
"message":" Successful listing of readers", 
"readers":[ 
READER_OBJECT_1 
] 
}, 
"jsonrpc":"2.0", 
"id":"4272" 
}

Add Reader

This method is used to add a new Reader to one of your Accounts.

  • Method Name: com.vizpin.reader.add

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "reader" – Reader object to create (see Appendix for objects)

  • Response Attributes: "reader" – newly created Reader object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"5272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.reader.add", 
"params":{ 
"oem_key":OEM_KEY, 
"add_reader":READER_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_READER_ADD_SUCCESS, 
"message":" Successful adding of reader", 
"reader":READER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"5272" 
}

Edit Reader

This method is used to edit a Reader on one of your Accounts.

  • Method Name: com.vizpin.reader.edit

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "edit_reader" – Reader object to edit (see Appendix for objects)

  • Response Attributes: "reader" – Reader object modified (see Appendix for objects)


Sample Request:

Code Block
languagejs
{ 
"id":"5272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.reader.edit", 
"params":{ 
"oem_key":OEM_KEY, 
"edit_reader":READER_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_READER_EDIT_SUCCESS, 
"message":" Successful adding of reader", 
"reader":READER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"5272" 
}


Count Users

This method is used to get the total number of users per account and to specify the number of batches com.vizpin.user.list must be called/executed to get the all users in an Account or Location. If locationid is empty, return result will be filtered by Account. Otherwise, the result will be filtered by Location.

  • Method Name: com.vizpin.user.count

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "account_id" – if locationid is empty result will be filtered by Account ID
    "locationid" – Location ID from previous Add or List Location response

  • Response Attributes:
    "totalcount" – total number of users per Account/Location
    "batchcounter" – total number of com.vizpin.user.list to get all users '
    requested

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.count", 
"params":{ 
"oem_key":OEM_KEY, 
"account_id":"a0G3300030aYQaF", 
"locationid":"" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_COUNT_SUCCESS, 
"message":" Successful listing of users' count", 
"totalcount":"200", 
"batchcounter":"2" 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

List Users

This method is used to get a list of Users currently on the specified Account or Location. If locationid is empty, return result will be filtered by Account. Otherwise, the result will be filtered by Location.

  • Method Name: com.vizpin.user.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "account_id" – If locationid is empty result will be filtered by Account ID
    "locationid" – Location ID from previous Add or List Location response
    "totalcount" – total number of users per Account/Location, result from com.vizpin.user.count
    "batchcount" - default to 1, result from com.vizpin.user.count

  • Response Attributes:
    "users" – Array of User objects (see Appendix for objects)
    "totalCount" - total number of users


Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.list", 
"params":{ 
"oem_key":OEM_KEY, 
"account_id":"a0G3300030aYQaF", 
"locationid":"", 
"totalcount":"200", 
"batchcounter":"1" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_LIST_SUCCESS, 
"message":" Successful listing of users", 
"users":[ 
USER_OBJECT_1, 
USER_OBJECT_2……. 
] 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}


Sample Code:

Code Block
languagejava
public Result_GetListUsers GetUserList(string accountID, string locationID) 
{ 
Result_GetListUsers users = new Result_GetListUsers (); 
string token = string.Empty; 
string userName = ConfigurationHelper.Vizpin_USERNAME; 
var httpWebRequest = (HttpWebRequest)WebRequest.Create(<<SANDBOX URL>>/VIZpin/services/apexrest/oem-api); 

httpWebRequest.Method = "POST"; 
httpWebRequest.ContentType = contenttype; 
httpWebRequest.Credentials = CredentialCache.DefaultCredentials; 

string json = new JavaScriptSerializer().Serialize(new 
{ 
version = "2.0", 
id = "1234567", 
method = "com.vizpin.user.count", 
jsonrpcs = "2.0", 
param = new 
{ 
"oem_key":OEM_KEY, 
"account_id":accountID, 
"locationid": locatonID 
} 
}); 

var usercount = SendHttpWebRequest(httpWebRequest, json); 
var result = JsonConvert.DeserializeObject<Result_UserCount>(usercount ); 

int totalcount = result.totalcount; 
int batchcounter = result.batchcounter; 

If (totalcount > 0) 
{ 
for (i=1, i= batchCounter, i++) 
{ 
users.AddList(GetUserList(accountID, locationID, totalcount, batchcounter)); 
} 
} 

return users; 
} 

public Result_GetListUsers GetUserList(string accountID, string locationID, int batchCounter, int totalCount) 
{ 
string token = string.Empty; 
string userName = ConfigurationHelper.Vizpin_USERNAME; 
var httpWebRequest = (HttpWebRequest)WebRequest.Create(<<SANDBOX URL>>/VIZpin/services/apexrest/oem-api); 

httpWebRequest.Method = "POST"; 
httpWebRequest.ContentType = contenttype; 
httpWebRequest.Credentials = CredentialCache.DefaultCredentials; 

string json = new JavaScriptSerializer().Serialize(new 
{ 
version = "2.0", 
id = "1234567", 
method = "com.vizpin.user.list", 
jsonrpcs = "2.0", 
param = new 
{ 
"oem_key":OEM_KEY, 
"account_id":"accountID", 
"locationid":"", 
"totalcount": totalCount, 
"batchcounter": batchCounter 
} 
}); 

result = SendHttpWebRequest(httpWebRequest, json); 

var users = JsonConvert.DeserializeObject<Result_GetListUsers>(result); 

return users; 

}

Find User

This method is used to find a user by phone and name, across all Accounts.

  • Method Name: com.vizpin.user.find

  • Request Parameters: "phone" – Mobile phone number for existing User, including country
    "last_name" – Last Name

  • Response Attributes: "user" – Single User object matching query (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.find", 
"params":{ 
"phone":"+15551234567", 
"last_name":"Smith" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_FIND_SUCCESS, 
"message":" Found User", 
"user":USER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Get User

This method is used to find a user by user id, across all Accounts.

  • Method Name: com.vizpin.user.get

  • Request Parameters: "userid" – user id of the User to search

  • Response Attributes: "user" – Single User object matching query (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":"com.vizpin.user.get", 
"params":{ 
"userid":"a0G5600030aYZbN" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_GET_SUCCESS, 
"message":" Found User", 
"user":USER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

PreRegister User

This method is used to pre-register a User. Used only when you want to pre register a smart app user that is not yet registered by VIZpin app SDK or VIZpin SMART app. This method does not require a password, so the user needs to reset the password on first usage of the VIZpin SMART app.

  • Method Name: com.vizpin.user.preregister

  • Request Parameters: "preregister_user" – Single PreRegistered User object to add (see Appendix for objects)

  • Response Attributes: "preregister_user" – Single PreRegistered User object result

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":"com.vizpin.user.preregister", 
"params":{ 
"preregister_user":"PREREGISTERED_USER_OBJECT_1" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_REGISTER_SUCCESS, 
"message":"Successful User Registration", 
"preregister_user":"PREREGISTERED_USER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Register User

This method is used to register a User. Used only when you want to fully register a smart app user that is not yet registered by VIZpin app SDK or VIZpin SMART app. This method requires a pre-defined password that can be shared with the VIZpin SMART app user.

  • Method Name: com.vizpin.user.register

  • Request Parameters: "user" – Single User object to add (see Appendix for objects)

  • Response Attributes: "user" – Single User object result

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":"com.vizpin.user.register", 
"params":{ 
"user":"USER_OBJECT_1" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_REGISTER_SUCCESS, 
"message":"Successful User Registration", 
"user":USER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Edit User

This method is used to edit a User by user id, across all Accounts.

  • Method Name: com.vizpin.user.edit

  • Request Parameters: "user" – Single User object to modify (see Appendix for objects)

  • Response Attributes: "user" – Single User object result (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.edit", 
"params":{ 
"user":"USER_OBJECT_1" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_EDIT_SUCCESS, 
"message":"Successful User Edit", 
"user":USER_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Delete User

This method is used to delete a User by user id, across all Accounts.

  • Method Name: com.vizpin.user.delete

  • Request Parameters: "userid" – Single User object to modify (see Appendix for objects)


Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.delete", 
"params":{ 
"oem_key":"d41d8cd98f00b204e9800998ecf8427e", 
"user_id": "a0q56000000YW6PAAsW" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_EDIT_SUCCESS, 
"message":"Successful User Deleted", 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Associate User

This method is used to associate an existing User to one of your Accounts.

  • Method Name: com.vizpin.user.associate

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "location_ids" – location IDs from previous Add or List Location response,
    "assoc_user" – User ID from previous Add, List, or Find response

  • Response Attributes: "user" – Arraylist of User credentials object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id": "7272", 
"jsonrpc": "2.0", 
"method": com.vizpin.user.associate", 
"params": { 
"oem_key" : OEM_KEY, 
"location_ids" : ["a0j63000015uTiOAAU", "a0j63000015uTiOAAU"] 
"assoc_user" : USER_OBJECT_1 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status" : API_VIZPIN_SUCCESS, 
"result" : { 
"now" : 1437910464, 
"code" : API_VIZPIN_USER_ASSOCIATE_SUCCESS, 
"message" : " Successful association of user", 
"user" : USER_OBJECT_1}, 
"jsonrpc" : "2.0", 
"id" : "7272" 
}

Get User Credentials

This method is used to get all wiegand credentials of a user.

  • Method Name: com.vizpin.credential.get

  • Request Parameters: "userid" – id of the User to retrieve all wiegand credentials

  • Response Attributes: "credentials" – Arraylist of User credentials object (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.credential.get", 
"params":{ 
"userid":"userid" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_CREDENTIAL_GET_SUCCESS, 
"message":"Successful User Credential List", 
"credentials":CREDENTIAL_OBJECT_1, 
CREDENTIAL_OBJECT_2, n….. 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Generate User Credential

This method is used to generate wiegand credentials of a user. [Needs to coordinate with VIZpin regarding the implementation fo card number generation per partner)

  • Method Name: com.vizpin.credential.generate

  • Request Parameters: "userid" – id of the User to generate a wiegand credential
    "account_id" of the Account.

  • Response Attributes: "credentials" – Single User credentials object created (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"jsonrpc":"2.0","!version" : "2", 
"method":com.vizpin.credential.generate", 
"params":{ 
"userid":"userid", 
"account_id":"account_id" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_CREDENTIAL_GENERATE_SUCCESS, 
"message":"Successful Credential Generation", 
"credentials":WIEGAND_CREDENTIAL_OBJECT_1 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

List Users the Need Access

This method is used to get a list of Users currently on the specified Account or Location the need access for granting. If locationid is empty, return result will be filtered by Account. Otherwise, the result will be filtered by Location.

  • Method Name: com.vizpin.user.NeedAccess

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "account_id" – If locationid is empty result will be filtered by Account ID
    "locationid" – Location ID from previous Add or List Location response

  • Response Attributes:
    "users" – Array of User objects (see Appendix for objects)
    "totalCount" - total number of users


Sample Request:

Code Block
languagejs
{
    "!version": "2",
    "id": 1491396943,
    "method": "com.vizpin.user.NeedAccess",
    "jsonrpc": "2.0",
    "params": {
        "oem_key": "86f26ef9042e4fb6ab3016293957e5c9",
        "account_id": "a0M2300000080KGEAY",
        "locationid": "a0j230000007hsfAAA"
    }
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_LIST_SUCCESS, 
"message":" Successful listing of users", 
"users":[ 
USER_OBJECT_1, 
USER_OBJECT_2……. 
] 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Grant Phone Role to User

This method is used to grant a SmartPhone role based permissions to a user.

  • Method Name: com.vizpin.user.grantphonerole

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "site_id" – Site ID from previous Add or List Locations response,
    "user_ids" – list of user ids to be granted,
    "role_ids" – list of role ids to grant to users,
    "start_date" – Date when the permission became effective,
    "stop_date" – Date when the permission expires

Sample Request:

Code Block
languagejs
{ 
  "id":"8272", 
  "Jsonrpc":"2.0", "!version" : "2", 
  "method":com.vizpin.user.grantphonerole", 
  "params":{ 
    "oem_key":OEM_KEY, 
    "site_id":"a0G3300030aYQaF", 
    "user_ids":["a0G3300030aYWbD"], 
    "role_ids":["a0G4400030aCVaT", "a0V6701039bTBdT],
    "start_date":"2023-12-08",
    "stop_date":"2024-12-09"
  } 
}

Sample Response:

Code Block
languagejs
{ 
  "status":API_VIZPIN_SUCCESS, 
  "result":{ 
    "now":1437910464, 
    "code":API_VIZPIN_USER_GRANT_SUCCESS, 
    "message":" "Grant successfully completed.", 
  }, 
  "jsonrpc":"2.0", 
  "id":"8272"
}

List Roles

This method is used to list Roles of a specific Site.

  • Method Name: com.vizpin.role.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM
    "site_id" – Site ID from previous Add or List Locations response,
    "role_type" – role type to filter (as of 2023-12-08 only Phone type support is implemented)

  • Response Attributes: "roles" – Array of Role objects (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
  "id":"8272", 
  "Jsonrpc":"2.0", "!version" : "2", 
  "method":com.vizpin.role.list", 
  "params":{ 
    "oem_key":OEM_KEY, 
    "site_id":"a0G3300030aYQaF", 
    "role_type":"Phone"
  } 
}

Sample Response:

Code Block
languagejs
{ 
  "status":API_VIZPIN_SUCCESS, 
  "result":{ 
    "now":1437910464, 
    "code":API_VIZPIN_ROLE_LIST_SUCCESS, 
    "message":"List successfully retrieved.", 
    "roles":[ 
      ROLE_OBJECT_1, 
      ROLE_OBJECT_2……. 
      ] 
  }, 
  "jsonrpc":"2.0", 
  "id":"8272"
}

Add Role

This method is used to add a new Role to one of your Locations.

  • Method Name: com.vizpin.role.add

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "site_id" – Site ID from previous Add or List Locations response,
    "role_name" – New Role name,
    "role_type" – New Role type (as of 2023-12-08 only Phone type support is implemented)

  • Response Attributes: "roleId" – Id of newly created Role object

Sample Request:

Code Block
languagejs
{ 
  "id":"5272", 
  "Jsonrpc":"2.0", "!version" : "2", 
  "method":com.vizpin.role.add", 
  "params":{ 
    "oem_key":OEM_KEY,
    "site_id":"a0G3300030aYQaF",
    "role_name": "New Role Name",
    "role_type": "Phone" 
  } 
}

Sample Response:

Code Block
languagejs
{ 
  "status":API_VIZPIN_SUCCESS, 
  "result":{ 
    "now":1437910464, 
    "code":API_VIZPIN_ROLE_ADD_SUCCESS, 
    "message":"Role added successfully.", 
    "roleId": "a0w7h000000zLJ9AAM" 
  }, 
  "jsonrpc":"2.0", 
  "id":"5272" 
}

Edit Role

This method is used to edit an existing Role.

  • Method Name: com.vizpin.role.edit

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "site_id" – (Mandatory) Site ID from previous Add or List Locations response,
    "role_id" – (Mandatory) Role ID from previous Add or List Roles response,
    "reader_id" – (Optional) Reader ID from previous Add or List Readers response,
    "schedule_type" – (Optional) Schedule type to be applied to the specified reader_id (as of 2023-12-08 only None and 24x7 types support is implemented)

Sample Request:

Code Block
languagejs
{ 
  "id":"5272", 
  "Jsonrpc":"2.0", "!version" : "2", 
  "method":com.vizpin.role.edit", 
  "params":{ 
    "oem_key":OEM_KEY,
    "site_id":"a0G3300030aYQaF",
    "role_id":"a0w7h000000zLJ9AAM,
    "reader_id": "a0w7h000000zLJ9AAM",
    "schedule_type": "24x7"
  } 
}

Sample Response:

Code Block
languagejs
{ 
  "status":API_VIZPIN_SUCCESS, 
  "result":{ 
    "now":1437910464, 
    "code":API_VIZPIN_ROLE_EDIT_SUCCESS, 
    "message":"Role edited successfully."
  }, 
  "jsonrpc":"2.0", 
  "id":"5272" 
}

List VIZpins

This method is used to list VIZpins of a User with specified the Readers.

  • Method Name: com.vizpin.vizpin.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM
    "account_id" – Account ID from previous Add or List Accounts response,
    "user_id" – userid to filter
    "reader_ids" – list of reader ids to filter, empty to get all User's Vizpins

  • Response Attributes: "vizpins" – Array of VIZpin objects (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ 
"id":"8272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.vizpin.list", 
"params":{ 
"oem_key":OEM_KEY, 
"user_id":"a0G3300030aYQaF", 
"account_id":"a0G3300030aYWbD", 
"reader_ids":["a0G4400030aCVaT", "a0V6701039bTBdT] 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_VIZPIN_LIST_SUCCESS, 
"message":" Successful listing of VIZpins", 
"vizpins":[ 
VIZPIN_OBJECT_1, 
VIZPIN_OBJECT_2……. 
] 
}, 
"jsonrpc":"2.0", 
"id":"8272"}

Grant VIZpin (DEPRECATED- user GRANT PHONE ROLE instead)

This method is used to grant a User access to a Reader.  Multiple Schedule is activated per Partner license (please coordinate with VIZpin technical support is this feature is needed)

  • Method Name: com.vizpin.vizpin.grant

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "user_ids" – list of User IDs from previous Add or List Users response,
    "reader_ids" – list of Reader IDs for key granting
    "schedule" – Schedule object for grant (see Appendix for objects)

  • Response Attributes: "vizpins" – list of newly created VIZpin objects (see Appendix for objects)

Sample Request (Simple 24x7):

Code Block
languagejs
{ 
"id":"9272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":"com.vizpin.vizpin.grant", 
"params":{ 
"oem_key":OEM_KEY, 
"user_ids":["a0a3300030CnPv1"], 
"reader_ids":["a0a330020CfENt"], 
"schedule":[ 
] 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_VIZPIN_GRANT_SUCCESS, 
"message":" Successful granting of VIZpin", 
"vizpins":[ 
VIZPIN_OBJECT_1 
] 
}, 
"jsonrpc":"2.0", 
"id":"9272"}


Sample Request (Custom Schedule):

Grant Custom Schedule
Code Block
languagejava
{  
   "!version":"2",
   "id":1491396943,
   "method":"com.vizpin.vizpin.grant",
   "jsonrpc":"2.0",
    "params":{   
      "oem_key":"86f26ef9042e4fb6ab3016293957e5c9",
      "reader_ids" : ["a0c56000001cPIRAA2"],
      "user_ids" : ["a0q56000000ao1TAAQ"],
      "start_date" : "2020-01-01",
      "stop_date" : "2020-12-31 17:00:01",
      "schedule" : {
      	"type": "custom",
      	"scheduleelement":{
      		"monday_begin" : "05:00 PM",
      		"monday_end" : "06:00 PM",
      		"tuesday_begin" : "05:00 PM",
      		"tuesday_end" : "06:00 PM",
      		"wednesday_begin" : "05:00 PM",
      		"wednesday_end" : "06:00 PM",
			"thursday_begin" : "05:00 PM",
      		"thursday_end" : "06:00 PM",
			"friday_begin" : "05:00 PM",
      		"friday_end" : "06:00 PM"
      	}
      }
   }
}


Sample Request (Multiple Schedule):


Multiple Schedule
Code Block
languagejava
{
    "!version": "2",
    "id": 1491396943,
    "method": "com.vizpin.vizpin.grant",
    "jsonrpc": "2.0",
    "params": {
        "oem_key": "86f26ef9042e4fb6ab3016293957e5c9",
        "reader_ids": [
            "a0c56000001JpgnAAC"
        ],
        "user_ids": [
            "a0q56000000any3AAA"
        ],
        "start_date": "2020-04-25",
        "stop_date": "2020-08-31 17:00:01",
        "schedule": {
            "type": "multiple",
            "scheduleelement": {
                "includedates": [
                    {
                        "date": "2020-04-30",
                        "recurring": "false",
                        "time": [
                            {
                                "begin": "09:00 AM",
                                "end": "12:00 PM"
                            },
                            {
                                "begin": "08:00 AM",
                                "end": "05:00 PM"
                            },
                            {
                                "begin": "08:00 AM",
                                "end": "05:00 PM"
                            }
                        ]
                    }
                ],
                "excludedates": {
                    "recurring": [
                        "2020-04-30"
                    ],
                    "nonrecurring": [
                        "2020-04-01"
                    ]
                },
                "weekdays": {
                    "thursday": {
                        "time": [
                            {
                                "begin": "09:00 AM",
                                "end": "09:25 AM"
                            },
                            {
                                "begin": "09:30 AM",
                                "end": "09:55 AM"
                            },
                            {
                                "begin": "10:00 AM",
                                "end": "10:25 AM"
                            },
                            {
                                "begin": "10:30 AM",
                                "end": "10:55 AM"
                            },
                            {
                                "begin": "11:00 AM",
                                "end": "11:25 AM"
                            }
                        ]
                    },
                    "friday": {
                        "time": [                           
                            {
                                "begin": "03:30 PM",
                                "end": "03:55 PM"
                            },
                            {
                                "begin": "04:00 PM",
                                "end": "04:25 PM"
                            },
                            {
                                "begin": "04:30 PM",
                                "end": "04:55 PM"
                            },
                            {
                                "begin": "05:00 PM",
                                "end": "05:25 PM"
                            },
                            {
                                "begin": "05:30 PM",
                                "end": "05:55 PM"
                            }
                        ]
                    }
                }
            }
        }
    }
}

Revoke VIZpin

This method is used to revoke a User's access to a Reader.

  • Method Name: com.vizpin.vizpin.revoke

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "vizpin_ids" – list of VIZpin IDs from previous Grant or List VIZpins response,

  • Response Attributes: "vizpins" – revoked array list of VIZpin object (see Appendix for objects)


Sample Request:

Code Block
languagejs
{ 
"id":"10272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.vizpin.revoke", 
"params":{ 
"oem_key":OEM_KEY, 
"vizpin_ids":[ 
"a0a3303300CH9zq" 
] 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_VIZPIN_REVOKE_SUCCESS, 
"message":" Successful revoking of VIZpin", 
"vizpins":[ 
VIZPIN_OBJECT_1 
] 
}, 
"jsonrpc":"2.0", 
"id":"10272" 
}


List Activity

This method is used to list unlock Activity on the Account and User or Reader. If Reader is empty, api will get all activities of User per Account specified. Otherwise, return will be activities of a reader.

  • Method Name: com.vizpin.activity.list

  • Request Parameters: "oem_key" – Unique key to limit data results to your OEM,
    "start_date" – Start of activity to filter (mm/dd/yyyy),
    "end_date" – End of activity to filter (mm/dd/yyyy),
    "account_id" – Account ID from previous Add or List Accounts response,
    "user_id" – User object to filter on ,
    "reader_id" – Reader object to filter on

  • Response Attributes: "activity" – Array of Activity objects (see Appendix for objects)

Sample Request:

Code Block
languagejs
{ "id": "11272", 
"jsonrpc": "2.0", 
"method": com.vizpin.activity.list", 
"params": { 
"oem_key" : OEM_KEY, 
"start_date" : "06/01/2019", 
"end_date" : "06/30/2019", 
"account_id" : "a0G3300030aYQaF", 
"user_id" : "a0F6777030aYQaF" , 
"reader_id" : "" } 
}


Sample Response:

Code Block
languagejs
{ "status" : API_VIZPIN_SUCCESS, 
"result" : { 
"now" : 1437910464, 
"code" : API_VIZPIN_ACTIVITY_LIST_SUCCESS, 
"message" : " Successful listing of Activity", 
"activity" : [ACTIVITY_OBJECT_1, ACTIVITY_OBJECT_2…….] }, 
"jsonrpc" : "2.0", 
"id" : "11272" 
}


Remove User Per Account

This method removes associated Account, Credentials and Phone Access with the user

  • Method Name: com.vizpin.user.remove

  • Request Parameters: "userid" – Single User Id to remove
    "accountId" - Account associated to the user to be removed.

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.user.remove", 
"params":{ 
"oem_key":"d41d8cd98f00b204e9800998ecf8427e", 
"userid": "a0q56000000YW6PAAsW" 
"accountId": "a0q44000000YW6PQSsW" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_USER_ACCOUNT_REMOVE_SUCCESS, 
"message":"Successfully Removed User from Account.", 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Object Delete

This method deletes Account or Location or Reader and its association.

  • Method Name: com.vizpin.object.delete

  • Request Parameters:

    • "objectId" – Account Id or Location Id or Reader Id to be deleted.

    • objectname" - Object name to be deleted. Allowed values are "account" OR "location" OR "reader" ONLY.

  • Hierarchy of Object Deletion: Deleting a reader will delete all smartphone accesses and audit events. Deleting a location will delete ALL readers associated with it, including objects associated with the readers. Deleting account will delete all sites and readers associated with it, including all location and reader level objects as illustrated below.
    "reader"Smartphone AccessEvents"location""account"Credentials/Cards associated to user(s)

Sample Request:

Code Block
languagejs
{ 
"id":"6272", 
"Jsonrpc":"2.0", "!version" : "2", 
"method":com.vizpin.object.delete", 
"params":{ 
"oem_key":"d41d8cd98f00b204e9800998ecf8427e", 
"objectId": "account" 
"objectname": "a0q44000000YW6PQSsW" 
} 
}


Sample Response:

Code Block
languagejs
{ 
"status":API_VIZPIN_SUCCESS, 
"result":{ 
"now":1437910464, 
"code":API_VIZPIN_OBJECT_DELETE_SUCCESS , 
"message":"<objectname> successfully deleted.", 
}, 
"jsonrpc":"2.0", 
"id":"6272" 
}

Push API Calls

These methods will push an api request to OEM API endpoints to send json formatted objects that can be translated by OEMs into useful information.
Requirements:

  1. URL Endpoint that will handle post request

  2. JSON request handler

  3. JSON response with expected attributes

Push Audit Events

This call pushes audit events to OEM specified in Appendix 3 - Audit Events Code

  • HTTP Request URL: To be provided by OEM partner

  • HTTP Request Client Certification: (If required by OEM Partner for endpoint authentication) Unique per OEM, will be sent to OEM partners and will vary per sandbox.

  • HTTP Request Body Parameters:
    "activity_code" - event code,
    "audit_date" - GMT date and time of the audit event,
    "readerId" – Reader Id where event happened,
    "user_id" – User Id of the owner of the audit (if blank, event can be a reader event)
    "description" – readable date and time of the audit in reader location time zone,

  • Http Response Body Response Attributes:
    "status" – status code of the request.
    200 Status for SUCCESS
    4XX (where XX is an integer value) for ERROR and other status code
    "message" - description of the message. Message should not be empty If status is 4XX.

Sample JSON Request Body:

Code Block
languagejs
{ "description":"Jan 16 2020 11:04:03 AM AST", 
"user_id":"a0q63000002EuhzAAC", 
"readerId":"a0c63000002QIzEAAW", 
"audit_date":"2020-01-16 08:04:03", 
"activity_code":52 
}


Expected JSON Response:

Code Block
languagejs
{ "status" :200, 
"message" : "true" 
}


User Verification for Pre-registration

This notifies OEM partner that a pre-registered user was initially verified via VIZpin SDK. This feature is available for partners that have their own Mobile App access and are using VIZpinSDK.

  • HTTP Request URL: To be provided by OEM partner, user_id will be appended as part of URL string.
    https://oemurl/<user_id>

  • HTTP Request Client Certification: (If required by OEM Partner for endpoint authentication) Unique per OEM, will be sent to OEM partners and will vary per sandbox.

  • HTTP Request Body Parameters:
    NONE

  • Http Response Body Response Attributes:
    "status" – status code of the request.
    200 Status for SUCCESS
    4XX (where XX is an integer value) for ERROR and other status code
    "message" - description of the message. Message should not be empty If status is 4XX.

Sample OEM URL:


Expected JSON Response:

Code Block
languagejs
{ "status" :200, "message" : "true" 
}

Appendix 1: Status Codes and Error Codes

(These are preliminary values and are subject to change)

Success Codes:

  • Integer API_VIZPIN_UNKNOWN_ERROR = -1

  • Integer API_VIZPIN_ERROR = 0

  • Integer API_VIZPIN_SUCCESS = 1

Message Codes:

  • For Status = 1 :

    • Integer API_VIZPIN_AUTENTICATE_SUCCESS = 9;

    • Integer API_VIZPIN_TIME_SUCCESS = 30;

    • Integer API_VIZPIN_ACCOUNT_LIST_SUCCESS = 32;

    • Integer API_VIZPIN_ACCOUNT_ADD_SUCCESS = 34;

    • Integer API_VIZPIN_READER_LIST_SUCCESS = 36;

    • Integer API_VIZPIN_READER_ADD_SUCCESS = 38;

    • Integer API_VIZPIN_READER_EDIT_SUCCESS = 40;

    • Integer API_VIZPIN_USER_LIST_SUCCESS = 42;

    • Integer API_VIZPIN_ACTIVITY_LIST_SUCCESS = 43;

    • Integer API_VIZPIN_USER_FIND_SUCCESS = 44;

    • Integer API_VIZPIN_USER_ASSOCIATE_SUCCESS = 46;

    • Integer API_VIZPIN_VIZPIN_LIST_SUCCESS = 48;

    • Integer API_VIZPIN_VIZPIN_GRANT_SUCCESS = 50;

    • Integer API_VIZPIN_VIZPIN_REVOKE_SUCCESS = 52;

    • Integer API_VIZPIN_VIZPIN_ADD_SUCCESS = 54;

    • Integer API_VIZPIN_USER_ACCESS_SUCCESS = 62;

    • Integer API_VIZPIN_ACCOUNT_GET_SUCCESS = 64;

    • Integer API_VIZPIN_ACCOUNT_EDIT_SUCCESS = 93;

    • Integer API_VIZPIN_LOCATION_LIST_SUCCESS = 66;

    • Integer API_VIZPIN_LOCATION_GET_SUCCESS = 67;

    • Integer API_VIZPIN_LOCATION_ADD_SUCCESS = 68;

    • Integer API_VIZPIN_LOCATION_EDIT_SUCCESS = 69;

    • Integer API_VIZPIN_READER_GET_SUCCESS = 70;

    • Integer API_VIZPIN_USER_COUNT_SUCCESS = 71;

    • Integer API_VIZPIN_USER_GET_SUCCESS = 72;

    • Integer API_VIZPIN_USER_REGISTER_SUCCESS = 73;

    • Integer API_VIZPIN_USER_EDIT_SUCCESS = 74;

    • Integer API_VIZPIN_CREDENTIAL_GET_SUCCESS = 75;

    • Integer API_VIZPIN_CREDENTIAL_GENERATE_SUCCESS = 76;

    • Integer API_VIZPIN_USER_PREREGISTER_SUCCESS = 97;

    • Integer API_VIZPIN_USER_DELETE_SUCCESS = 100;

    • Integer API_VIZPIN_USER_ACCOUNT_REMOVE_SUCCESS = 102;

    • Integer API_VIZPIN_OBJECT_DELETE_SUCCESS = 105;

    • Integer API_VIZPIN_USER_GRANT_SUCCESS = 108;

    • Integer API_VIZPIN_ROLE_LIST_SUCCESS = 110;

    • Integer API_VIZPIN_ROLE_ADD_SUCCESS = 113;

    • Integer API_VIZPIN_ROLE_EDIT_SUCCESS = 115

  • For Status = 0 :

    • Integer API_VIZPIN_BAD_SESSION = 20;

    • Integer API_VIZPIN_VERIFY_PENDING = 24;

    • Integer API_VIZPIN_BAD_USERNAME = 65;

    • Integer API_VIZPIN_BAD_PASSWORD = 4;

    • Integer API_VIZPIN_ACCOUNT_ADD_ERROR = 35;

    • Integer API_VIZPIN_TIME_ERROR = 31;

    • Integer API_VIZPIN_ACCOUNT_LIST_ERROR = 33;

    • Integer API_VIZPIN_READER_LIST_ERROR = 37;

    • Integer API_VIZPIN_READER_ADD_ERROR = 39;

    • Integer API_VIZPIN_READER_EDIT_ERROR = 41;

    • Integer API_VIZPIN_USER_LIST_ERROR = 43;

    • Integer API_VIZPIN_USER_FIND_ERROR = 45;

    • Integer API_VIZPIN_USER_ASSOCIATE_ERROR = 47;

    • Integer API_VIZPIN_VIZPIN_LIST_ERROR = 49;

    • Integer API_VIZPIN_VIZPIN_GRANT_ERROR = 51;

    • Integer API_VIZPIN_VIZPIN_REVOKE_ERROR = 53;

    • Integer API_VIZPIN_VIZPIN_ADD_ERROR = 55;

    • Integer API_VIZPIN_ACTIVITY_LIST_ERROR = 57;

    • Integer API_VIZPIN_BAD_OEM_KEY = 59;

    • Integer API_VIZPIN_USER_LOGIN_ERROR = 61;

    • Integer API_VIZPIN_USER_ACCESS_ERROR = 63;

    • Integer API_VIZPIN_LOCATION_LIST_ERROR = 81;

    • Integer API_VIZPIN_LOCATION_GET_ERROR = 82;

    • Integer API_VIZPIN_LOCATION_ADD_ERROR = 83;

    • Integer API_VIZPIN_LOCATION_EDIT_ERROR = 84;

    • Integer API_VIZPIN_USER_COUNT_ERROR = 86;

    • Integer API_VIZPIN_USER_GET_ERROR = 87;

    • Integer API_VIZPIN_USER_REGISTER_ERROR = 88;

    • Integer API_VIZPIN_USER_EDIT_ERROR = 89;

    • Integer API_VIZPIN_CREDENTIAL_GET_ERROR = 90;

    • Integer API_VIZPIN_CREDENTIAL_GENERATE_ERROR = 91;

    • Integer API_VIZPIN_BAD_APP_VERSION = 95;

    • Integer API_VIZPIN_USER_PREREGISTER_ERROR = 96;

    • Integer API_VIZPIN_ACCOUNT_EDIT_ERROR = 98;

    • Integer API_VIZPIN_USER_DELETE_ERROR = 101;

    • Integer API_VIZPIN_USER_ACCOUNT_REMOVE_ERROR = 103;

    • Integer API_VIZPIN_OBJECT_DELETE_ERROR = 104;

    • Integer API_VIZPIN_SITE_DELETE_ERROR = 106;

    • Integer API_VIZPIN_READER_DELETE_ERROR =107;

    • Integer API_VIZPIN_USER_GRANT_ERROR = 109;

    • Integer API_VIZPIN_ROLE_LIST_ERROR =111;

    • Integer API_VIZPIN_ROLE_ADD_ERROR = 112;

    • Integer API_VIZPIN_ROLE_EDIT_ERROR = 114;

Appendix 2: Object Definitions

All properties will always be returned. Optional ones are not required in most API requests.
(These are preliminary values and are subject to change)

Account Object

Name

Type

Description

Remarks

id

string

internal identifier for this Account

Required
Value set when adding an account.
"null"/empty is for object is for creation

name

string

Account's Primary Name

Required
Unique Name

phone

string

phone number of contact person

Required

street

string

address street

Required

city

string

address city for this account

Required

state

string

address state for this account

Required
See Appendix for valid value of US State

zipcode

string

address zipcode for this account

Required

country

string

address country for this account(Alpha-3 country ISO codes as described in the ISO 3166 international standard)

Required

deactivated

string

Status of the account

Values:
"true" = deactivated,
"false" = active

type

string

Account type

Required for adding reader
Fixed value per OEM Partners as assigned by VIZpin

Valid Values allowed for Partners (non-OEM) : "VIZpin vPROX", "VIZpin PLUS", "VIZpin Lite"

Not editable(Not available in edit)

Location Object

Name

Type

Description

Remarks

accountid

string

Id of the Parent Account

Required
Value from Parent Account.
Always set this field with value of Account id associated to this location

id

string

internal identifier for this Location

Required
Value set when adding a location.
"null"/empty is for object is for creation

name

string

Location's name

Required
Unique Name

locationcode

string

code generated for this location

Value set when adding a location.
Read-only
Unique, Case Sensitive
Required but not editable

timezone

string

timezone of the location

Required for adding reader.
See Appendix 3 Timezone values for valid input
Not editable/Not required for editing

locationtype

string

Type of the location of vProx or PLUS

Required for adding reader.

Valid Values for OEM Partners : "VIZpin vPROX", "VIZpin PLUS"
Default: "VIZpin PLUS"


Valid Values for non-OEM Partners : "" 


Not editable/Not required for editing

country

string

country

Required

phone

string

phone information of the contact person

Not Required

state

string

State of the location

Not Required
See Appendix for valid value of US State

address1

string

address1 of the location

Not Required

address2

string

address2 location

Not Required

zipcode

string

Zip or postal code

Not Required

city

string

City of the location

Not Required


Reader Object

Name

Type

Description

Remarks

id

string

identifier for this Reader

Required
Value set when adding a reader
"null"/empty is for object is for creation

locationid

string

Reader's Location reference identifier (relates to Location)

Required in Adding Reader
Value from Location.id
Always set this field with value of Location id associated to this reader

Validation: Editable only if Reader has NO existing VIZpins that are confirmed or scheduled

name

string

display name for this Reader

Required

serial

string

serial number for this Reader

Required

version

string

firmware version for this Reader

Read only value
Value set when an audit from reader is sent to server

reader_collateral

string

reader settings supplied by the OEM.

32 hex digits representing fixed length of 16 unsigned bytes that may be structured by the OEM to suit any purpose needed.  This byte array will be transmitted to the specified reader and supplied to the reader firmware in the return data from an unlock request via SDK.

Optional. If this is excluded from the object in any add/edit reader api calls, value  saved is an empty string.

readersettings

Reader Settings

Reader Settings associated with this Reader

Only 1 Reader Settings object per Reader

batterylifestatus


Battery Status based on battery life of reader

Read only

  • If batterylife >= 776 : FullPower

  • If batterylife between 694  and 775 : MidPower 

  • If batterylife<  694 : LowPower

  • Default Value: Powered

batterylife


Battery Life of the reader 

Read Only

Numeric


ReaderSettings Object

Name

Type

Description

Remarks

id

string

Identifier for the reader setting

Required
Value set when adding a reader

readerid

string

reader reference identification
(relates to reader)

Required
Values relates to Reader.Id
Always set this field with value of Reader id associated to this object

read_range

string

read range

Required
Valid Values: "Short", "Normal"," Unlimited"
Default Value: "Unlimited"

relay_mode

string

relay mode

Valid Values: "Normally Open", "Normally Closed"
Default Value : "Normally Open"

Remove for smartlock reader.

powermode

string

For Smartlock type readers

If reader is a smartlock, powermode is required

Valid Values:  FastUnlock, Standard or PowerSaver

relay_time

string

relay time in seconds

Default Value : "5"

first_in_mode

string

Enable or disable first-in mode of the reader

Input options: "off", "on"
Default Value: "off"

first_in_schedule

Schedule

If first_in_mode is "on":
schedule.type is always "firstin"
Schedule element must be specified in a weekly basis only, multiple time spans per day is not allowed.

Ignored for first_in_mode = "off" else
schedule.type = "firstin"


User Object

Name

Type

Description

Remarks

id

string

internal identifier for this User

Required
Value set when adding a user.
"null"/empty is for object is for creation

first_name

string

first name for this User

Required

last_name

string

last name for this User

Required

password

string

password for this User

Masked value on response.
Not Editable via API Call
Can be modified by user via ResetPassword in SDK
Not editable via API method
Value is for Register User Method only, set as null for Edit User
See Appendix for Policies

emailaddress

string

Email Address of the User

Not a Required Field

phone

string

mobile phone number for this User, including plus (plus) and country code,

Required
Unique
Cannot be modified once added


country

string

3 letter country code of the phone for this User (Alpha-3 country ISO

Required
3 letter country code of the phone for this User (Alpha-3 country ISO as described in the ISO 3166 international standard)

state

string

State registered by user

Not a Required Field
See Appendix for valid value of US State

address1

string

address of the user

Not a required field

address2

string

address of the user

Not a required field

city

string

City address of the user

Not a required field

phoneconfirmation

string

Specify if user has been verified via phone confirmation

Required
Generated if user needs verification via SMS
Read Only
Values: "X"if user is already verified and " [generated 6 digits]" if user needs verification
Default: "x"

sfUserID

string

External User Id


PreRegistered User Object

Name

Type

Description

Remarks

id

string

internal identifier for this User

Required
Value set when adding a user.
"null"/empty is for object is for creation

first_name

string

first name for this User

Required

last_name

string

last name for this User

Required

emailaddress

string

Email Address of the User

Optional

phone

string

mobile phone number for this User, including plus (plus) and country code,

Required
Unique
Cannot be modified once added


country

string

3 letter country code of the phone for this User (Alpha-3 country ISO

Required
3 letter country code of the phone for this User (Alpha-3 country ISO as described in the ISO 3166 international standard)

state

string

State registered by user

Optional
See Appendix for valid value of US State

address1

string

address of the user

Not a required field

address2

string

address of the user

Not a required field

city

string

City address of the user

Not a required field


Credential Object

Name

Type

Description

Remarks

id

string

identifier for the credential

Value set when adding a credential.
"null"/empty is for object is for creation

userid

string

User reference identification
(relates to user)

Read-only
Relates to user.id
Referenced when credential is created.

accountId

string

Id of the Parent Account

Required
Value from Parent Account.
Always set this field with value of Account id associated to this location

cardnumber

string

Card number of user

Read-only
Unique per Partner
Auto-incremental based on specified range

cardnumberformatted

string

Formatted Card number

Read-only
Unique per partner
Format based on client specified requirement

Role Object

Name

Type

Description

Remarks

id

string

identifier for this Role

Value set when adding a Role.

name

string

Role name

Required

siteid

string

Role's Location reference identifier (relates to Location)

Required
Value from Location.id

VIZpin Object

Name

Type

Description

Remarks

id

string

identifier for this VIZpin

Value set when adding a user.
"null"/empty is for object is for creation

readerid

string

reader reference identification
(relates to reader)

Required
Values relates to Reader.Id
Always set this field with value of Reader id associated to this object

userid

string

User reference identification
(relates to user)

Required
Relates to user.id

start_date

string

access start date for this VIZpin (Reader Timezone)

Startdate of VIZpin Schedule

FORMAT: yyyy-mm-dd OR yyyy-mm-dd 00:00:00

Time part is defaulted to 00:00:00

stop_date

string

access stop date and time for this VIZpin (Reader Timezone)

EndDate of the VIZpin Schedule

FORMAT: yyyy-mm-dd HH:mm:01 (local time of the reader)

Seconds part is defaulted to 01.

schedule

Schedule

object describing the weekly schedule for this VIZpin

Required
Valid Values: "custom", "24x7"

status

string

Status of vizpin

Read-Only
Generated when VIZpin schedule is updated via back end process
Values:
"Confirmed" - active VIZpin as of current date/time
"Scheduled" - VIZpin is still scheduled current date/time
"Expired" - VIZpin is already expired
"Revoke Complete" - VIZpin is revoked
"Blacklisted" - VIZpin is completely blacklisted and will not be used
"Superceded"

cardnumber

string

The Card Number for VProx Credential

Read-Only
Optional
For VProx Location Type Only
This is the unique Card Number per user and per Account.
CardNumber from Credential Object.


Schedule Object (local time of the reader)

Name

Type

Description

Remarks

id

string

Internal identifier for this schedule

Value set when schedule is created.
Referenced by VIZpin.schedule
"null"/empty is for object is for creation

type

string

Schedule Type

Required
Valid Values: "custom", "firstin", "24x7", "multiple"

scheduleelement

Schedule Element

Arraylist of Schedule Elements associated with this schedule

If type = "firstin", schedule element must be specified in a weekly basis only, custom time span per day is not allowed. Maximum of 1 time span per day

If type = "24x7", daily schedule elements will be ignored.

If type = "custom, custom time span per day is allowed. Maximum of 1 time span per day.

If type = "multiple, multiple time spans per day is allowed. Maximum of 5 time spans


ScheduleElement Object - FOR FIRSTIN, 24x7 and CUSTOM SCHEDULE local time of the reader)

Name

Type

Description

Remarks

id

string

Internal identifier for this schedule element

Value set when schedule element is created
"null"/empty is for object is for creation

scheduleid

string

schedule reference identification
Relates to Schedule Object

Read-only

sunday_begin

string

daily access start for Sunday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

sunday_end

string

daily access stop for Sunday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

monday_begin

string

daily access start for Monday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

monday_end

string

daily access stop for Monday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

tuesday_begin

string

daily access start for Tuesday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

tuesday_end

string

daily access stop for Tuesday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

wednesday_begin

string

daily access start for Wednesday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

wednesday_end

string

daily access stop for Wednesday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

thursday_begin

string

daily access start for Thursday,

time of the reader in format hh:mm AM/PM
Ignored for 24x7

thursday_end

string

daily access stop for Thursday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

friday_begin

string

daily access start for Friday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

friday_end

string

daily access stop for Friday,

time of the reader in format hh:mm AM/PM
Ignored for 24x7

saturday_begin

string

daily access start for Saturday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

saturday_end

string

daily access stop for Saturday

time of the reader in format hh:mm AM/PM
Ignored for 24x7

ScheduleElement Object - FOR MULTIPLE SCHEDULE (local time of the reader)

*Multiple Schedule per day is activated per Partner license (please coordinate with VIZpin technical support is this feature is needed)

Name

Type

Description

Remarks

id

string

Internal identifier for this schedule element

Value set when schedule element is created
"null"/empty is for object is for creation

includedates

object

Relates to IncludeDates Object

Array of includedates object

Optional

excludedates

string

Relates to ExcludeDates Object

Array of excludedates object

Optional

weekdays

string

Relates to WeekDays Object

Array of includedates object

Required

IncludeDates Object - FOR MULTIPLE SCHEDULE (local time of the reader)

Name

Type

Description

Remarks

date

string

start time of the schedule 

Date of the Include date (yyyy-mm-dd)

recurring

string

Identifies if the Include Date is recurring or not

Values: "true" or "false"

If "true" : year will not be considered in schedule checking when processing keys

time


Relates to Time Object

List of time objects (Minimum of  1, Maximum of 5 objects)

ExcludeDates Object - FOR MULTIPLE SCHEDULE (local time of the reader)

Name

Type

Description

Remarks

recurring

Array of String

Identifies if the Exclude Dates is/are recurring 

List of Dates in yyyy-mm-dd format

Year will NOT be considered in schedule checking when processing keys

nonrecurring

Array of String

Identifies if the Exclude Dates is/are nonrecurring 

Year will be considered in schedule checking when processing keys

Weekdays Object - FOR MULTIPLE SCHEDULE (local time of the reader)

Name

Type

Description

Remarks

"weekname"


string

weekday representation of the schedule:

"monday" or "tuesday"  or "wednesday"  or "thursday"  or "friday"  or "saturday" or "sunday"  

change "weekname" to one of these values can be:

"monday" or "tuesday"  or "wednesday"  or "thursday"  or "friday"  or "saturday" or "sunday"  

time


Relates to time Object

List of time objects (Minimum of  1, Maximum of 5 objects)

Time Object - FOR MULTIPLE SCHEDULE (local time of the reader)

Name

Type

Description

Remarks

begin

string

start time of the schedule 

time of the reader in format hh:mm AM/PM (Reader Timezone)

end

string

end time of the schedule 

time of the reader in format hh:mm AM/PM (Reader Timezone)


Activity Object

Name

Type

Description

Remarks

audit_id

string

id for this Activity

Read-only

user_id

string

User id of this Activity

Read-only

first_name

string

first name of the user

Read-only

last_name

string

last name of the user

Read-only

phone

string

phone number of the user

Read-only

reader_name

string

reader display name for this Activity

Read-only

audit_date

string

date/time string when this Activity occurred

Read-only

description

string

description of the event for this Activity

Read-only

readerId

string

Reader of the specific Audit

Read-only

activity_code

String

Event Code of the Activity

See Appendix 5 for list of Unlock Activities


Appendix 3: Request/Response Valid Values

(These are preliminary values and are subject to change)

Timezone values

Africa/Algiers

Asia/Bangkok

Atlantic/Bermuda

Pacific/Enderbury

Africa/Cairo

Asia/Beirut

Atlantic/Cape_Verde

Pacific/Fiji

Africa/Casablanca

Asia/Colombo

Atlantic/South_Georgia

Pacific/Gambier

Africa/Johannesburg

Asia/Dhaka

Australia/Adelaide

Pacific/Guadalcanal

Africa/Nairobi

Asia/Dubai

Australia/Brisbane

Pacific/Honolulu

America/Adak

Asia/Ho_Chi_Minh

Australia/Darwin

Pacific/Kiritimati

America/Anchorage

Asia/Hong_Kong

Australia/Lord_Howe

Pacific/Marquesas

America/Bogota

Asia/Jakarta

Australia/Perth

Pacific/Niue

America/Buenos_Aires

Asia/Jerusalem

Australia/Sydney

Pacific/Norfolk

America/Caracas

Asia/Kabul

Europe/Amsterdam

Pacific/Pago_Pago

America/Chicago

Asia/Kamchatka

Europe/Athens

Pacific/Pitcairn

America/Denver

Asia/Karachi

Europe/Berlin

Pacific/Tongatapu

America/El_Salvador

Asia/Katmandu

Europe/Brussels


America/Halifax

Asia/Kolkata

Europe/Bucharest


America/Indiana/Indianapolis

Asia/Kuala_Lumpur

Europe/Dublin


America/Lima

Asia/Kuwait

Europe/Helsinki


America/Los_Angeles

Asia/Manila

Europe/Istanbul


America/Mazatlan

Asia/Rangoon

Europe/Lisbon


America/Mexico_City

Asia/Riyadh

Europe/London


America/New_York

Asia/Seoul

Europe/Minsk


America/Panama

Asia/Shanghai

Europe/Moscow


America/Phoenix

Asia/Singapore

Europe/Paris


America/Puerto_Rico

Asia/Taipei

Europe/Prague


America/Santiago

Asia/Tashkent

Europe/Rome


America/Sao_Paulo

Asia/Tbilisi

GMT


America/Scoresbysund

Asia/Tehran

Pacific/Auckland


America/St_Johns

Asia/Tokyo

Pacific/Chatham


America/Tijuana

Asia/Yekaterinburg



Asia/Baghdad

Asia/Yerevan



Asia/Baku

Atlantic/Azores



US States values

States

Values

States

Values

Alabama

AL

Montana

MT

Alaska

AK

Nebraska

NE

American Samoa

AS

Nevada

NV

Arizona

AZ

New Hampshire

NH

Arkansas

AR

New Jersey

NJ

California

CA

New Mexico

NM

Colorado

CO

New York

NY

Connecticut

CT

North Carolina

NC

Delaware

DE

North Dakota

ND

Dist. of Columbia

DC

Northern Marianas

MP

Florida

FL

Ohio

OH

Georgia

GA

Oklahoma

OK

Guam

GU

Oregon

OR

Hawaii

HI

Palau

PW

Idaho

ID

Pennsylvania

PA

Illinois

IL

Puerto Rico

PR

Indiana

IN

Rhode Island

RI

Iowa

IA

South Carolina

SC

Kansas

KS

South Dakota

SD

Kentucky

KY

Tennessee

TN

Louisiana

LA

Texas

TX

Maine

ME

Utah

UT

Maryland

MD

Vermont

VT

Marshall Islands

MH

Virginia

VA

Massachusetts

MA

Virgin Islands

VI

Michigan

MI

Washington

WA

Micronesia

FM

West Virginia

WV

Minnesota

MN

Wisconsin

WI

Mississippi

MS

Wyoming

WY

Missouri

MO




Country Code Values

User A3 format in the list from {+}https://www.worldatlas.com/aatlas/ctycodes.htm+

COUNTRY

A3 (UN)

COUNTRY

A3 (UN)

COUNTRY

A3 (UN)

Afghanistan

AFG

Gibraltar

GIB

Pakistan

PAK

Albania

ALB

Greece

GRC

Palau

PLW

Algeria

DZA

Greenland

GRL

Palestine, State of

PSE

American Samoa

ASM

Grenada

GRD

Panama

PAN

Andorra

AND

Guadeloupe

GLP

Papua New Guinea

PNG

Angola

AGO

Guam

GUM

Paraguay

PRY

Anguilla

AIA

Guatemala

GTM

Peru

PER

Antarctica

ATA

Guernsey

GGY

Philippines

PHL

Antigua and Barbuda

ATG

Guinea

GIN

Pitcairn

PCN

Argentina

ARG

Guinea-Bissau

GNB

Poland

POL

Armenia

ARM

Guyana

GUY

Portugal

PRT

Aruba

ABW

Haiti

HTI

Puerto Rico

PRI

Australia

AUS

Heard Island and McDonald Islands

HMD

Qatar

QAT

Austria

AUT

Holy See (Vatican City State)

VAT

Romania

ROU

Azerbaijan

AZE

Honduras

HND

Russian Federation

RUS

Bahamas

BHS

Hong Kong

HKG

Rwanda

RWA

Bahrain

BHR

Hungary

HUN

Reunion

REU

Bangladesh

BGD

Iceland

ISL

Saint Barthelemy

BLM

Barbados

BRB

India

IND

Saint Helena

SHN

Belarus

BLR

Indonesia

IDN

Saint Kitts and Nevis

KNA

Belgium

BEL

Iran, Islamic Republic of

IRN

Saint Lucia

LCA

Belize

BLZ

Iraq

IRQ

Saint Martin (French part)

MAF

Benin

BEN

Ireland

IRL

Saint Pierre and Miquelon

SPM

Bermuda

BMU

Isle of Man

IMN

Saint Vincent and the Grenadines

VCT

Bhutan

BTN

Israel

ISR

Samoa

WSM

Bolivia

BOL

Italy

ITA

San Marino

SMR

Bonaire

BES

Jamaica

JAM

Sao Tome and Principe

STP

Bosnia and Herzegovina

BIH

Japan

JPN

Saudi Arabia

SAU

Botswana

BWA

Jersey

JEY

Senegal

SEN

Bouvet Island

BVT

Jordan

JOR

Serbia

SRB

Brazil

BRA

Kazakhstan

KAZ

Seychelles

SYC

British Indian Ocean Territory

IOT

Kenya

KEN

Sierra Leone

SLE

Brunei Darussalam

BRN

Kiribati

KIR

Singapore

SGP

Bulgaria

BGR

Korea, Democratic People's Republic of

PRK

Sint Maarten (Dutch part)

SXM

Burkina Faso

BFA

Korea, Republic of

KOR

Slovakia

SVK

Burundi

BDI

Kuwait

KWT

Slovenia

SVN

Cambodia

KHM

Kyrgyzstan

KGZ

Solomon Islands

SLB

Cameroon

CMR

Lao People's Democratic Republic

LAO

Somalia

SOM

Canada

CAN

Latvia

LVA

South Africa

ZAF

Cape Verde

CPV

Lebanon

LBN

South Georgia and the South Sandwich Islands

SGS

Cayman Islands

CYM

Lesotho

LSO

South Sudan

SSD

Central African Republic

CAF

Liberia

LBR

Spain

ESP

Chad

TCD

Libya

LBY

Sri Lanka

LKA

Chile

CHL

Liechtenstein

LIE

Sudan

SDN

China

CHN

Lithuania

LTU

Suriname

SUR

Christmas Island

CXR

Luxembourg

LUX

Svalbard and Jan Mayen

SJM

Cocos (Keeling) Islands

CCK

Macao

MAC

Swaziland

SWZ

Colombia

COL

Macedonia, the Former Yugoslav Republic of

MKD

Sweden

SWE

Comoros

COM

Madagascar

MDG

Switzerland

CHE

Congo

COG

Malawi

MWI

Syrian Arab Republic

SYR

Democratic Republic of the Congo

COD

Malaysia

MYS

Taiwan

TWN

Cook Islands

COK

Maldives

MDV

Tajikistan

TJK

Costa Rica

CRI

Mali

MLI

United Republic of Tanzania

TZA

Croatia

HRV

Malta

MLT

Thailand

THA

Cuba

CUB

Marshall Islands

MHL

Timor-Leste

TLS

Curacao

CUW

Martinique

MTQ

Togo

TGO

Cyprus

CYP

Mauritania

MRT

Tokelau

TKL

Czech Republic

CZE

Mauritius

MUS

Tonga

TON

Cote d'Ivoire

CIV

Mayotte

MYT

Trinidad and Tobago

TTO

Denmark

DNK

Mexico

MEX

Tunisia

TUN

Djibouti

DJI

Micronesia, Federated States of

FSM

Turkey

TUR

Dominica

DMA

Moldova, Republic of

MDA

Turkmenistan

TKM

Dominican Republic

DOM

Monaco

MCO

Turks and Caicos Islands

TCA

Ecuador

ECU

Mongolia

MNG

Tuvalu

TUV

Egypt

EGY

Montenegro

MNE

Uganda

UGA

El Salvador

SLV

Montserrat

MSR

Ukraine

UKR

Equatorial Guinea

GNQ

Morocco

MAR

United Arab Emirates

ARE

Eritrea

ERI

Mozambique

MOZ

United Kingdom

GBR

Estonia

EST

Myanmar

MMR

United States

USA

Ethiopia

ETH

Namibia

NAM

United States Minor Outlying Islands

UMI

Falkland Islands (Malvinas)

FLK

Nauru

NRU

Uruguay

URY

Faroe Islands

FRO

Nepal

NPL

Uzbekistan

UZB

Fiji

FJI

Netherlands

NLD

Vanuatu

VUT

Finland

FIN

New Caledonia

NCL

Venezuela

VEN

France

FRA

New Zealand

NZL

Viet Nam

VNM

French Guiana

GUF

Nicaragua

NIC

British Virgin Islands

VGB

French Polynesia

PYF

Niger

NER

US Virgin Islands

VIR

French Southern Territories

ATF

Nigeria

NGA

Wallis and Futuna

WLF

Gabon

GAB

Niue

NIU

Western Sahara

ESH

Gambia

GMB

Norfolk Island

NFK

Yemen

YEM

Georgia

GEO

Northern Mariana Islands

MNP

Zambia

ZMB

Germany

DEU

Norway

NOR

Zimbabwe

ZWE

Ghana

GHA

Oman

OMN




Appendix 4: Policies


Password

  1. User passwords expire in 90 days.

  2. Enforce password history : 3 passwords remembered

  3. Minimum password length : 8

  4. Password complexity requirement: Must Include alpha and numeric characters

  5. Maximum invalid login attempts : 3

Appendix 5: Activity Event Code


Code

Event code 

Name

Name of the event

Is Reader Event 

If YES - audit is for a reader event such as reader setup, configuration installation, reader activity

If NO - event is an audit message with phone or server activity 


Code

Name

Is Reader Event


Code

Name

Is Reader Event

85

Setup Error

YES


73

Alarm was detected as disarmed

NO

96

DMR connection Info

NO


70

Door was detected as Opened

NO

94

Unknown code 94

NO


50

Add new low audit events here 10

NO

97

DMR Unknown Device R/W timeout

NO


78

Door Close request sent

NO

64

Device not authorized

NO


31

New device added

NO

60

BLE R/W Activty Timeout

NO


80

Authorized phone seen within range

NO

52

A phone has triggered an unlock

NO


43

Add new low audit events here 3

NO

74

Pin Request Error

NO


54

A phone has arming message an alarm

NO

72

Alarm was detected as armed

NO


30

Low Audit

NO

53

A phone has triggered an open message

NO


81

Wiegand Authorized

NO

61

DMR_WIEGAND_IN_FAULT

NO


41

Add new low audit events here

NO

32

Paired phone deleted

NO


33

All phones deleted

NO

62

DMR_BT_ERROR

NO


37

First In Unlock Start

NO

56

The door was propped open

NO


34

Tamper switch has been opened

NO

66

Multi Output Unlock

NO


45

Add new low audit events here 5

NO

55

A phone has disarming message an alarm

NO


71

Door was detected as Closed

NO

59

Rejected Un-lock

NO


57

Setting Changed

NO

77

Door Lock

NO


91

RTC Recovered TIme

YES

75

Day/Night - Night/Day Mode change

NO


76

Admin Mode Entered

YES

88

RTC set to default time

YES


92

Time set from phone

YES

47

Add new low audit events here 7

NO


83

User List Valid

YES

67

Aborted Un-lock, no arming input

NO


90

Power Fail

YES

63

Time on phone and reader don't match

NO


40

Settings reset

YES

86

Bad Un-lock Msg Preamble

NO


87

Panic

YES

35

Tamper switch has been closed

NO


89

Power fail recovery

YES

58

Code was sent to the external panel

NO


36

Unit has been powered up

YES

68

Request to Exit

NO


84

User List Error

YES

38

First In Unlock End

NO


65

LINK Update

YES

46

Add new low audit events here 6

NO


39

Hardware reset

YES

82

Wiegand Unauthorized

NO


101

Door forced Open

*

79

Admin Error

NO


103

Door open too long

*

48

Add new low audit events here 8

NO


104

Door left open

*

51

Add new low audit events here 11 END

NO


106

Door forced open

*

116

DOOR_LOCK_STATUS_FAILURE

*


108

Door open to long

*

117

DOOR_LOCK_STATUS_RESTORED

*


109

Door left open restore

*

124

IOSMART_POWER_RESTORED

*


110

Door Closed

*

125

IOSMART_POWER_LOW

*


111

Exit Request

*

118

IOSMART_SOFT_RESET

*


121

Schedule Unlock

*

119

IOSMART_HARD_RESET

*


122

Schedule Relock

*

132

IOSMART_FW_UPDATE_SUCCESSFUL

*


130

Tamper Alarm

*

136

IOSMART_FW_UPDATE_FAILED

*


131

Tamper Restored

*

137

IOSMART_FW_UPDATE_CANCELLED

*



*Reserved Events to an OEM