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/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

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_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
Have more questions? Submit a request

Comments