API Documentation

Overview

The WAQTUM API provides full programmatic access to all platform features. All requests and responses use JSON format.

Base URL: https://waqtum.qantrah.com/api/v1

Health Check: GET /api/v1/health Public

Authentication

All protected endpoints require your API key and secret in the Authorization header:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET
Content-Type: application/json
Accept: application/json

You can generate API keys from your dashboard at /admin/api

Rate Limiting

Requests are rate-limited per API key based on your plan:

Plan	Limit
Basic	100 requests/minute
Business	300 requests/minute
Enterprise	1000 requests/minute

When exceeded, a 429 (Too Many Requests) error is returned.

Documents

GET /documents List documents

Optional parameters:

`status`	draft, pending, in_progress, approved, rejected, expired, voided
`page`	Page number
`per_page`	Results per page (default: 15)

GET /documents/{id} Get document

Returns document details with approvers and status.

POST /documents Create document

Required fields:

`title_ar`	string	Arabic title
`title_en`	string	English title
`file`	file (PDF)	PDF file (max 20MB)
`department`	string	Department
`workflow_type`	string	sequential \| parallel

PUT /documents/{id} Update document

Update document (only documents in draft status).

DELETE /documents/{id} Delete document

Delete document (only documents in draft status).

POST /documents/{id}/send Send for approval

Send document to approval workflow and notify approvers.

POST /documents/{id}/void Void document

Void a sent document (notifies approvers).

GET /documents/{id}/status Document status

Returns current document status and approval progress.

GET /documents/{id}/download Download document

Download the final approved file (PDF).

Approvers

GET /documents/{documentId}/approvers List approvers

POST /documents/{documentId}/approvers Add approver

`name_ar`	string	Arabic name
`name_en`	string	English name
`phone`	string	Phone number (WhatsApp)
`role_ar`	string	Job title (Arabic)
`role_en`	string	Job title (English)
`action_type`	string	sign \| stamp \| approve_only \| review_only
`order_index`	integer	Approval order (for sequential)

PUT /approvers/{id} Update approver

DELETE /approvers/{id} Delete approver

POST /approvers/{id}/remind Send reminder

Resend WhatsApp notification to the approver.

Webhooks

Receive real-time notifications when events occur in the system.

Available Events

Event	Description
`document.created`	When a new document is created
`document.sent`	When a document is sent for approval
`document.approved`	When a document is fully approved
`document.rejected`	When a document is rejected
`approver.completed`	When an approver completes their action

Webhook Management

GET /webhooks/events Available events

GET /webhooks List webhooks

POST /webhooks Create webhook

`url`	string	URL to receive notifications
`events`	array	List of events to subscribe to

POST /webhooks/{id}/test Test webhook

POST /webhooks/{id}/rotate-secret Rotate secret

Signature Verification

An HMAC-SHA256 signature is sent in the header of each webhook request:

X-Waqtum-Signature: sha256=HMAC_HASH

// Verification (PHP):
$hash = hash_hmac('sha256', $payload, $webhookSecret);
$valid = hash_equals($hash, $signatureFromHeader);

Error Codes

Code	Description
`400`	Bad Request — check parameters
`401`	Unauthorized — invalid API key
`403`	Forbidden — no permission for this action
`404`	Not Found — resource does not exist
`422`	Validation Error — invalid data
`429`	Too Many Requests — rate limit exceeded
`500`	Server Error — contact support

Response Format

{
    "success": false,
    "error": {
        "code": 422,
        "message": "Validation failed",
        "details": {
            "title_ar": ["The title_ar field is required."]
        }
    }
}

Contents