Develop a physical access control system integration with Camio quickly and easily by posting access control devices and events to the Camio API.
Table of Contents
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
Method + URL
|
Examples
|
Devices
|
|
POST /pacs/devices
|
Payload
{ "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
200/204
|
Success. No payload is returned.
|
400/422
|
Bad request / Malformed payload. Check that the payload you sent matches the example above. An empty payload also will return a 422.
|
401
|
Unauthorized. Most likely missing the Authorization header.
|
405
|
Method not allowed. Only supports GET and POST.
|
500
|
Server error. Something unexpected went wrong. If this does not seem to be a transient error, please contact support@camio.com for help resolving this error.
|
|
GET /pacs/devices
|
Payload
None
Curl
curl --location --request GET 'https://incoming.integrations.camio.com/pacs/devices' \ --header 'Authorization: Bearer 42g-D0T41A5HIu4ssrlJgepKRGLgA-s'
Response Codes
200
|
Success. Returns a json payload in the same format as the POST above. Ex:
{ "readers": [ { "integration_name": "pacs", "device_id": "testDevice0129397", "device_name": "Test Device" }, ... ] }
|
401
|
Unauthorized. Most likely missing the Authorization header.
|
405
|
Method not allowed. Only supports GET and POST.
|
404
|
Not found. No stored devices found for the user.
{ "detail": "No devices found for {{user_id}}" }
|
500
|
Server error. Something unexpected went wrong. If this does not seem to be a transient error, please contact support@camio.com for help resolving this error.
|
|
Events
|
|
POST /pacs/webhooks
|
Payload
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.
event_type (not case sensitive)
|
entry unlocked
|
forced open
|
entry ajar
|
Response Codes
200
|
Success. A payload is returned that includes the annotations that will be applied to any matching Camio events, as well as the estimated time that the annotations request will go through:
{ "annotation_request": { "user_id": "...", "annotations": [{ "timestamp": "2023-08-04T22:28:44.989000+00:00", "cameras": [{ "camera_id": "...", "user_id": "..." }], "labels_to_add": [ "integration:pacs", "entry.unlocked", "T.Smith0129486_entry.unlocked", "tester_smith_entry.unlocked", "tsmith@gmail.com_entry.unlocked", "pacs:entry.unlocked:2023-08-04T22:28:44.989000+00:00", "integration:pacs:2023-08-04T22:28:44.989000+00:00:Entry Unlocked:T.Smith0129486:tsmith@gmail.com:tester_smith", "T.Smith0129486", "Tester Smith", "South Entry", "Building 5" ], "labels_to_remove": [] }], "create_time": "2023-08-04 22:54:29+00:00", "schedule_time": "2023-08-04 22:54:29.875997+00:00" } }
|
400/422
|
Bad request / Malformed payload. Check that the payload you sent matches the example above. An empty payload also will return a 422.
Common error is that the user has no camera mapped to the device_id. Make sure the user has a camera mapped to the device on their settings page.
Response when there are no cameras mapped to the device looks like this:
{ "detail": "No annotations could be created from the events." }
|
401
|
Unauthorized. Most likely missing the Authorization header.
|
405
|
Method not allowed. Only supports POST.
|
404
|
User does not have PACS integration settings saved.
|
500
|
Server error. Something unexpected went wrong. If this does not seem to be a transient error, please contact support@camio.com for help resolving this error.
|
|
**required
**at least one is required
Testing Steps
-
Create a Camio account at https://camio.com/app
-
Register a Camio Box to the account
-
Connect cameras to the Camio Box on the boxes page
- [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.
-
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
-
Add devices to your integration
-
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
-
Send access control event webhooks to Camio
-
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.
Method + URL
|
Examples
|
POST /api/integrations/pacs/devices
deprecated
|
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" }, ... ] }'
Response Codes
200/204
|
Success. No payload is returned.
|
400
|
Bad request / Malformed payload. Check that the payload you sent matches the example above. An empty payload also will return a 400.
Also returned for unsupported methods. Supported methods are GET, POST, and PUT.
|
401
|
Unauthorized. Most likely missing the Authorization header.
|
403
|
Unauthorized. Caller does not have permission to make this request.
|
500
|
Server error. Something unexpected went wrong. If this does not seem to be a transient error, please contact support@camio.com for help resolving this error.
|
|
GET /api/integrations/pacs/devices
deprecated
|
Payload
None
Curl
curl --location --request GET 'https://camio.com/api/integrations/pacs/devices' \ --header 'Authorization: Bearer 42g-D0T41A5HIu4s4srlJgepKRGLgA-s'
Response Codes
200
|
Success. Returns a json payload in the same format as the POST above. Ex:
{ "readers": [ { "device_id": "testDevice0129397", "device_name": "Test Device" }, ... ] }
|
400
|
Bad request. Returned for unsupported methods. Supported methods are GET, POST, and PUT.
|
401
|
Unauthorized. Most likely missing the Authorization header.
|
404
|
Not found. No stored devices found for the user.
|
500
|
Server error. Something unexpected went wrong. If this does not seem to be a transient error, please contact support@camio.com for help resolving this error.
|
|
POST /api/integrations/pacs/webhooks
deprecated
|
Payload
{ 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.
event_type (not case sensitive)
|
entry unlocked
|
forced open
|
entry ajar
|
Response Codes
200/204
|
Success. No payload is returned.
|
400
|
Bad request / Malformed payload. Check that the payload you sent matches the example above. An empty payload also will return a 400.
Also returned for unsupported methods. Supported methods are POST and PUT.
|
401
|
Unauthorized. Most likely missing the Authorization header.
|
403
|
Unauthorized. Caller does not have permission to make this request.
Also returned if the user does not have a PACS integration.
|
404
|
No camera mapped to the device_id. Make sure the user has a camera mapped to the device on their settings page.
|
500
|
Server error. Something unexpected went wrong. If this does not seem to be a transient error, please contact support@camio.com for help resolving this error.
|
|
**required
**at least one is required
Comments