VIZpin API Specification v4.3

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

1 Overview
2 Assumptions
3 VIZpin OEM API URLs
4 VIZpin OEM API Version
5 VIZpin OEM API Authentication
6 High-level Object Relationship Diagram
- 6.1 Account
- 6.2 Card Number
- 6.3 VIZpin/PLUS
- 6.4 Entity Relationship Diagram
7 VIZpin OEM API Methods
- 7.1 API METHODS
  - 7.1.1 Authenticate
  - 7.1.2 Get Time
  - 7.1.3 List Accounts
  - 7.1.4 Get Account
  - 7.1.5 Add Account
  - 7.1.6 Edit Account
  - 7.1.7 List Locations By Account
  - 7.1.8 Get Location
  - 7.1.9 Add Location
  - 7.1.10 Edit Location
  - 7.1.11 List Readers
  - 7.1.12 Get Reader
  - 7.1.13 Add Reader
  - 7.1.14 Edit Reader
  - 7.1.15 Count Users
  - 7.1.16 List Users
  - 7.1.17 Find User
  - 7.1.18 Get User
  - 7.1.19 PreRegister User
  - 7.1.20 Register User
  - 7.1.21 Edit User
  - 7.1.22 Delete User
  - 7.1.23 Associate User
  - 7.1.24 Get User Credentials
  - 7.1.25 Generate User Credential
  - 7.1.26 List Users the Need Access
  - 7.1.27 Grant Phone Role to User
  - 7.1.28 List Roles
  - 7.1.29 Add Role
  - 7.1.30 Edit Role
  - 7.1.31 List VIZpins
  - 7.1.32 Grant VIZpin (DEPRECATED - user GRANT PHONE ROLE instead)
    - 7.1.32.1 Grant Custom Schedule
    - 7.1.32.2 Multiple Schedule
  - 7.1.33 Revoke VIZpin
  - 7.1.34 List Activity
  - 7.1.35 Remove User Per Account
  - 7.1.36 Object Delete
- 7.2 Push API Calls
  - 7.2.1 Push Audit Events
  - 7.2.2 User Verification for Pre-registration
8 Appendix 1: Status Codes and Error Codes
9 Appendix 2: Object Definitions
10 Appendix 3: Request/Response Valid Values
- 10.1 Timezone values
- 10.2 US States values
- 10.3 Country Code Values
11 Appendix 4: Policies
- 11.1 Password
12 Appendix 5: Activity Event Code

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:

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):

{ 
"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:

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:

{ 
"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:

{ 
"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:

{ 
"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:

{ 
"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:

{ 
"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:

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:

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

Sample Response:

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

Sample Code:

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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{
"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:

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

Sample Response:

{ 
"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:

{ 
"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:

{ 
"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:

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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

{ 
"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:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

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

Sample Response:

{ 
"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:

{ 
  "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"
  } 
}

VIZpin API Documentation

Overview

Assumptions

VIZpin OEM API URLs

VIZpin OEM API Version

VIZpin OEM API Authentication

High-level Object Relationship Diagram

Account

Card Number

VIZpin/PLUS

Entity Relationship Diagram

VIZpin OEM API Methods

API METHODS

Authenticate

Get Time

List Accounts

Get Account

Add Account

Edit Account

List Locations By Account

Get Location

Add Location

Edit Location

List Readers

Get Reader

Add Reader

Edit Reader

Count Users

List Users

Find User

Get User

PreRegister User

Register User

Edit User

Delete User

Associate User

Get User Credentials

Generate User Credential

List Users the Need Access

Grant Phone Role to User