Comprehensive helpdesk and ticketing system API for customer support management

Introduction

The Answer API provides a complete helpdesk and ticketing system solution. It enables you to manage support tickets, customer interactions, knowledge base articles, and team collaboration through a RESTful interface.

Authentication

The Answer API uses JWT Bearer tokens for authentication. Obtain a token by exchanging your API key credentials.

POST /v1/auth/token

Exchange API key for JWT authentication token.

Request Body

{
  "api_key": "your_api_key_here",
  "api_secret": "your_api_secret_here"
}

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Rate Limits

API requests are rate-limited based on your subscription tier:

Tier	Requests/Minute	Requests/Day
Free	30	1,000
Starter	60	10,000
Professional	120	100,000
Enterprise	Unlimited	Unlimited

Health Check

GET /health

Check API and service health status. No authentication required.

Response

{
  "status": "healthy",
  "timestamp": "2024-01-22T14:00:00Z",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "cache": "connected",
    "queue": "connected"
  }
}

Tickets

Manage support tickets with full CRUD operations, status management, assignments, and more.

GET /v1/tickets

Retrieve a paginated list of tickets with optional filtering and sorting.

Parameters

Parameter	Type	Description
page optional	integer	Page number (default: 1)
per_page optional	integer	Results per page (default: 20, max: 100)
status optional	string	Filter by status: open, pending, resolved, closed
priority optional	string	Filter by priority: low, medium, high, urgent
assigned_to optional	integer	Filter by assigned agent ID
category_id optional	integer	Filter by category ID
search optional	string	Search in subject and content
sort optional	string	Sort field: created_at, updated_at, priority
order optional	string	Sort order: asc, desc (default: desc)

Response

{
  "success": true,
  "data": [
    {
      "id": 1234,
      "subject": "Cannot login to my account",
      "content": "I've been trying to login but keep getting an error...",
      "status": "open",
      "priority": "high",
      "category": {
        "id": 5,
        "name": "Account Issues"
      },
      "requester": {
        "id": 101,
        "name": "John Doe",
        "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser."
      },
      "assigned_to": {
        "id": 15,
        "name": "Support Agent"
      },
      "tags": ["login", "authentication"],
      "reply_count": 3,
      "created_at": "2024-01-20T10:30:00Z",
      "updated_at": "2024-01-22T14:00:00Z",
      "first_response_at": "2024-01-20T11:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

POST /v1/tickets

Create a new support ticket.

Parameters

Field	Type	Description
subject required	string	Ticket subject (max: 255 chars)
content required	string	Ticket description/content
requester_email required	string	Email of the ticket requester
requester_name optional	string	Name of the requester
priority optional	string	low, medium, high, urgent (default: medium)
category_id optional	integer	Category ID to assign
assigned_to optional	integer	Agent ID to assign
tags optional	array	Array of tag strings
metadata optional	object	Custom metadata object

GET /v1/tickets/{id}

Retrieve a single ticket with all details including replies and attachments.

Parameters

Parameter	Type	Description
id required	integer	Ticket ID

Response

{
  "success": true,
  "data": {
    "id": 1234,
    "subject": "Cannot login to my account",
    "content": "I've been trying to login but keep getting an error...",
    "content_html": "<p>I've been trying to login...</p>",
    "status": "open",
    "priority": "high",
    "category": {
      "id": 5,
      "name": "Account Issues",
      "color": "#ff5722"
    },
    "requester": {
      "id": 101,
      "name": "John Doe",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "avatar_url": null
    },
    "assigned_to": {
      "id": 15,
      "name": "Support Agent",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser."
    },
    "watchers": [
      {"id": 16, "name": "Manager"}
    ],
    "tags": ["login", "authentication"],
    "replies": [
      {
        "id": 5001,
        "content": "Thank you for contacting us...",
        "author": {"id": 15, "name": "Support Agent"},
        "is_internal": false,
        "created_at": "2024-01-20T11:15:00Z"
      }
    ],
    "attachments": [
      {
        "id": 801,
        "filename": "screenshot.png",
        "file_size": 102400,
        "mime_type": "image/png",
        "url": "/v1/attachments/801/download"
      }
    ],
    "activity_log": [
      {
        "action": "status_changed",
        "from": "new",
        "to": "open",
        "user": {"id": 15, "name": "Support Agent"},
        "timestamp": "2024-01-20T11:00:00Z"
      }
    ],
    "metadata": {},
    "created_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-22T14:00:00Z",
    "first_response_at": "2024-01-20T11:15:00Z",
    "resolved_at": null
  }
}

PUT /v1/tickets/{id}

Update an existing ticket's properties.

Response

{
  "success": true,
  "data": {
    "id": 1234,
    "status": "pending",
    "priority": "urgent",
    "updated_at": "2024-01-22T16:00:00Z"
  },
  "message": "Ticket updated successfully"
}

DELETE /v1/tickets/{id}

Delete a ticket and all associated data (replies, attachments).

Response

{
  "success": true,
  "message": "Ticket deleted successfully"
}

Replies

Manage ticket replies including internal notes and customer-facing responses.

GET /v1/tickets/{ticket_id}/replies

List all replies for a specific ticket.

Parameters

Parameter	Type	Description
include_internal	boolean	Include internal notes (default: true for agents)

Response

{
  "success": true,
  "data": [
    {
      "id": 5001,
      "ticket_id": 1234,
      "content": "Thank you for contacting us. We're looking into this.",
      "content_html": "<p>Thank you for contacting us...</p>",
      "is_internal": false,
      "author": {
        "id": 15,
        "name": "Support Agent",
        "type": "agent"
      },
      "attachments": [],
      "created_at": "2024-01-20T11:15:00Z"
    },
    {
      "id": 5002,
      "ticket_id": 1234,
      "content": "[Internal] Escalating to engineering team",
      "is_internal": true,
      "author": {
        "id": 15,
        "name": "Support Agent",
        "type": "agent"
      },
      "created_at": "2024-01-21T09:00:00Z"
    }
  ]
}

POST /v1/tickets/{ticket_id}/replies

Add a reply to a ticket. Can be a public response or internal note.

Request Body

{
  "content": "Thank you for your patience. We've identified the issue and it should be resolved now.",
  "is_internal": false,
  "notify_requester": true,
  "update_status": "resolved"
}

Attachments

POST /v1/tickets/{ticket_id}/attachments

Upload an attachment to a ticket. Uses multipart/form-data encoding.

Parameters

Field	Type	Description
file required	file	File to upload (max: 10MB)

Response

{
  "success": true,
  "data": {
    "id": 802,
    "ticket_id": 1234,
    "filename": "error-log.txt",
    "original_filename": "error-log.txt",
    "file_size": 2048,
    "mime_type": "text/plain",
    "url": "/v1/attachments/802/download"
  }
}

GET /v1/attachments/{id}/download

Download an attachment file.

Users

Manage users including customers and support agents.

GET /v1/users

List all users with filtering options.

Parameters

Parameter	Type	Description
type	string	customer, agent, admin
search	string	Search by name or email
organization_id	integer	Filter by organization

Response

{
  "success": true,
  "data": [
    {
      "id": 101,
      "name": "John Doe",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "type": "customer",
      "organization": {
        "id": 50,
        "name": "Acme Corp"
      },
      "ticket_count": 5,
      "created_at": "2023-06-15T10:00:00Z"
    }
  ],
  "pagination": {...}
}

POST /v1/users

Create a new user.

Request Body

{
  "name": "Jane Smith",
  "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
  "type": "customer",
  "organization_id": 50,
  "phone": "+1234567890",
  "metadata": {
    "company_size": "50-100"
  }
}

Organizations

Manage customer organizations for grouping and reporting.

GET /v1/organizations

List all organizations.

Response

{
  "success": true,
  "data": [
    {
      "id": 50,
      "name": "Acme Corp",
      "domain": "acme.com",
      "user_count": 15,
      "ticket_count": 42,
      "created_at": "2023-01-10T08:00:00Z"
    }
  ]
}

POST /v1/organizations

Create a new organization.

Request Body

{
  "name": "Tech Solutions Inc",
  "domain": "techsolutions.com",
  "notes": "Enterprise customer",
  "metadata": {
    "plan": "enterprise",
    "account_manager": "John"
  }
}

Categories

Manage ticket categories for organization and routing.

GET /v1/categories

List all ticket categories.

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "General Inquiry",
      "slug": "general",
      "color": "#3b82f6",
      "parent_id": null,
      "ticket_count": 150
    },
    {
      "id": 5,
      "name": "Account Issues",
      "slug": "account",
      "color": "#ef4444",
      "parent_id": null,
      "ticket_count": 75
    }
  ]
}

