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 below.
If your software solution supports OAuth flows, then you can request this token via OAuth with scope=annotations:write.
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. 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 https://incoming.integrations.camio.com/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.
Access Control Events
When a new access control event occurs, 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 (optional)
|
|
|
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 '{
"readers": [
{
"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"
]
}}'
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
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
|
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
|
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
|
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
|
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"
}'
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
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
|
Comments