Skip to main content

API Reference - Technical Documentation

**⚠️ Technical Documentation**: This reference is for developers and technical integrators. API a...

Etienne Champagne avatar
Written by Etienne Champagne
Updated over 6 months ago

API Reference - Technical Documentation

⚠️ Technical Documentation: This reference is for developers and technical integrators. API access requires special authorization.

API Overview

Authentication and Access

API Access Levels

  • Read-Only: Data retrieval for reporting and analytics

  • Limited Write: Specific operations like customer creation and unit updates

  • Full Access: Complete platform functionality through API

  • Webhook Integration: Real-time notifications for system events

Authentication Methods

  • API Key Authentication: Server-to-server communication

  • OAuth 2.0: User-delegated access with scopes

  • JWT Tokens: Stateless authentication for client applications

  • Webhook Signatures: Secure webhook verification

Rate Limiting and Usage

Standard Rate Limits

  • Read Operations: 1000 requests/hour per API key

  • Write Operations: 500 requests/hour per API key

  • Bulk Operations: 100 requests/hour per API key

  • Real-time Operations: 10 requests/minute per endpoint

Rate Limit Headers

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200
X-RateLimit-Window: 3600

Core API Endpoints

Authentication Endpoints

Get API Token

http
POST /api/v1/auth/token
Content-Type: application/json{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials",
    "scope": "read write"
}Response:
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write"
}

Refresh Token

http
POST /api/v1/auth/refresh
Authorization: Bearer {access_token}Response:
{
    "access_token": "new_token_here",
    "expires_in": 3600
}

Facility Management

List Facilities