POST /v1/categories

Create a new category.

Request Body

{
  "name": "Billing",
  "slug": "billing",
  "color": "#10b981",
  "parent_id": null,
  "description": "Billing and payment related issues"
}

Webhooks

Configure webhooks to receive real-time notifications for ticket events.

GET /v1/webhooks

List all configured webhooks.

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://example.com/webhooks/answer",
      "events": ["ticket.created", "ticket.updated", "reply.created"],
      "is_active": true,
      "secret": "whsec_****",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /v1/webhooks

Create a new webhook subscription.

Request Body

{
  "url": "https://your-app.com/webhooks/answer",
  "events": ["ticket.created", "ticket.updated", "reply.created"],
  "secret": "your_webhook_secret"
}

Statistics

Access comprehensive analytics and reporting data.

GET /v1/stats/overview

Get overview statistics for the helpdesk.

Parameters

Parameter	Type	Description
from_date	date	Start date (YYYY-MM-DD)
to_date	date	End date (YYYY-MM-DD)

Response

{
  "success": true,
  "data": {
    "tickets": {
      "total": 1500,
      "open": 45,
      "pending": 23,
      "resolved": 1200,
      "closed": 232
    },
    "response_times": {
      "average_first_response": 3600,
      "average_resolution": 86400,
      "sla_compliance": 94.5
    },
    "agent_performance": [
      {
        "agent_id": 15,
        "name": "Support Agent",
        "tickets_resolved": 150,
        "avg_response_time": 2800,
        "satisfaction_rating": 4.8
      }
    ],
    "by_category": [
      {"category": "Account Issues", "count": 350},
      {"category": "Billing", "count": 280},
      {"category": "Technical", "count": 420}
    ],
    "by_priority": {
      "low": 300,
      "medium": 800,
      "high": 350,
      "urgent": 50
    },
    "trends": {
      "daily_created": [...],
      "daily_resolved": [...]
    }
  }
}

GET /v1/stats/agents

Get detailed agent performance statistics.

Response

{
  "success": true,
  "data": [
    {
      "agent_id": 15,
      "name": "Support Agent",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "metrics": {
        "tickets_assigned": 200,
        "tickets_resolved": 180,
        "tickets_open": 20,
        "avg_first_response_time": 1800,
        "avg_resolution_time": 43200,
        "satisfaction_score": 4.8,
        "sla_compliance": 96.5
      },
      "activity": {
        "replies_sent": 450,
        "internal_notes": 120,
        "tickets_reassigned": 15
      }
    }
  ]
}

Error Codes

Code	Status	Description
UNAUTHORIZED	401	Invalid or missing authentication token
FORBIDDEN	403	Insufficient permissions for this action
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Request validation failed
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Internal server error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The subject field is required",
    "details": {
      "subject": ["This field is required"]
    }
  }
}