API Reference: Visitors & Check-Ins
API Reference: Visitors & Check-Ins
This reference documents all API endpoints related to visitors and check-ins in KyberAccess. Use these endpoints to
list, create, update, and manage visitor records programmatically.
For authentication setup and general API usage, see API Authentication & Getting Started.
Visitors Endpoints
List Visitors
Retrieve a paginated list of visitors.
GET /api/v1/visitors
Query Parameters:
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | date | string | No |
Filter by date: today, yesterday, or ISO 8601 date (YYYY-MM-DD) | | start_date | string | No | Start of date range
(ISO 8601) | | end_date | string | No | End of date range (ISO 8601) | | status | string | No | Filter by status:
checked_in, checked_out, denied, pre_registered | | location_id | string | No | Filter by location | | host_id | string
| No | Filter by host | | department | string | No | Filter by department | | purpose | string | No | Filter by visit
purpose | | search | string | No | Search by visitor name, email, or company | | page | integer | No | Page number
(default: 1) | | per_page | integer | No | Results per page (default: 25, max: 100) | | sort | string | No | Sort field:
check_in_time, name, company (default: check_in_time) | | order | string | No | Sort order: asc or desc (default: desc)
|
Example Request:
curl -X GET "https://api.kyberaccess.com/api/v1/visitors?date=today&status=checked_in" \
-H "Authorization: Bearer YOUR_TOKEN"
Response (200 OK):
{
"data": [
{
"id": "vis_abc123",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"phone": "+1-555-0100",
"company": "Acme Corp",
"purpose": "Meeting",
"host": {
"id": "usr_xyz789",
"name": "John Doe",
"email": "john@company.com",
"department": "Engineering"
},
"status": "checked_in",
"check_in_time": "2025-01-15T09:30:00Z",
"check_out_time": null,
"location": {
"id": "loc_001",
"name": "Main Office"
},
"id_scanned": true,
"id_type": "drivers_license",
"nda_signed": true,
"watchlist_cleared": true,
"badge_number": "V-0042",
"photo_url": "https://api.kyberaccess.com/photos/vis_abc123.jpg",
"custom_fields": {
"vehicle_plate": "ABC-1234",
"laptop_serial": "SN-98765"
},
"returning_visitor": true,
"visit_count": 5,
"created_at": "2025-01-15T09:30:00Z",
"updated_at": "2025-01-15T09:30:00Z"
}
],
"meta": {
"total": 47,
"page": 1,
"per_page": 25,
"total_pages": 2
}
}
Get Single Visitor
Retrieve details for a specific visitor.
GET /api/v1/visitors/{visitor_id}
Path Parameters:
| Parameter | Type | Description | |-----------|------|-------------| | visitor_id | string | The visitor's unique ID |
Example Request:
curl -X GET "https://api.kyberaccess.com/api/v1/visitors/vis_abc123" \
-H "Authorization: Bearer YOUR_TOKEN"
Response (200 OK): Returns the full visitor object as shown above, plus additional details:
{
"data": {
"id": "vis_abc123",
"first_name": "Jane",
"last_name": "Smith",
"...all standard fields...",
"id_photo_url": "https://api.kyberaccess.com/photos/vis_abc123_id.jpg",
"selfie_url": "https://api.kyberaccess.com/photos/vis_abc123_selfie.jpg",
"photo_match_score": 0.94,
"nda_document_url": "https://api.kyberaccess.com/docs/vis_abc123_nda.pdf",
"screening_results": {
"sex_offender": "clear",
"custom_watchlist": "clear",
"bolo": "clear"
},
"visit_history": [
{
"date": "2025-01-10",
"host": "John Doe",
"purpose": "Meeting"
},
{
"date": "2024-12-20",
"host": "Jane Manager",
"purpose": "Delivery"
}
]
}
}
Create a Pre-Registration
Pre-register an expected visitor.
POST /api/v1/visitors/pre-register
Request Body:
| Field | Type | Required | Description | |-------|------|----------|-------------| | first_name | string | Yes |
Visitor's first name | | last_name | string | Yes | Visitor's last name | | email | string | No | Visitor's email
(required for sending invite) | | phone | string | No | Visitor's phone number | | company | string | No | Visitor's
company | | purpose | string | No | Purpose of visit | | host_id | string | Yes | ID of the employee being visited | |
expected_date | string | Yes | Expected visit date (ISO 8601) | | expected_time | string | No | Expected arrival time
(HH:MM format) | | location_id | string | No | Location ID (defaults to primary location) | | send_invite | boolean | No
| Send email invite to visitor (default: true) | | custom_fields | object | No | Key-value pairs for custom fields | |
notes | string | No | Internal notes about the visit |
Example Request:
curl -X POST "https://api.kyberaccess.com/api/v1/visitors/pre-register" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Alice",
"last_name": "Johnson",
"email": "alice@partner.com",
"company": "Partner Inc",
"purpose": "Contract Review",
"host_id": "usr_xyz789",
"expected_date": "2025-01-20",
"expected_time": "10:00",
"send_invite": true,
"custom_fields": {
"vehicle_plate": "XYZ-5678"
}
}'
Response (201 Created):
{
"data": {
"id": "vis_def456",
"status": "pre_registered",
"qr_code_url": "https://api.kyberaccess.com/qr/vis_def456.png",
"invite_sent": true,
"...all standard fields..."
}
}
Check In a Visitor
Programmatically check in a visitor.
POST /api/v1/visitors/{visitor_id}/check-in
For pre-registered visitors, use their existing ID. For walk-ins, create a new visitor first:
POST /api/v1/visitors/check-in
Request Body (Walk-In):
| Field | Type | Required | Description | |-------|------|----------|-------------| | first_name | string | Yes |
Visitor's first name | | last_name | string | Yes | Visitor's last name | | email | string | No | Visitor's email | |
phone | string | No | Visitor's phone | | company | string | No | Visitor's company | | purpose | string | No | Purpose
of visit | | host_id | string | Yes | Host employee ID | | location_id | string | No | Location ID | | skip_screening |
boolean | No | Skip watchlist screening (default: false) | | custom_fields | object | No | Custom field values |
Response (201 Created):
{
"data": {
"id": "vis_ghi789",
"status": "checked_in",
"check_in_time": "2025-01-15T14:00:00Z",
"badge_number": "V-0043",
"host_notified": true,
"screening_results": {
"sex_offender": "clear",
"custom_watchlist": "clear",
"bolo": "clear"
}
}
}
Note: If watchlist screening returns a hit, the response includes a screening_alert field and the visitor status is set
to denied (if auto-deny is enabled) or flagged (if manual review is required).
Check Out a Visitor
POST /api/v1/visitors/{visitor_id}/check-out
Request Body (optional):
| Field | Type | Description | |-------|------|-------------| | notes | string | Check-out notes | | checked_out_by |
string | User ID of who processed the check-out |
Response (200 OK):
{
"data": {
"id": "vis_abc123",
"status": "checked_out",
"check_out_time": "2025-01-15T17:30:00Z",
"duration_minutes": 480
}
}
Bulk Check-Out
Check out multiple visitors at once (useful for end-of-day processing).
POST /api/v1/visitors/bulk-check-out
Request Body:
{
"visitor_ids": ["vis_abc123", "vis_def456", "vis_ghi789"],
"notes": "End of day bulk check-out"
}
Alternatively, check out all visitors at a location:
{
"location_id": "loc_001",
"check_out_all": true
}
Response (200 OK):
{
"data": {
"checked_out": 3,
"failed": 0,
"details": [
{ "id": "vis_abc123", "status": "checked_out" },
{ "id": "vis_def456", "status": "checked_out" },
{ "id": "vis_ghi789", "status": "checked_out" }
]
}
}
Update a Visitor Record
PATCH /api/v1/visitors/{visitor_id}
Request Body: Include only the fields you want to update.
{
"phone": "+1-555-0200",
"company": "New Company Name",
"custom_fields": {
"vehicle_plate": "NEW-1234"
}
}
Response (200 OK): Returns the updated visitor object.
Delete a Visitor Record
DELETE /api/v1/visitors/{visitor_id}
This permanently deletes the visitor record. For GDPR compliance, this also removes all associated photos, documents,
and screening results.
Response (204 No Content)
Warning: Deletion is irreversible. Consider using the archive endpoint instead if you need to retain data for
compliance.
Check-In Events Endpoints
List Check-In Events
Retrieve a log of all check-in and check-out events.
GET /api/v1/check-in-events
Query Parameters:
| Parameter | Type | Description | |-----------|------|-------------| | start_date | string | Start of date range | |
end_date | string | End of date range | | event_type | string | check_in, check_out, denied, pre_registered | |
location_id | string | Filter by location | | page | integer | Page number | | per_page | integer | Results per page |
Response (200 OK):
{
"data": [
{
"id": "evt_001",
"event_type": "check_in",
"visitor_id": "vis_abc123",
"visitor_name": "Jane Smith",
"host_name": "John Doe",
"location": "Main Office",
"timestamp": "2025-01-15T09:30:00Z",
"method": "kiosk",
"badge_printed": true,
"id_scanned": true,
"nda_signed": true
}
],
"meta": { "total": 156, "page": 1, "per_page": 25 }
}
Host Directory Endpoints
List Hosts
GET /api/v1/hosts
Query Parameters:
| Parameter | Type | Description | |-----------|------|-------------| | search | string | Search by name or email | |
department | string | Filter by department | | location_id | string | Filter by location |
Response (200 OK):
{
"data": [
{
"id": "usr_xyz789",
"name": "John Doe",
"email": "john@company.com",
"department": "Engineering",
"location": "Main Office",
"visitor_count_today": 3
}
]
}
Active Visitors (Real-Time)
Get all currently checked-in visitors.
GET /api/v1/visitors/active
Query Parameters:
| Parameter | Type | Description | |-----------|------|-------------| | location_id | string | Filter by location |
This endpoint is optimized for real-time dashboards and digital signage displays.
Emergency Endpoints
Get Evacuation List
Retrieve all currently checked-in visitors for emergency evacuation purposes.
GET /api/v1/emergency/evacuation-list
Response (200 OK):
{
"data": {
"location": "Main Office",
"generated_at": "2025-01-15T14:00:00Z",
"total_visitors": 12,
"visitors": [
{
"name": "Jane Smith",
"company": "Acme Corp",
"host": "John Doe",
"checked_in_at": "09:30",
"badge_number": "V-0042",
"photo_url": "https://api.kyberaccess.com/photos/vis_abc123_thumb.jpg"
}
]
}
}
Trigger Lockdown
POST /api/v1/emergency/lockdown
Request Body:
{
"location_id": "loc_001",
"reason": "Security threat",
"notify_all": true
}
Warning: This endpoint triggers immediate lockdown and sends emergency notifications to all staff. Use with caution.
Troubleshooting
| Issue | Solution | |-------|----------| | 404 on visitor endpoint | Verify the visitor ID is correct. The visitor may
have been deleted. | | Screening results not included | Screening may be disabled for your account. Enable it under
Settings → Security. | | Pre-registration invite not sent | Verify the visitor's email is provided and send_invite is
true. | | Check-in returns 409 Conflict | The visitor is already checked in. Check them out first. | | Photo URLs
returning 403 | Photo URLs expire after 24 hours. Fetch the visitor record again for fresh URLs. |