API Reference

Complete developer guide for integrating with the Loopdesk API, including authentication, endpoints, and code examples.

API Overview

Programmatic access to your helpdesk system for integration and automation

Introduction

The Loopdesk API provides programmatic access to your helpdesk system, enabling integration with external applications, automation of workflows, and custom application development.

API Capabilities

Core Features

Full CRUD operations on tickets, customers, and agents
Real-time webhook notifications
Custom field management
Advanced search and filtering
Bulk operations for efficiency
File upload and download

Integration Use Cases

CRM Integration: Sync customer data and tickets

Monitoring Tools: Auto-create tickets from alerts

Business Applications: Embed support functionality

Mobile Apps: Native mobile support applications

Automation: Custom workflow and business logic

Reporting: External analytics and dashboards

API Architecture

RESTful Design

• Standard HTTP methods (GET, POST, PUT, DELETE)
• JSON request and response format
• Stateless operations
• Resource-based URLs
• HTTP status codes for responses

API Versioning

• Current version: v1
• Version specified in URL path
• Backward compatibility commitment
• Deprecation notices for changes
• Migration guides for updates

Authentication

API Key Authentication

Obtaining API Keys

Navigate to Admin → Settings → API → API Keys

Click Create New API Key

Configure key settings and permissions

Key Configuration:

• Name: Descriptive identifier
• Permissions: Read, write, or admin access
• Rate Limits: Request throttling
• IP Restrictions: Whitelist specific addresses
• Expiration: Key validity period

Using API Keys

GET

/api/v1/tickets

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json

OAuth 2.0 Authentication

OAuth Flow (for user-context applications)

Authorization Request: Redirect user to OAuth endpoint

User Consent: User grants application access

Authorization Code: Receive temporary code

Access Token: Exchange code for access token

API Requests: Use token for authenticated requests

OAuth Configuration

// OAuth 2.0 Configuration

const

oauth_config = {

client_id: 'your_client_id',

client_secret: 'your_client_secret',

authorization_url: 'https://your-domain.loopdesk.ca/oauth/authorize',

token_url: 'https://your-domain.loopdesk.ca/oauth/token',

scope: 'tickets:read tickets:write customers:read'

};

Security

Store API keys securely and never expose them in client-side code. Use environment variables in production.

Tickets API

Complete CRUD operations for tickets including creation, retrieval, updates, and deletion

Ticket Operations

Create Ticket

POST /api/v1/tickets

Request Body:

{

"subject": "Unable to login to account",

"description": "Customer cannot access account",

"customer_id": 12345,

"department_id": 2,

"category_id": 5,

"priority": "high",

"status": "open"

}

Response:

