Open

VIZpin API Specification v4.3

 

 

 REVISION HISTORY

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:

Parameters:

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

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

And you should get a response similar to this:

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

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:

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

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

Sample Response:

Sample Code:

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:

Sample Response:

Sample Code:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

Sample Code:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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

Sample Response:

Sample Request (Custom Schedule):

Grant Custom Schedule

Sample Request (Multiple Schedule):

Multiple Schedule

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Sample Response:

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:

Expected JSON Response:

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:

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;