HeskAPI Documentation

Quick Start

Authentication

Every request to the HeskAPI requires an API key. Generate and manage keys from the HeskAPI admin panel inside HESK (Admin → HeskAPI Manager).

Pass the key via HTTP header (recommended):

X-HESK-API-Key: your_api_key_here

Or via query parameter:

GET /api/v1/?action=list_tickets&key=your_api_key_here

API keys can be rotated at any time from the admin panel without downtime.

Rate Limiting

HeskAPI enforces configurable per-key rate limits using atomic database counters.

When the limit is exceeded the API returns HTTP 429 with a JSON error body. Configure the limit per API key from the admin panel.

Endpoints

Returns a paginated list of HESK tickets.

Full-text search across ticket subjects and messages.

Creates a new HESK ticket. Supports multipart/form-data for file attachments and triggers native HESK email notifications. When email verification is enabled (see below), the ticket is held and this endpoint returns HTTP 202 instead of creating it immediately.

HTTP 202 Accepted
{"success":true,"data":{"status":"pending_verification","email":"[email protected]"}}

HTTP 202 Accepted
{"success":true,"data":{"status":"pending_verification","method":"code","confirmation_id":"a1b2…","expires_in_hours":72}}

Updates fields on an existing ticket (status, priority, category, or custom fields).

Posts a staff reply to a ticket. Triggers native HESK customer email notification.

Marks a ticket as resolved.

The browser-facing confirmation link emailed to a submitter when email verification is enabled. No API key — the single-use token is the credential. Clicking it creates the held ticket, then shows a confirmation page (or redirects to the admin-configured success URL). Expired or already-used links show a friendly message. You never call this directly; it is the link embedded in the confirmation email.

Confirms a submission created under the 6-digit code verification method and creates the held ticket. API key required. Submit the confirmation_id returned by create_ticket together with the code the sender received by email; on success it returns the created ticket exactly like create_ticket. The code is single-use and attempts are capped (the row is discarded after too many wrong tries).

Error Codes

All error responses include a JSON body: {"status":"error","code":"...","message":"..."}

Code Examples

PHP — List tickets

$ch = curl_init('https://yoursite.com/hesk/api/v1/?action=list_tickets');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-HESK-API-Key: your_api_key_here'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

PHP — Create ticket

$ch = curl_init('https://yoursite.com/hesk/api/v1/?action=create_ticket');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => [
        'name'    => 'Jane Smith',
        'email'   => '[email protected]',
        'subject' => 'Login issue',
        'message' => 'I cannot log in since yesterday.',
        'category' => 1, // required: target HESK category ID
        'client_ip' => $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $_SERVER['REMOTE_ADDR'], // real end-user IP
    ],
    CURLOPT_HTTPHEADER => ['X-HESK-API-Key: your_api_key_here'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch) — List tickets

const res = await fetch('https://yoursite.com/hesk/api/v1/?action=list_tickets', {
    headers: { 'X-HESK-API-Key': 'your_api_key_here' },
});
const data = await res.json();