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

Develop a physical access control system integration with Camio quickly and easily by posting access control devices and events to the Camio API.

Devices (badge readers)

In order for Camio to know the user's available access control devices, send a payload to https://incoming.integrations.camio.com/pacs/devices when setting up the integration and whenever the user's devices are updated. See the payload described in the API to POST Devices.

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 so that Camio can correlate the access control events with the associated video.

Note that POSTs to the https://incoming.integrations.camio.com/pacs/devices endpoint overwrite the user's stored devices, but Camio won't forget currently configured devices unless the user removes them from the integration on the settings page. Remove the devices assigned to a camera by clicking the x next to the device names and hitting Save.

Access Control Events

When a new access control event occurs, such as a door unlock, send information to https://incoming.integrations.camio.com/pacs/webhooks. By including the user's authorization token and the access device's id, Camio matches the access control event to the user's video. Any labels you add to the video become searchable. See the payload described in the API to POST Events.

API Calls

{
  "devices": [\
    {\
      "device_id": "{{unique_id}}",\
      "device_name": "{{display_name}}"\
    },\
    ...\
  ]
}

Curl

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

Response Codes

None

Curl

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

Response Codes

Only device_id, timestamp, event_type, and actor_id are required.

{
   # Either event or events is required
   "event": {
        "device_id": {{unique_id}},
        "timestamp": {{ISO8601_datetime_UTC_string}},
        "event_type": {{valid_event_type}},
        "labels": [{{any_string}}],
        "actor_id": {{any_string}},
        "actor_name": {{any_string}},
        "actor_email": {{valid@email.com}}
   },
   "events": [\
      ... # List of access events, structured the same way as event above\
   ]
}

Curl

curl --location --request POST 'https://incoming.integrations.camio.com/pacs/webhooks' \
--header 'Authorization: Bearer 42g-D0T41A5HIu4ssrlJgepKRGLgA-s' \
--header 'Content-Type: application/json' \
--data-raw '{
   "event": {
      "timestamp": "2023-08-04T22:28:44.989-0000",
      "event_type": "Entry Unlocked",
      "device_id": "testDevice0129397",
      "actor_id": "T.Smith0129486",
      "actor_name": "Tester Smith",
      "actor_email": "tsmith@gmail.com",
      "labels": [\
        "South Entry",\
        "Building 5"\
      ]
   }}'

Valid Event Types

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

Response Codes

Testing Steps

1. Create a Camio account at https://camio.com/app
2. Register a Camio Boxto the account
   • For development, we recommend setting up a Camio VM for free
   • See https://camio.com/start for other options
3. Connect cameras to the Camio Box on the boxes page
4. [Optional] Add a 3D grid on the cameras to be used for Access Control

• Follow this guide for optimal setup
  • A 3D grid is required to perform tailgating (unauthorized entry) analysis. If your integration does not trigger tailgating analysis then you can skip this step.

5. Generate a bearer token on the integration settings page. 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 below. - If your software solution supports OAuth flows, then you can request this token via OAuth with scope=annotations:write
6. Add devices to your integration
7. Map the devices to cameras on the settings page and hit Save
   • If you do not save your integration settings you will receive a 404 response from the webhooks endpoint
   • With no devices mapped to cameras you will receive a 400 response from the webhooks endpoint
8. Send access control event webhooks to Camio
9. View results in the Camio app - Search for "entry unlocked" or any other labels added via webhooks

Legacy API Calls

These endpoints are deprecated in favor of the new integration server https://incoming.integrations.camio.com used in the examples above. These endpoints will continue to work but new features and improvements will not be added.

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

Response Codes

None

Curl

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

Response Codes

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

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

Valid Event Types

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

Response Codes

required

at least one is required