How do I create a Physical Access Control System integration? (Developer's Guide)

Getting Started

To create a Physical Access Control System (PACS) integration for an account, the user must first go to the settings page and generate a bearer token:

mceclip0.png

 

This token is used as authorization to store devices and write annotations for this account. Once you have the user's token, store it securely and use it with the API calls listed below

If your software solution supports OAuth flows, then you can request this token via OAuth with scope=annotations:write.

Add / Remove Devices

In order for Camio to know the user's available access control devices, send a payload to /api/integrations/pacs/devices when setting up the integration and whenever the user's devices are updated. This way, Camio can display the available devices on the user's settings page:

mceclip0.png

The user must select which access control devices are in view of which camera. This way, Camio can correlate the access control events with the associated video.

Note that POSTs to the /api/integrations/devices endpoint overwrite the user's stored devices, but Camio won't forget currently set devices unless the user removes them from the integration. They can do so by clearing them from the camera and hitting save.

POST Events

When a new access control event occurs, send information to /api/integrations/pacs/webhooks. By including the user's authorization token and the access device's id, Camio matches the access event to the user's video. Any labels you add to the video become searchable. See the payload described here.

API Calls

Method + URL Examples

POST /api/integrations/pacs/devices

Payload

{
readers: [
{
device_id: {{unique_id}},
device_name: {{display_name}}
}
]
}

 

Curl

curl --location --request POST 'https://camio.com/api/integrations/pacs/devices' \
--header 'Authorization: Bearer 42g-D0T41A5HIu4s4srlJgepKRGLgA-s' \
--header 'Content-Type: application/json' \
--data-raw '{
"readers": [
{
"device_id": "testDevice0129397",
"device_name": "Test Device"
}
]
}'

GET /api/integrations/pacs/devices

Payload

None

Curl

curl --location --request GET 'https://camio.com/api/integrations/pacs/devices' \
--header 'Authorization: Bearer 42g-D0T41A5HIu4s4srlJgepKRGLgA-s'

POST /api/integrations/pacs/webhooks

Payload

{  
device_id: {{unique_id}},

timestamp: {{ISO8601_datetime_string}}
event_type: {{valid_event_type}},
labels: [{{any_string}}],
actor_id: {{any_string}},
actor_name: {{any_string}}
}

Curl

curl --location --request POST 'https://camio.com/api/integrations/pacs/webhooks' \
--header 'Authorization: Bearer 42g-D0T41A5HIu4s4srlJgepKRGLgA-s' \
--header 'Content-Type: application/json' \
--data-raw '{
"device_id": "testDevice0129397",
"timestamp": "2021-11-01T17:30:10.000Z",
"event_type": "Entry Unlocked",
"labels": [
"South Entry",
"Building 5"
],
"actor_id": "T.Smith0129486",
"actor_name": "Tester Smith"
}'

**required

**at least one is required

Valid Event Types

Valid event types are searchable with additional natural language queries and may go through additional analysis such as tailgating detection.

event_type (not case sensitive)
entry unlocked
forced open
entry ajar
Have more questions? Submit a request

Comments