http
GET /api/v1/facilities
Authorization: Bearer {access_token}Response:
{
    "data": [
        {
            "id": "fac_123456789",
            "name": "Downtown Storage",
            "address": {
                "street": "123 Main St",
                "city": "Toronto",
                "province": "ON",
                "postal_code": "M5V 3A8",
                "country": "CA"
            },
            "contact": {
                "phone": "+1-416-555-0123",
                "email": "[email protected]"
            },
            "status": "active",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-15T10:30:00Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1,
        "per_page": 50
    }
}

Get Facility Details

http
GET /api/v1/facilities/{facility_id}
Authorization: Bearer {access_token}Response:
{
    "id": "fac_123456789",
    "name": "Downtown Storage",
    "address": {
        "street": "123 Main St",
        "city": "Toronto",
        "province": "ON",
        "postal_code": "M5V 3A8",
        "country": "CA"
    },
    "contact": {
        "phone": "+1-416-555-0123",
        "email": "[email protected]"
    },
    "business_hours": {
        "monday": "09:00-18:00",
        "tuesday": "09:00-18:00",
        "wednesday": "09:00-18:00",
        "thursday": "09:00-18:00",
        "friday": "09:00-18:00",
        "saturday": "09:00-17:00",
        "sunday": "10:00-16:00"
    },
    "tax_configuration": {
        "gst_rate": 0.05,
        "pst_rate": 0.08,
        "gst_number": "123456789RT0001",
        "pst_number": "PST-1234567"
    },
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
}

Unit Management

List Units

http
GET /api/v1/facilities/{facility_id}/units
Authorization: Bearer {access_token}
Query Parameters:status: available|occupied|maintenance|reserved
unit_type_id: filter by unit type
limit: number of results (default: 50, max: 200)
offset: pagination offsetResponse:
{
    "data": [
        {
            "id": "unit_987654321",
            "unit_number": "A101",
            "unit_type": {
                "id": "utype_456789123",
                "name": "Medium 10x10",
                "dimensions": {
                    "width": 10,
                    "length": 10,
                    "height": 8,
                    "square_feet": 100
                },
                "monthly_rate": 150.00,
                "security_deposit": 150.00
            },
            "status": "available",
            "access_code": "4567",
            "last_occupied": null,
            "created_at": "2024-01-15T11:00:00Z",
            "updated_at": "2024-01-15T11:00:00Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "total_count": 250,
        "per_page": 50
    }
}

Update Unit Status

http
PATCH /api/v1/facilities/{facility_id}/units/{unit_id}
Authorization: Bearer {access_token}
Content-Type: application/json{
    "status": "maintenance",
    "notes": "Cleaning and minor repairs",
    "access_code": "new_code_1234"
}Response:
{
    "id": "unit_987654321",
    "unit_number": "A101",
    "status": "maintenance",
    "notes": "Cleaning and minor repairs",
    "access_code": "new_code_1234",
    "updated_at": "2024-08-17T15:30:00Z"
}

Customer Management

List Customers

http
GET /api/v1/facilities/{facility_id}/customers
Authorization: Bearer {access_token}
Query Parameters:search: search by name, email, or phone
status: active|inactive
limit: number of results
offset: pagination offsetResponse:
{
    "data": [
        {
            "id": "cust_135792468",
            "first_name": "John",
            "last_name": "Smith",
            "email": "[email protected]",
            "phone": "4165551234",
            "language": "en",
            "address": {
                "street": "456 Oak Avenue",
                "city": "Toronto",
                "province": "ON",
                "postal_code": "M4K 1B2",
                "country": "CA"
            },
            "active_rentals": [
                {
                    "unit_id": "unit_987654321",
                    "unit_number": "A101",
                    "move_in_date": "2024-06-01",
                    "monthly_rate": 150.00,
                    "status": "active"
                }
            ],
            "created_at": "2024-06-01T09:00:00Z",
            "updated_at": "2024-06-01T09:00:00Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 10,
        "total_count": 500,
        "per_page": 50
    }
}

Create Customer

http
POST /api/v1/facilities/{facility_id}/customers
Authorization: Bearer {access_token}
Content-Type: application/json{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "4165555678",
    "language": "en",
    "address": {
        "street": "789 Pine Street",
        "city": "Toronto",
        "province": "ON",
        "postal_code": "M5H 2N2",
        "country": "CA"
    }
}Response:
{
    "id": "cust_246813579",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "4165555678",
    "language": "en",
    "address": {
        "street": "789 Pine Street",
        "city": "Toronto",
        "province": "ON",
        "postal_code": "M5H 2N2",
        "country": "CA"
    },
    "active_rentals": [],
    "created_at": "2024-08-17T16:00:00Z",
    "updated_at": "2024-08-17T16:00:00Z"
}

Booking Management

Create Booking

http
POST /api/v1/facilities/{facility_id}/bookings
Authorization: Bearer {access_token}
Content-Type: application/json{
    "customer_id": "cust_246813579",
    "unit_id": "unit_987654321",
    "move_in_date": "2024-09-01",
    "payment_method": {
        "type": "credit_card",
        "token": "pm_1234567890abcdef"
    },
    "promotional_code": "FIRST_MONTH_FREE"
}Response:
{
    "id": "book_369258147",
    "customer_id": "cust_246813579",
    "unit_id": "unit_987654321",
    "unit_number": "A101",
    "move_in_date": "2024-09-01",
    "monthly_rate": 150.00,
    "security_deposit": 150.00,
    "promotion_applied": {
        "code": "FIRST_MONTH_FREE",
        "discount_amount": 150.00,
        "description": "First month free"
    },
    "total_due_today": 150.00,
    "status": "confirmed",
    "created_at": "2024-08-17T16:15:00Z"
}

Payment Processing

List Invoices

http
GET /api/v1/facilities/{facility_id}/invoices
Authorization: Bearer {access_token}
Query Parameters:customer_id: filter by customer
status: pending|paid|overdue|failed
date_from: YYYY-MM-DD
date_to: YYYY-MM-DDResponse:
{
    "data": [
        {
            "id": "inv_159753468",
            "customer_id": "cust_135792468",
            "invoice_number": "INV-2024-001234",
            "issue_date": "2024-08-01",
            "due_date": "2024-08-05",
            "status": "paid",
            "line_items": [
                {
                    "description": "Monthly Rent - Unit A101",
                    "amount": 150.00,
                    "tax_amount": 19.50,
                    "total": 169.50
                }
            ],
            "subtotal": 150.00,
            "tax_total": 19.50,
            "total_amount": 169.50,
            "payment_date": "2024-08-03T10:30:00Z",
            "created_at": "2024-08-01T00:00:00Z"
        }
    ]
}

Process Payment

http
POST /api/v1/facilities/{facility_id}/invoices/{invoice_id}/payments
Authorization: Bearer {access_token}
Content-Type: application/json{
    "payment_method": "cash",
    "amount": 169.50,
    "notes": "Cash payment received at front desk"
}Response:
{
    "id": "pay_753159468",
    "invoice_id": "inv_159753468",
    "amount": 169.50,
    "payment_method": "cash",
    "status": "completed",
    "processed_at": "2024-08-17T16:45:00Z",
    "notes": "Cash payment received at front desk"
}

Webhook Integration

Webhook Events

Available Events

  • booking.created - New booking created

  • booking.confirmed - Booking confirmed with payment

  • booking.cancelled - Booking cancelled

  • payment.processed - Payment successfully processed

  • payment.failed - Payment processing failed

  • invoice.created - New invoice generated

  • customer.created - New customer account created

  • unit.status_changed - Unit status updated

Webhook Configuration

Register Webhook Endpoint

http
POST /api/v1/webhooks
Authorization: Bearer {access_token}
Content-Type: application/json{
    "url": "https://your-app.com/webhooks/stortech",
    "events": [
        "booking.created",
        "payment.processed",
        "payment.failed"
    ],
    "secret": "your_webhook_secret"
}Response:
{
    "id": "hook_864297531",
    "url": "https://your-app.com/webhooks/stortech",
    "events": [
        "booking.created",
        "payment.processed", 
        "payment.failed"
    ],
    "status": "active",
    "created_at": "2024-08-17T17:00:00Z"
}

Webhook Payload Examples

Booking Created Event

json
{
    "event": "booking.created",
    "timestamp": "2024-08-17T17:15:00Z",
    "facility_id": "fac_123456789",
    "data": {
        "booking": {
            "id": "book_369258147",
            "customer_id": "cust_246813579",
            "unit_id": "unit_987654321",
            "unit_number": "A101",
            "move_in_date": "2024-09-01",
            "monthly_rate": 150.00,
            "status": "confirmed"
        }
    }
}

Payment Failed Event

json
{
    "event": "payment.failed",
    "timestamp": "2024-08-17T17:20:00Z",
    "facility_id": "fac_123456789",
    "data": {
        "payment": {
            "id": "pay_failed_123",
            "invoice_id": "inv_159753468",
            "customer_id": "cust_135792468",
            "amount": 169.50,
            "failure_reason": "insufficient_funds",
            "failure_code": "card_declined"
        }
    }
}

Error Handling

HTTP Status Codes

Success Codes

  • 200 OK - Request successful

  • 201 Created - Resource created successfully

  • 202 Accepted - Request accepted for processing

  • 204 No Content - Successful request with no response body

Client Error Codes

  • 400 Bad Request - Invalid request format or parameters

  • 401 Unauthorized - Invalid or missing authentication

  • 403 Forbidden - Insufficient permissions

  • 404 Not Found - Resource not found

  • 422 Unprocessable Entity - Validation errors

  • 429 Too Many Requests - Rate limit exceeded

Server Error Codes

  • 500 Internal Server Error - Server-side error

  • 502 Bad Gateway - Upstream service error

  • 503 Service Unavailable - Service temporarily unavailable

Error Response Format

json
{
    "error": {
        "code": "validation_error",
        "message": "The request contains invalid data",
        "details": [
            {
                "field": "email",
                "message": "Invalid email format"
            },
            {
                "field": "phone",
                "message": "Phone number must be 10 digits"
            }
        ],
        "request_id": "req_abc123def456"
    }
}

SDKs and Client Libraries

Official SDKs

Node.js/JavaScript

bash
npm install @stortech/api-client

javascript
const Stortech = require('@stortech/api-client');const client = new Stortech({
    apiKey: 'your_api_key',
    environment: 'production' // or 'sandbox'
});// List facilities
const facilities = await client.facilities.list();// Create customer
const customer = await client.customers.create('fac_123', {
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]',
    phone: '4165551234'
});

Python

bash
pip install stortech-python

python
import stortechclient = stortech.Client(
    api_key='your_api_key',
    environment='production'
)List unitsunits = client.units.list(facility_id='fac_123')Update unit statusclient.units.update('fac_123', 'unit_456', {
    'status': 'maintenance'
})

Third-Party Integrations

Zapier Integration

  • Pre-built triggers and actions

  • No-code automation workflows

  • Popular app integrations

Make (Integromat) Integration

  • Visual workflow builder

  • Advanced data transformation

  • Enterprise automation features

Rate Limiting and Performance

Optimization Best Practices

Batch Operations

  • Use bulk endpoints when available

  • Minimize API calls through data aggregation

  • Implement request batching strategies

Caching Strategies

  • Cache frequently accessed data

  • Implement conditional requests with ETags

  • Use webhook events to invalidate caches

Pagination Handling

javascript
// Efficient pagination
async function getAllCustomers(facilityId) {
    let customers = [];
    let page = 1;
    let hasMore = true;
    
    while (hasMore) {
        const response = await client.customers.list(facilityId, {
            page: page,
            limit: 100
        });
        
        customers = customers.concat(response.data);
        hasMore = response.pagination.current_page < response.pagination.total_pages;
        page++;
    }
    
    return customers;
}

Security Best Practices

API Key Management

Security Guidelines

  • Store API keys securely (environment variables, key management services)

  • Rotate API keys regularly

  • Use different keys for different environments

  • Monitor API key usage and detect anomalies

Webhook Security

Signature Verification

javascript
const crypto = require('crypto');function verifyWebhookSignature(payload, signature, secret) {
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expectedSignature)
    );
}

Data Protection

PII Handling

  • Minimize personal data collection and storage

  • Implement data encryption for sensitive information

  • Follow data retention policies

  • Comply with privacy regulations (GDPR, PIPEDA)

Testing and Development

Sandbox Environment

Sandbox Access

  • Test API integration without affecting live data

  • Separate API keys for sandbox environment

  • Reset sandbox data as needed

  • Full feature parity with production

Test Data

  • Pre-populated test facilities and customers

  • Test payment methods and scenarios

  • Simulated webhook events

  • Error condition testing

Development Tools

API Explorer

  • Interactive API documentation

  • Test API calls directly from documentation

  • Code generation for multiple languages

  • Response schema validation

Postman Collection

  • Pre-configured API requests

  • Environment variables for easy switching

  • Test scripts and assertions

  • Team collaboration features

---

For API Access: Contact [email protected] with "API Access Request" in the subject line to begin the approval process.

Related Articles
Detailed Stripe Connect Guide - Technical Documentation
Advanced Tax Configuration - Technical Documentation
Did this answer your question?