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:

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:

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/pacs/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 remove the devices assigned to a camera by clicking the x next to the device names and then 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

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

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"
         },
         ...
    ]
}'

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

{
  "readers": [
    {
      "device_id": "testDevice0129397",
      "device_name": "Test Device"
    },
    ...
  ]
}

{  
    device_id: {{unique_id}},
    timestamp: {{ISO8601_datetime_string}},
    event_type: {{valid_event_type}},
    labels: [{{any_string}}],
    actor_id: {{any_string}},
    actor_name: {{any_string}},
   actor_email: {{valid@email.com}}
}

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",
  "actor_email": "tsmith@gmail.com"
}'

**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.

entry unlocked

forced open

entry ajar