{

"success": true,

"data": {

"id": 78901,

"number": "TKT-2025-001234",

"subject": "Unable to login...",

"status": "open",

"priority": "high"

}

Retrieve Ticket

GET /api/v1/tickets/{id}

Get detailed information about a specific ticket including all fields, comments, and history.

Update Ticket

PUT /api/v1/tickets/{id}

Modify ticket properties such as status, priority, assignment, or add comments and notes.

Delete Ticket

DELETE /api/v1/tickets/{id}

Permanently remove a ticket from the system. This action cannot be undone.

Additional Operations

Bulk Operations:

• POST /api/v1/tickets/bulk - Create multiple tickets
• PUT /api/v1/tickets/bulk - Update multiple tickets
• GET /api/v1/tickets/search - Advanced search

Ticket Actions:

• POST /api/v1/tickets/{id}/comments - Add comment
• POST /api/v1/tickets/{id}/attachments - Upload files
• PUT /api/v1/tickets/{id}/assign - Assign agent

Ticket Endpoints

Complete API reference for ticket management operations

Retrieve Ticket

Endpoint:

GET /api/v1/tickets/{ticket_id}

Response:

{
  "success": true,
  "data": {
    "id": 78901,
    "number": "TKT-2025-001234",
    "subject": "Unable to login to account",
    "description": "Customer cannot access their account after password reset",
    "status": "open",
    "priority": "high",
    "created_at": "2025-08-23T10:30:00Z",
    "updated_at": "2025-08-23T10:30:00Z",
    "due_date": "2025-08-24T18:00:00Z",
    "customer": {
      "id": 12345,
      "name": "John Smith",
      "email": "[email protected]",
      "organization": "Acme Corporation"
    },
    "assigned_agent": {
      "id": 567,
      "name": "Sarah Johnson",
      "email": "[email protected]"
    },
    "department": {
      "id": 2,
      "name": "Technical Support"
    },
    "category": {
      "id": 5,
      "name": "Login Issues"
    },
    "custom_fields": {
      "affected_product": "Web Application",
      "browser": "Chrome 119"
    },
    "tags": ["login", "password", "urgent"],
    "attachments": [
      {
        "id": 123,
        "filename": "error_screenshot.png",
        "size": 245760,
        "url": "https://api.loopdesk.ca/files/123/download"
      }
    ],
    "replies": [
      {
        "id": 456,
        "content": "Thank you for contacting support. We're investigating the login issue.",
        "author": {
          "type": "agent",
          "name": "Sarah Johnson"
        },
        "created_at": "2025-08-23T10:45:00Z"
      }
    ]
  }
}

Update Ticket

Endpoint:

PUT /api/v1/tickets/{ticket_id}

Request Body:

{
  "status": "resolved",
  "priority": "normal",
  "assigned_agent_id": 567,
  "internal_note": "Issue resolved by resetting password hash"
}

List Tickets

Endpoint:

GET /api/v1/tickets

Query Parameters:

• status: Filter by ticket status
• priority: Filter by priority level
• department_id: Filter by department
• assigned_agent_id: Filter by assigned agent
• customer_id: Filter by customer
• created_after: Filter by creation date
• updated_after: Filter by update date
• page: Page number for pagination
• per_page: Items per page (max 100)
• sort: Sort field (created_at, updated_at, priority)
• order: Sort order (asc, desc)

Example Request:

GET /api/v1/tickets?status=open&priority=high&page=1&per_page=25&sort=created_at&order=desc

Response:

{
  "success": true,
  "data": [
    {
      "id": 78901,
      "number": "TKT-2025-001234",
      "subject": "Unable to login to account",
      "status": "open",
      "priority": "high",
      "created_at": "2025-08-23T10:30:00Z",
      "customer": {
        "id": 12345,
        "name": "John Smith"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6,
    "has_next": true,
    "has_prev": false
  }
}

Ticket Replies

API endpoints for managing ticket communications and replies

Add Reply

Endpoint:

POST /api/v1/tickets/{ticket_id}/replies

Request Body:

{
  "content": "We've identified the issue and are working on a resolution. Expected fix time: 2 hours.",
  "type": "public",
  "author_type": "agent",
  "attachments": [
    {
      "filename": "solution_steps.pdf",
      "content": "base64_encoded_file_content"
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": 789,
    "content": "We've identified the issue and are working on a resolution.",
    "type": "public",
    "author": {
      "type": "agent",
      "id": 567,
      "name": "Sarah Johnson"
    },
    "created_at": "2025-08-23T11:15:00Z",
    "attachments": [
      {
        "id": 124,
        "filename": "solution_steps.pdf",
        "size": 102400,
        "url": "https://api.loopdesk.ca/files/124/download"
      }
    ]
  }
}

Customers API

Complete API reference for customer management operations

Customer Management

Create Customer

Endpoint:

POST /api/v1/customers

Request Body:

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "[email protected]",
  "phone": "+1-555-123-4567",
  "organization": "Acme Corporation",
  "department": "IT Department",
  "title": "System Administrator",
  "address": {
    "street": "123 Business Ave",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "United States"
  },
  "custom_fields": {
    "employee_id": "EMP-12345",
    "cost_center": "IT-001",
    "manager": "Jane Doe"
  },
  "preferences": {
    "language": "en",
    "timezone": "America/New_York",
    "email_notifications": true
  }
}

Response:

{
  "success": true,
  "data": {
    "id": 12346,
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+1-555-123-4567",
    "organization": "Acme Corporation",
    "status": "active",
    "created_at": "2025-08-23T12:00:00Z",
    "last_login": null,
    "ticket_count": 0
  }
}

Retrieve Customer

GET /api/v1/customers/{customer_id}

List Customers

GET /api/v1/customers

Query Parameters:

• organization: Filter by organization
• status: Filter by customer status
• created_after: Filter by creation date
• search: Search in name, email, organization

Update Customer

PUT /api/v1/customers/{customer_id}

Customer Tickets

GET /api/v1/customers/{customer_id}/tickets

Get all tickets for a specific customer.

Agents API

API endpoints for agent management and performance tracking

Agent Management

List Agents

Endpoint:

GET /api/v1/agents

Response:

{
  "success": true,
  "data": [
    {
      "id": 567,
      "first_name": "Sarah",
      "last_name": "Johnson",
      "email": "[email protected]",
      "role": "agent",
      "status": "active",
      "departments": [
        {
          "id": 2,
          "name": "Technical Support"
        }
      ],
      "skills": ["database", "web_development", "troubleshooting"],
      "availability": "available",
      "current_tickets": 8,
      "max_tickets": 15
    }
  ]
}

Agent Performance

Endpoint:

GET /api/v1/agents/{agent_id}/performance

Query Parameters:

• start_date: Performance period start
• end_date: Performance period end
• metrics: Specific metrics to include

Response:

{
  "success": true,
  "data": {
    "agent_id": 567,
    "period": {
      "start": "2025-08-01T00:00:00Z",
      "end": "2025-08-23T23:59:59Z"
    },
    "metrics": {
      "tickets_handled": 156,
      "tickets_resolved": 148,
      "average_response_time": "2.5 hours",
      "average_resolution_time": "8.2 hours",
      "customer_satisfaction": 4.7,
      "first_contact_resolution": 0.85,
      "reopened_tickets": 3
    }
    }
  }
}

Webhooks

Real-time event notifications for seamless integrations

Webhook Configuration

Setting Up Webhooks

Webhook Setup:

Navigate to Admin → Settings → Webhooks
Create new webhook:

• URL: Target endpoint URL

• Events: Select trigger events

• Secret: Optional signature validation

• Active: Enable/disable webhook

Supported Events:

• ticket.created
• ticket.updated
• ticket.resolved
• ticket.closed

• customer.created
• customer.updated
• agent.created
• ticket.assigned

Webhook Payload

Example Webhook Payload:

{
  "event": "ticket.created",
  "timestamp": "2025-08-23T12:30:00Z",
  "data": {
    "ticket": {
      "id": 78902,
      "number": "TKT-2025-001235",
      "subject": "New support request",
      "status": "open",
      "priority": "normal",
      "customer": {
        "id": 12345,
        "name": "John Smith",
        "email": "[email protected]"
      },
      "department": {
        "id": 2,
        "name": "Technical Support"
      }
    }
  },
  "signature": "sha256=a8b7c9d..."
}

Webhook Security & Examples

Security best practices and implementation examples for webhooks

Webhook Security

Signature Verification:

import hashlib
import hmac

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(
        f"sha256={expected_signature}",
        signature
    )

Webhook Examples

Node.js Webhook Handler:

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

Additional API Endpoints

Complete API coverage for customers, agents, webhooks, and system management

Customers API

POST /api/v1/customers

GET /api/v1/customers/{id}

PUT /api/v1/customers/{id}

DELETE /api/v1/customers/{id}

Agents API

POST /api/v1/agents

GET /api/v1/agents/{id}

PUT /api/v1/agents/{id}

GET /api/v1/agents/{id}/tickets

Webhooks

• Real-time event notifications
• Secure signature verification
• Configurable event types
• Automatic retry mechanism
• Delivery status tracking

Rate Limiting

• 1000 requests per hour
• Rate limit headers included
• Automatic throttling
• Burst request handling
• Premium tier upgrades

Error Handling

• Standard HTTP status codes
• Detailed error messages
• Error code categorization
• Retry recommendations
• Debug information

Quick Start Example

// JavaScript Example - Create a ticket

const

response = await fetch ( 'https://your-domain.loopdesk.ca/api/v1/tickets' , {

method: 'POST',

headers: {

'Authorization': 'Bearer YOUR_API_KEY',

'Content-Type': 'application/json'

body: JSON.stringify({

subject: 'API Test Ticket',

description: 'Created via API',

priority: 'medium'

})

});

const

ticket = await response. json ();

API Resources & Tools

API Documentation

Complete reference with interactive examples

SDK Libraries

Official libraries for popular programming languages

Postman Collection

Ready-to-use API collection for testing

Developer Support

Technical support and community forums

"retry_after": 900 }

Best Practices & Error Handling

Guidelines for optimal API usage and comprehensive error management

Best Practices

Monitor rate limit headers
Implement exponential backoff
Cache responses when possible
Use webhooks instead of polling
Optimize API calls for efficiency

Error Handling

HTTP Status Codes

Success Codes:

• 200 OK: Successful request
• 201 Created: Resource created successfully
• 204 No Content: Successful deletion

Client Error Codes:

• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded

Server Error Codes:

• 500 Internal Server Error: Server error
• 502 Bad Gateway: Service unavailable
• 503 Service Unavailable: Temporary unavailability

Error Response Format

Standard Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed for the request",
    "details": [
      {
        "field": "email",
        "message": "Email address is required"
      },
      {
        "field": "priority",
        "message": "Priority must be one of: low, normal, high, urgent"
      }
    ]
  }
}
```


API Integration Checklist



Generate and secure API keys
    "message": "Validation failed for the given input",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      },
      {
        "field": "priority",
        "message": "Priority must be one of: low, normal, high, urgent"
      }
    ]
  },
  "timestamp": "2025-08-23T12:30:00Z"
}

API Integration Checklist

Implement proper authentication

Add error handling and retry logic

Respect rate limits and implement backoff

Validate webhook signatures

Test all integration scenarios

Monitor API usage and performance

Document integration for maintenance

Set up monitoring and alerting

Reports & Analytics