Skip to main content

Getting Started with the VOLO API

Welcome to the VOLO Access Control API! This guide will help you get started with integrating your applications with the VOLO system.

Overview​

The VOLO API provides programmatic access to all features of the VOLO Access Control System. Everything that can be done through the VOLO web interface is also accessible through the API, enabling powerful third-party integrations and automation.

Prerequisites​

Before you begin, ensure you have:

  • A valid email address for application registration
  • Understanding of REST API concepts
  • Knowledge of JSON data format
  • HTTPS-capable client for making requests

Quick Start​

1. Register Your Application​

First, you need to register your application to receive an application token:

POST https://api.volo-access.com/v1/config/application
Content-Type: application/json

{
  "applicationName": "My Integration App",
  "applicationEmail": "developer@mycompany.com"
}

This will return your application token and connection limits.

2. Authenticate Your Requests​

All API requests require specific headers for authentication and security:

  • x-nonce-token: A unique, base64-encoded random string for each request (prevents replay attacks)
  • x-app-token: Your application token from registration
  • x-user-credential: Session token from user login (for user-specific operations)

3. Make Your First Request​

Here's an example of listing customers:

GET https://api.volo-access.com/v1/business/customer
x-nonce-token: MDU4ZmQ5Y2EtNTExNi00N2E0LWI0Y2EtNjM1YWRjZTZjYmNi
x-app-token: your-application-token-here
x-user-credential: your-session-token-here

Authentication Flow​

Application Authentication​

  1. Register your application to get an x-app-token
  2. Include this token in all requests that require application-level authentication
  3. Tokens are valid for one year by default

User Authentication​

  1. Use the login endpoint to authenticate a user
  2. Receive a session token in the response
  3. Include this token as x-user-credential for user-specific operations

Nonce Tokens​

Every request must include a unique x-nonce-token:

  • Generate a random string (e.g., GUID)
  • Base64 encode it
  • Use it only once per request
  • Valid for 10 minutes

API Structure​

The VOLO API is organized into several main categories:

  • Customer Management: Create and manage customers
  • Site Management: Manage sites within customers
  • User Management: Handle user accounts and permissions
  • Device Management: Control access control devices
  • Event Management: Monitor and retrieve system events
  • Report Management: Generate and schedule reports
  • License Management: Manage system licenses

Rate Limits​

  • Default: 10 simultaneous connections per application
  • Endpoint-specific: Some endpoints have per-minute rate limits
  • Exceeding limits: Returns 503 Service Unavailable
  • Circumvention: May result in API suspension

Error Handling​

The API uses standard HTTP status codes and returns consistent error responses:

{
  "applicationMessage": "Technical error details for developers",
  "consumerMessage": "User-friendly error message"
}

Common status codes:

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (authentication required)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found (resource doesn't exist)
  • 409: Conflict (duplicate resource)
  • 500: Internal Server Error
  • 503: Service Unavailable (rate limit exceeded)

Development Environment​

Base URLs​

  • Production: https://api.volo-access.com/v1
  • Staging: https://staging-api.gendis.co.uk/v1

Content Type​

All requests and responses use application/json

Character Encoding​

Use UTF-8 encoding for all text data

API Specification​

For complete API details, you can download the OpenAPI specification:

This specification can be imported into tools like:

  • Swagger UI - For interactive API documentation
  • Postman - For API testing and collection building
  • Insomnia - For API development and testing
  • Code generators - For generating client libraries

Next Steps​

  1. Read the Authentication Guide for detailed authentication information
  2. Review the Terms & Conditions before production use
  3. Explore the Endpoint Documentation for specific API operations
  4. Test your integration using the staging environment first

Support​

For technical support and questions:

Security Best Practices​

  • Keep your application tokens secure and never expose them in client-side code
  • Rotate tokens regularly
  • Use HTTPS for all API communications
  • Implement proper error handling in your applications
  • Monitor your API usage to stay within rate limits
  • Log and audit API access for security purposes