API User Guide
- Vinodhraj DP
- Steven Lewis
- Anand Rajaraman
About This Guide
This guide describes how to configure and use the PRIMIS API software.
Topics in this guide are intended for security system integrators and security administrators responsible for setting up IP-based physical access security control systems.
Additional Documentation
To find documentation available for all products, go to https://www.identiv.com.
Getting Started
Introduction
The Primis API provides the RESTful Web Services for the Primis Access Control System. The Primis API calls described in this document required HTTP BASIC authentication. The same login credentials that can access the Primis software are used for API authentication. You can add/remove logins by navigating to the “Admin Users” section of the Primis software. The default user that comes with the system is:
Username: primis
Password: identiv
The Primis API Web Services can be configured to support https. Please contact support for additional details.
Users
This chapter describes how to create/retrieve/update/delete Users through the PRIMIS API software.
user elements:
Element Name | Type | Description | Comments | |
|---|---|---|---|---|
id | string max 200 characters | Unique identifier for a User | Optional; On POST, server generates an ID | |
first_name | string max 50 characters | First name of the User | Optional | |
last_name | string max 50 characters | Last name of the User | Required | |
access_start_date | date(yyyymmdd) | Date for when the User will be active (enabled) | Optional; Uses the API server’s current date if empty | |
access_end_date | date(yyyymmdd) | Date for when the User will be inactive (disabled) | Optional | |
pin | integer | The User’s PIN | Optional; This PIN is used with Wiegand Keypads and should not be confused with a PIV card’s PIN. | |
string max 100 characters | Email address of the User | Optional | ||
phone | string max 50 characters | Phone number of the User | Optional | |
created_at | datetime | Create timestamp | This element is searchable by using query parameter created_since. for example: created_since=20170615130130 will return all users created after 2017-06-15 13:01:30 | |
updated_at | datetime | Update timestamp | This element is searchable by using query parameter updated_since. for example: updated_since=20170615130130 will return all users updated after 2017-06-15 13:01:30 | |
disabled | boolean(true/false) | Indicates whether a User is disabled | Optional; User is enabled if empty (false). | |
credential | child element | Credential of the User | Optional; only supported in POST and GET method. Refer to | |
|
|
| section 0 CHAPTER 3 Credentials for details. | |
cards | child element | The Card(s) belong to the User | Optional; only supported in POST and GET method | |
| card_number | string max 100 characters | Unique identifier for a Card | Required |
access_group | child element | The Access Group(s) that the User belongs to | Optional; only supported in POST and GET method | |
| id | string maximum 36 characters | Unique identifier for an Access Group | Required |
name | string max 200 characters | The name of the Access Group | Required | |
site_id | string maximum 36 characters | The ID of the Site that the Access Group belongs to | Optional; on POST, default to 1 if it is not set | |
custom_field_items | child element |
| Not used; Only supported in GET method | |
image | child element | The image(s) of the User | Optional; Only supported in GET method | |
| id | string maximum 36 characters | Unique identifier for the Image |
|
filename | string max 255 characters | The filename the image |
| |
url | string | The url for the image |
| |
category | integer | The category of the image |
| |
content_type | string | The content type of the image |
| |
created_at | datetime | The created date of the image record |
| |
Add a new user
POST /api/users
http://<ip address>:<api listening port>/api/users
Content-Type: text/xml
Post Data:
<user>
<id />
<first_name>Test E. Cardholder IV - PIV</first_name>
<last_name>Test</last_name>
<access_start_date />
<access_end_date>20301231</access_end_date>
<pin type="integer" />
<email />
<phone />
<disabled type="boolean" />
<access_groups>
<access_group>
<id>82</id>
<name>Engineering 1b</name>
</access_group>
<access_group>
<id>84</id>
<name>Manager</name>
</access_group>
<access_group>
<id>83</id>
<name>Production 1</name>
</access_group>
</access_groups>
<credential>
<type>PIV-II</type>
<fascn_hex>D650185B3CCE6D9C9053CDA16CDA10AA09C4378486501843EB</fascn_hex>
<expiration_date>20301231</expiration_date>
<card_auth_key />
<guid>00000000000000000000000000000000</guid>
</credential>
</user>List all users
GET /api/users
http://<ip address>:<api listening port>/api/users
Result:
<users>
<user>
<id>252</id>
<first_name>Test E. Cardholder IV - PIV</first_name>
<last_name>Test</last_name>
<access_start_date />
<access_end_date>20301231</access_end_date>
<pin type="integer" />
<email />
<phone />
<created_at>2013-08-22T10:06:52.000-07:00</created_at>
<updated_at>2013-08-22T10:06:52.000-07:00</updated_at>
<disabled type="boolean">false</disabled>
<credential>
<id>253</id>
<fascn_hex>D650185B3CCE6D9C9053CDA16CDA10AA09C4378486501843EB</fascn_hex>
<type>PIV-II</type>
<status />
<expiration_date>20301231</expiration_date>
<guid>00000000000000000000000000000000</guid>
<card_auth_key />
</credential>
<cards>
<card_number>32013733334893131152472674132011</card_number>
<card_number>3201373333489320301231</card_number>
</cards>
<access_groups>
<access_group>
<id>82</id>
<name>Engineering 1b</name>
</access_group>
<access_group>
<id>84</id>
<name>Manager</name>
</access_group>
<access_group>
<id>83</id>
<name>Production 1</name>
</access_group>
</access_groups>
<custom_field_items />
<images>
<image>
<id type="integer">260</id>
<filename>252_0.jpg</filename>
<url>http://192.168.123.101:9000/api/images/view/252_0.jpg</url>
<category type="integer">0</category>
<content_type>image/jpeg</content_type>
<created_at>2013-08-22T11:15:36.000-07:00</created_at>
</image>
</images>
</user>
<user>
<id>257</id>
<first_name>Test Cardholder XIV - PIV</first_name>
<last_name>Test</last_name>
<access_start_date />
<access_end_date>20301231</access_end_date>
<pin type="integer" />
<email />
<phone />
<created_at>2013-08-22T11:06:39.000-07:00</created_at>
<updated_at>2013-08-22T11:06:38.000-07:00</updated_at>
<disabled type="boolean">false</disabled>
<credential>
<id>258</id>
<fascn_hex>D6501858999CED9992049DA16AD9A19C279A844486501843F5</fascn_hex>
<type>PIV-II</type>
<status />
<expiration_date>20301231</expiration_date>
<guid>00000000000000000000000000000000</guid>
<card_auth_key />
</credential>
<cards>
<card_number>23100241</card_number>
<card_number>32014399394149156091935084132011</card_number>
<card_number>3201439939414920301231</card_number>
<card_number>834299</card_number>
</cards>
<access_groups>
<access_group>
<id>82</id>
<name>Engineering 1b</name>
</access_group>
</access_groups>
<custom_field_items />
<images />
</user>
</users>Search users with filtering criteria
GET /api/users/search
http://<ip address>:<api port>/api/users/search?id=83&first_name=Test%20E.%20Cardholder%20IV%20-%20PIV
Result:
<users_search>
<criteria>first_name=Test E. Cardholder IV - PIV,</criteria>
<users results="1">
<user>
<id>252</id>
<first_name>Test E. Cardholder IV - PIV</first_name>
<last_name>Test</last_name>
<access_start_date />
<access_end_date>20301231</access_end_date>
<pin type="integer" />
<email />
<phone />
<created_at>2013-08-22T10:06:52.000-07:00</created_at>
<updated_at>2013-08-22T10:06:52.000-07:00</updated_at>
<disabled type="boolean">false</disabled>
<credential>
<id>253</id>
<fascn_hex>D650185B3CCE6D9C9053CDA16CDA10AA09C4378486501843EB</fascn_hex>
<type>PIV-II</type>
<status />
<expiration_date>20301231</expiration_date>
<guid>00000000000000000000000000000000</guid>
<card_auth_key />
</credential>
<cards>
<card_number>32013733334893131152472674132011</card_number>
<card_number>3201373333489320301231</card_number>
</cards>
<access_groups>
<access_group>
<id>82</id>
<name>Engineering 1b</name>
</access_group>
<access_group>
<id>84</id>
<name>Manager</name>
</access_group>
<access_group>
<id>83</id>
<name>Production 1</name>
</access_group>
</access_groups>
<custom_field_items />
<images>
<image>
<id type="integer">260</id>
<filename>252_0.jpg</filename>
<url>http://192.168.123.101:9000/api/images/view/252_0.jpg</url>
<category type="integer">0</category>
<content_type>image/jpeg</content_type>
<created_at>2013-08-22T11:15:36.000-07:00</created_at>
</image>
</images>
</user>
</users>
</users_search>Get a user record by user id
GET /api/users/<user id>
http://<ip address>:<api listening port>/api/users/252
Result:
Update a user record by user id
PUT /api/users/<user id>
http://<ip address>:<api listening port>/api/users/252
Result:
Delete a user record by user id
DELETE /api/users/<user id>
http://<ip address>:<api listening port>/api/users/252
Result:
Response code 204 if successfully deleted or if the user does not exist
Credentials
This chapter describes how to retrieve or delete Credentials through the PRIMIS API software.
credential element:
Element Name | Type | Description | Comments |
id | string maximum 36 characters | Unique identifier for a Credential | Optional; On POST, server generates an ID |
fascn_hex | string maximum 50 characters | FASCN of the PIV Card represented as a hex string | Required |
type | Either ‘PIV-I’ or ‘PIV- II’ | The type of Credential | Optional |
status | - | - | UNUSED |
expiration_date | date(yyyymmdd) | Expiration date of the CHUID | Required |
guid | string maximum 255 characters | The GUID located within the CHUID | Optional |
card_auth_key | - | - | UNUSED |
List all credentials
GET /api/credentials
http://<ip address>:<api listening port>/api/credentials
Result:
Get a credential record by credential id
GET /api/credentials/<credential id>
http://<ip address>:<api listening port>/api/credentials/253
Get a credential record by the FASC-N
GET /api/credentials/fascn/<fascn>
http://<ip address>:<api port>/api/credentials/fascn/D650185B3CCE6D9C9053CDA16CDA10AA09C4378486501843EB
Delete a credential by credential id
DELETE /api/credentials/<credential id>
http://<ip address>:<api listening port>/api/credentials/253
Result:
Response code 204 if successfully deleted or if the credential does not exist.
List all certificates under a credential id
GET /api/credentials/<credential id>/certificates
http://<ip address>:<api listening port>/api/credentials/253/certificates
Result:
|
Certificates
This chapter describes how to create/retrieve/update/delete Certificates through the PRIMIS API software.
certificate element:
Element Name | Type | Description | Comments |
|---|---|---|---|
id | string maximum 36 characters | Unique identifier for a Certificate | Optional; On POST, server generates an ID |
credential_id | string maximum 36 characters | The ID of the Credential that the Certificate belongs to | Required |
type | 0, 1, 2, 3, or 4 | The type of Certificate | Required |
not_before | datetime | The start date and time that the Certificate will be valid | Required |
not_after | datetime | The end date and time that the Certificate will be valid | Required |
validated_at | datetime | The date and time when the Certificate was validated | Optional |
status | 0 or 1 | Indicates the validity of the Certificate | Required |
content | string | The content of the Certificate | Required |
serial_number | string, maximum 300 characters | The serial number of the Certificate |
|
issuer_name | string, maximum 300 characters | The issuer name of the Certificate | Required |
List all Certificates
GET /api/certificates
http://<ip address>:<api listening port>/api/certificates
Result:
|
Add a new certificate
POST /api/certificates
http://<ip address>:<api listening port>/api/certificates
Content-Type: text/xml
Post Data:
|
Get a certificate by certificate id
GET /api/certificates/<certificate id>
http://<ip address>:<api listening port>/api/certificates/10
Result:
|
Update a certificate by certificate id
PUT /api/certificates/<certificate id>
http://<ip address>:<api listening port>/api/certificates/10
PUT Data:
|
Delete a certificate by the certificate id
DELETE /api/certificates/<certificate id>
http://<ip address>:<api listening port>/api/certificates/10
Result:
Response code 204 if successfully deleted or if the certificate does not exist.
Images
This chapter describes how to create/retrieve/delete Images through the PRIMIS API software.
Image element:
Element Name | Type | Description | Comments |
id | string maximum 36 characters | Unique identifier for an Image | On POST, server generates an ID |
user_id | string max 200 characters | The identifier of the user | Required |
filename | string max 255 characters | The filename the image | Required |
url | string | The url for the image | Supported in GET method. |
category | integer | The category of the image | On POST, default to 0 |
content_type | string, maximum 255 characters | The content type of the image | Required |
created_at | datetime | The created date of the image record |
|
List all images
GET /api/images
http://<ip address>:<api listening port>/api/images
Result:
Add image to User
POST /api/images/user/<user id>
http://<ip address>:<api listening port>/api/images/user/170
Content-Type: image/jpeg
Delete an image
DELETE /api/images/<image id>
http://<ip address>:<api listening port>/api/images/170
Result:
Response code 204 if successfully deleted or if the image does not exist.
Access Groups
This chapter describes how to create/retrieve/update/delete Access Groups through the PRIMIS API software.
access_group element:
Element Name | Type | Description | Comments | |
id | string maximum 100 characters | Unique identifier for an Access Group | Optional; On POST, server generates an ID | |
name | string max 200 characters | The name of the Access Group | Required | |
description | string max 100 characters | The description of the Access Group | Optional | |
site_id | string maximum 36 characters | The ID of the Site that the Access Group belongs to | Optional; on POST, default to 1 if it is not set. site_id 0 means the access group is a global access group and it can be used in all sites. | |
access_right | child element | The Access Right granted to the Access Group | access_right is only supported in GET method | |
| zone_id | string max 200 characters | The ID of the Controlled Area that the Access Right has access to | Required |
schedule_id | string max 50 characters | The ID of the Schedule that the Access Right is following | Required | |
activation_time | integer | The activation time of the output devices (i.e. how long the door will be opened for) | Required | |
List all access groups
GET /api/access_group
http://<ip address>:<api listening port>/api/access_groups
Result:
Add access group to user
POST /api/users/<user id>/access_groups
http://<ip address>:<api listening port>/api/users/<user id>/access_groups
Post Data:
Delete an access group from user
DELETE /api/users/<user id>/access_groups
http://<ip address>:<api listening port>/api/users/<user id>/access_groups
Result:
Response code 204 if successfully removed from the user or if the access group was not assigned to the user.
Add a new access group
POST /api/access_groups
http://<ip address>:<api listening port>/api/access_groups
Content-Type: text/xml
Post Data:
Get an access group record by the access group id
GET /api/access_groups
http://<ip address>:<api listening port>/api/access_groups/213
Result:
Update an access group record by the access group id
PUT /api/access_groups/<access group id>
http://<ip address>:<api listening port>/api/access_groups/213
Content-Type: text/xml
Put Data:
Delete an access group record by the access group id
DELETE /api/access_groups/<access group id>
http://<ip address>:<api listening port>/api/access_groups/213
Result:
Response code 204 if successfully deleted or if the access group does not exist.
CA Certificates
This chapter describes how to create/retrieve/update/delete CA Certificates through the PRIMIS API software.
Element Name | Type | Description | Comments |
|---|---|---|---|
id | string maximum 36 characters | Unique identifier for a CA Certificate | Optional; On POST, server generates an ID |
issuer_name | string max 300 characters | The issuer name of the CA Certificate | Required |
serial_number | string max 100 characters | The serial number of the CA Certificate | Required |
subject_name | string max 300 characters | The subject name of the CA Certificate | Required |
issued_to | string max 200 characters | The organization that the CA Certificate is issued to | Required |
issued_by | string max 200 characters | The organization that issued the CA Certificate | Required |
expiration_date | datetime | Indicates the validity of the CA Certificate | Required |
file_name | string max 200 characters | The file name of the CA Certificate | Required |
content | string | The content of the CA Certificate | Required |
ak_id | string max 255 characters | Authority key identifier of the CA Certificate | Required |
sk_id | string max 255 characters | Subject key identifier of the CA Certificate | Required |
Add a new CA certificate
POST /api/ca_certificates
http://<ip address>:<api listening port>/api/ca_certificates
Content-Type: text/xml
Post Data:
|
List all CA certificates
GET /api/ca_certificates
http://<ip address>:<api listening port>/api/ca_certificates
Result:
|
Get a CA certificate by the CA certificate id
GET /api/ca_certificates/<ca_certificate id>
http://<ip address>:<api listening port>/api/ca_certificates/163
Result:
|
Update a CA certificate by the CA certificate id
PUT /api/ca_certificates/<ca certificate id>
http://<ip address>:<api listening port>/api/ca_certificates/163
PUT Data:
|
Delete a CA certificate by the CA certificate id
DELETE /api/ca_certificates/<ca_certificate id>
http://<ip address>:<api listening port>/api/ca_certificates/163
Result:
Response code 204 if successfully deleted or if the CA certificate does not exist.
Cards
This chapter describes how to create/retrieve/update/delete Cards through the PRIMIS API software.
card element:
Element Name | Type | Description | Comments |
card_number | string max 100 characters | Unique identifier for a Card | Required |
card_type | string, either ‘wg’ or ‘piv’ | The type of the card | Required |
user_id | string max 200 characters | The ID of the User that the Card belongs to | Required |
created_at | datetime | Create timestamp |
|
updated_at | datetime | Update timestamp |
|
disabled | boolean(true/false) | Enable or disable the Card | Required |
Add a new card
POST /api/cards
http://<ip address>:<api listening port>/api/cards
Content-Type: text/xml
Post Data:
List all cards
GET /api/cards
http://<ip address>:<api listening port>/api/cards
Result:
Get a card record by the card id
GET /api/cards/<card id>
http://<ip address>:<api listening port>/api/cards/048051B4228841FDB8955FE9945E1C63
Result:
Update a card record by the card id
PUT /api/cards/<card id>
http://<ip address>:<api listening port>/api/cards/048051B4228841FDB8955FE9945E1C63
Content-Type: text/xml
Put Data:
Delete a card record by the card id
DELETE /api/cards/<card id>
http://<ip address>:<api listening port>/api/cards/048051B4228841FDB8955FE9945E1C63
Result:
Response code 204 if successfully deleted or if the card does not exist.
Sites
This chapter describes how to create/retrieve/update/delete Sites through the PRIMIS API software.
site element:
Element Name | Type | Description | Comments |
id | string maximum 36 characters | Unique identifier for a Site | Optional; On POST, server generates an ID |
name | string max 200 characters | The name of the Site | Required |
description | string max 200 characters | The description of the Site | Optional |
timezone_id | string max 200 characters | The timezone where the Site is in. The value must be a valid Java TimeZone ID. The complete list of supported timezones is available from: | Required |
Add a new site
POST /api/sites
http://<ip address>:<api listening port>/api/sites
Content-Type: text/xml
Post Data:
List all sites
GET /api/sites
http://<ip address>:<api listening port>/api/sites
Result:
Get a site record by the site id
GET /api/sites/<site id>
http://<ip address>:<api listening port>/api/sites/1
Result:
Update a site record by the site id
PUT /api/sites/<site id>
http://<ip address>:<api listening port>/api/sites/1
Content-Type: text/xml
Put Data:
Delete a site record by the site id
DELETE /api/sites/<site id>
http://<ip address>:<api listening port>/api/sites/10
Result:
Response code 204 if successfully deleted or if the site does not exist.
Controlled Areas
This chapter describes how to create/retrieve/update/delete Controlled Areas through the Primis API software.
controlled_area element:
Element Name | Type | Description | Comments |
id | string max 200 characters | Unique identifier for a Controlled Area | Optional; On POST, server generates an ID |
name | string max 255 characters | The name of the Controlled Area | Required |
description | string max 255 characters | The description of the Controlled Area | Optional |
toggle | character | When toggle is set to “T”, the Controlled Area will remain off or on indefinitely when its state is changed. This disables activation times for the Controlled Area and toggles the state of the Controlled Area indefinitely. | Optional |
factor | integer | Multi-factor settings for authorization | Optional; On POST, default to 0 |
authorization_mode | integer | Multi-factor authorization mode | Optional; On POST, default to 0 |
authorization_timeout | Integer | Time out in seconds for multi-factor authorization | Optional; On POST, default to 0 |
guard_group |
|
| Deprecated |
state | string | The state of the Controlled Area | Required |
zone_group_id | string maximum 36 characters | The zone group which the controlled area is assigned to. | Optional: |
site_id | string maximum 36 characters | The site identifier | On POST, default to 1 if it is not set. |
Add a new controlled area
POST /api/controlled_areas
http://<ip address>:<api listening port>/api/controlled_areas
Content-Type: text/xml
Post Data:
List all controlled areas
GET /api/controlled_areas
http://<ip address>:<api listening port>/api/controlled_areas
Result:
Get a controlled area record by the controlled area id
GET /api/controlled_areas/<controlled area id>
http://<ip address>:<api listening port>/api/controlled_areas/1110000000003
Result:
Update a controlled area record by the controlled area id
PUT /api/controlled_areas/<controlled area id>
http://<ip address>:<api listening port>/api/controlled_areas/1110000000003
Content-Type: text/xml
Put Data:
Delete a controlled area record by the controlled area id
DELETE /api/controlled_areas/<controlled area id>
http://<ip address>:<api listening port>/api/controlled_areas/1110000000003
Result:
Response code 204 if successfully deleted or if the controlled area does not exist.
Schedules
This chapter describes how to create/retrieve/update/delete Schedules through the PRIMIS API software.
schedule element:
Element Name | Type | Description | Comments | |
|---|---|---|---|---|
id | string maximum 50 characters | Unique identifier for a Schedule | Optional; On POST, server generates an ID | |
name | string max 200 characters | The name of the Schedule | Required | |
description | string max 80 characters | The description of the Schedule | Optional | |
site_id | string maximum 36 characters | The site identifier | On POST, default to 1 if it is not set. | |
period | child element |
| period is only supported in GET method | |
| id | string max 36 characters | Unique identifier for a Schedule Period |
|
frequency | integer | The frequency of the Schedule Period | This field is a bit mask of the two types - weekly and holiday. When weekly is used, this field has the value of 0x00002 (decimal 2). When holiday type is used, the lower two bytes has the value of 0x00040 (decimal 64), the upper 3 bytes represents the holiday type in used. Each bit in these 3 upper bytes present one holiday type enumerated like the following: Type 1 - 0x00100 | |
| exceptions | integer | The exception holiday types in the Schedule Period | This field is a bit mask that maintains the exception holiday types in the schedule period. The types are enumerated the same way as the types 1 through to 12 in frequency (0x00100, 0x00200.... 0x80000). |
| days | integer | The days of the week that are active in the Schedule Period | This field is a bit mask that maintains the days of the week that are active in the schedule period. SUNDAY_MASK = 0x0001; MONDAY_MASK = 0x0002; TUESDAY_MASK = 0x0004; WEDNESDAY_MASK = 0x0008; THURSDAY_MASK = 0x0010; |
| on_time | datetime | The effective start date of the Schedule Period | 1900-01-01 00:00:00.0 will be returned if no start date is specified |
| off_time | datetime | The effective expire date of the Schedule Period | 1900-01-01 00:00:00.0 will be returned if no expire date is specified |
| enabled | integer |
| Deprecated |
Add a new schedule
POST /api/schedules/<schedule id>
http://<ip address>:<api listening port>/api/schedules
Content-Type: text/xml
Post Data:
List all schedules
GET /api/schedules
http://<ip address>:<api listening port>/api/schedules
Result:
Get a schedule record by the schedule id
GET /api/schedules/<schedule id>
http://<ip address>:<api listening port>/api/schedules/23
Result:
Update a schedule record by the schedule id
PUT /api/schedules/<schedule id>
http://<ip address>:<api listening port>/api/schedules/23
Content-Type: text/xml
Put Data:
Delete a schedule record by the schedule id
DELETE /api/schedules/<schedule id>
http://<ip address>:<api listening port>/api/schedules/23
Result:
Response code 204 if successfully deleted or if the schedule does not exist.
Access Rights
This chapter describes how to create/retrieve/delete Access Rights through the PRIMIS API software.
access_right element:
Element Name | Type | Description | Comments |
zone_id | string max 200 characters | The ID of the Controlled Area that the Access Right has access to | Required |
schedule_id | string max 50 characters | The ID of the Schedule that the Access Right is following | Required |
activation_time | integer | The activation time of the output devices (i.e. how long the door will be opened for) | Required |
Add a new access right to an access group
POST /api/access_groups/<access group id>/controlled_areas
http://<ip address>:<api listening port>/api/221/controlled_areas
Content-Type: text/xml
Post Data:
List all controlled areas accessible by an access group
GET /api/access_groups/<access group id>/controlled_areas
http://<ip address>:<api listening port>/api/access_groups/221/controlled_areas
Result:
List all access groups assigned to an user
GET /api/access_groups/<access group id>/users
http://<ip address>:<api listening port>/api/access_groups/221/users
Result:
Delete access right from an access group by the controlled area id
DELETE /api/access_groups/<access group id>/controlled_areas/<controlled area id>
http://<ip address>:<api listening port>/api/access_groups/221/controlled_areas/1110000000003
Result:
Response code 204 if successfully deleted or if the access right does not exist.
Zone Groups
This chapter describes how to create/retrieve/update/delete Zone Groups through the PRIMIS API software.
zone_group element:
Element Name | Type | Description | Comments | |
id | string maximum 36 characters | Unique identifier for a Site | Optional; On POST, server generates an ID | |
name | string max 100 characters | The name of the Site | Required | |
description | string max 200 characters | The description of the Site | Optional | |
site_id | string maximum 36 characters | The site identifier | On POST, default to 1 if it is not set. | |
controlled_area |
|
| controlled-area is only supported in GET method | |
| id | string max 200 characters | Unique identifier for a Controlled Area |
|
name | string max 255 characters | The name of the Controlled Area |
| |
Add a new zone group
POST /api/zone_groups
http://<ip address>:<api listening port>/api/zone_groups
Content-Type: text/xml
Post Data:
List all zone groups
GET /api/zone_groups
http://<ip address>:<api listening port>/api/zone_groups
Result:
Get a zone group record by the zone group id
GET /api/zone_groups/<zone group id>
<http://<ip> address>:<api listening port>/api/zone_groups/1
Result:
Update a zone group record by the zone group id
PUT /api/zone_groups/<zone group id>
http://<ip address>:<api listening port>/api/zone groups/1
Content-Type: text/xml
Put Data:
Delete a zone group record by the zone group id
DELETE /api/zone groups/<zone group id>
http://<ip address>:<api listening port>/api/zone_groups/10
Result:
Response code 204 if successfully deleted or if the zone group does not exist.
Activity Events
This chapter describes how to retrieve Activity events through the PRIMIS API software.
activity_event element:
Element Name | Type | Description | Comments |
|---|---|---|---|
id | integer | Unique identifier for an activity event |
|
hostname | string max 50 characters | Hostname of the server which logged the event |
|
event_time | datetime | Timestamp of the event | This element is searchable by using query parameter logged_since. for example: logged_since=20170615130130 will return all events logged after 2017-06-15 13:01:30 |
site_id | string maximum 36 characters | The identifier of the site | This element is searchable |
activity_type | string max 20 characters | Activity type of the event | Supported values are: Unknown, Card Access, Port, Video, Dial Suite, PIN Access, Panel Access, Schedule, Snapshot, Phone Access, Manual. This element is searchable |
device_id | string max 100 characters | The identifier of the device | This element is searchable |
device_name | string max 100 characters | Name of the device | This element is searchable |
device_type | string max 50 characters | Type of the device | This element is searchable |
port_name | string max 50 characters | Name of the port | This element is searchable |
originator_id | string max 2000 characters | The identifier of the originator | This element is searchable |
originator_name | string max 50 characters | Name of the originator | This element is searchable |
result | string max 100 characters | Result of the event | Supported values are: Unknown, Granted, Denied, Opened, Closed, Snapshot, Answered, Placed, Wrong number, Restricted, Locked, Unlocked, Set, Reset, Denied - CA Locked Down, Authenticated, Denied - Invalid License, Error Break, Error short, Denied - Anti Passback, Denied - Card Disabled, Denied - User Deactivated, - Denied - User Expired, Denied - Access Expired, Denied - Risk Level, Denied - Start Date Error, Denied - Certificate Revoked, Denied - Certificate Chain Invalid, Denied - Certificate Signature Invalid, Granted - Certificate Chain Error Ignored, Granted - Certificate Signature Error Ignored, Denied - Certificate Timestamp Invalid, Denied -, Card Swipe, Card Swipe 2 Times, Card Swipe 3 Times, Card Swipe 4 Times, Card Swipe 5 Times, Card Swipe 6 Times, Request to Exit, Door Opened, Door Closed This element is searchable |
suite_id | string max 50 characters | The identifier of the suite | This element is searchable |
user_id | string max 200 characters | The identifier of the user | This element is searchable |
first_name | string max 50 characters | First name of the user | This element is searchable |
last_name | string max 50 characters | Last name of the user | This element is searchable |
card_number | string max 100 characters | Card number of the user | This element is searchable |
snapshot_url | string max 50 characters | URL of the photo snapshot | This element is searchable |
io_control | string max 2 characters |
| Obsoleted |
sent_to_ams | boolean(true/false) | Flag to indicate if the event has been sent to AMS |
|
event_code | integer | Event code of the event | This element is searchable |
List all activity events
GET /api/activitylog
http://<ip address>:<api listening port>/api/activitylog
Result:
Retrieve a range of activity events
GET /api/activitylog?offset=<offset>&n=<limit>
To return the activity event record 101 to 150
http://<ip address>:<api listening port>/api/activitylog?offset=100&n=50
Search activity events with filtering criteria
GET /api/activitylog/search
http://<ip address>:<api listening port>/api/activitylog/search?event_code=10301
Result:
Get a activity event record by id
GET /api/activitylog/<id>
http://<ip address>:<api listening port>/api/activitylog/3045762
Result:
System Events
This chapter describes how to retrieve System events through the PRIMIS API software.
Element Name | Type | Description | Comments |
|---|---|---|---|
id | integer | Unique identifier for an system event |
|
hostname | string max 50 characters | Hostname of the server which logged the event |
|
event_time | datetime | Timestamp of the event |
|
site_id | string maximum 36 characters | The identifier of the site | This element is searchable |
category | string max 20 characters | Category of the system event | Supported values are: System, Device, Network, Port, User, Floor, Door, Database, Credential, Ldap, Logon/Logoff, Operator Action and Video |
event_code | integer | Event code identifying events | This element is searchable |
severity | string max 20 characters | Severity level of the event | Supported values are: Info, Warning, Error, Critical, Alert and Emergency |
activity_type | string max 50 characters | Event type of the event | Supported values are: UNKNOWN, ALARM, MESSAGE, DEBUG and ALARM CLEARED. |
controlled_area | string max 255 characters | Name of the controlled area | This element is searchable |
device_id | string max 100 characters | The identifier of the device | This element is searchable |
device_name | string max 100 characters | Name of the device | This element is searchable |
suite_id | string max 50 characters | The identifier of the suite | This element is searchable |
card_number | string max 100 characters | Card number of the user | This element is searchable |
snapshot_url | string max 50 characters | URL of the photo snapshot | This element is searchable |
result | string max 100 characters | The result of the event | This element is searchable |
event_info | string max 2000 characters | The detail information of the event | This element is searchable |
instruction_id | integer | The identifier of the instruction |
|
acknowledge_required | boolean(true/false) | Flag to indicate if operator acknowledgement is required |
|
transaction_id | integer | The transaction id of the event. The same transaction id will be assigned to related system events. | This element is searchable |
sent_to_ams | boolean(true/false) | Flag to indicate if the event has been sent to AMS |
|
List all system events
GET /api/systemlog
http://<ip address>:<api listening port>/api/systemlog
Result:
Retrieve a range of system events
GET /api/systemlog?offset=<offset>&n=<limit>
To return the system event record 101 to 150
http://<ip address>:<api listening port>/api/systemlog?offset=100&n=50
Search system events with filtering criteria
GET /api/systemlog/search
http://<ip address>:<api listening port>/api/systemlog/search? severity_level=Error
Result:
Get a system event record by id
GET /api/systemlog/<id>
http://<ip address>:<api listening port>/api/systemlog/519810
Result:
GLOSSARY
TERM | DEFINITION |
Access Group | Access Group is the logical grouping of users which you can assign Access Right to. |
Access Right | The access right assigned to an Access Group. Access Right defines the access permission to a controlled area under a time schedule. |
Administrator | An individual who is responsible for the maintenance and implementation of access control rights involving tasks such as issuing, and closing user accounts; tracking users and their respective access authorizations; and managing these functions. |
CA Certificate | The certificate of a Certificate Authority which issues digital certificates. |
Card | The access card issued to a user. It can be a Wiegand card or a PIV card. |
Certificate | The digital certificate of an entity or User. |
Controlled Area | Controlled Area is an area being controlled by one or more input or output devices such as Primis Bridge readers. |
Credential | The credential information of the PIV card. |
Image | The digital image of a User. |
IP Address | An IP address is a unique identifier for a computer or device on an Internet protocol network. |
PIV Card | A physical identity card, smart card issued to an individual that contains stored identity credentials such as a photograph, cryptographic keys, digitized fingerprint representation to verify the identity of the cardholder by a process or individual. |
Schedule | A schedule is a given period of time that is applied to Controlled Areas and Access Groups and used to schedule device activation and alarms. |
Site | A geographical grouping of controlled area(s). |
User | An individual whose access privilege to controlled areas are managed by PRIMIS. |
Zone Group | Zone Group is a logical grouping of Controlled Areas. |