Users API

Complete reference for User management endpoints.

List Users

GET /v1/users

Query Parameters

Parameter	Type	Description
role	string	Filter by role slug or identifier (e.g. department_head, procurement_officer)
department_id	integer	Filter by department
status	string	Filter by status: active, inactive, invited
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 15, max: 100)
search	string	Search by name or email

Example Request

curl -X GET "https://api.waqti.sa/v1/users?status=active&department_id=2&per_page=20" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    {
      "id": 12,
      "name_en": "Sara Al-Mutairi",
      "name_ar": "سارة المطيري",
      "email": "sara.mutairi@acme.sa",
      "role": {
        "id": 3,
        "name": "Department Head"
      },
      "department": {
        "id": 2,
        "name": "Operations",
        "code": "OPS"
      },
      "status": "active",
      "two_factor_enabled": true,
      "last_login_at": "2026-04-03T08:15:00Z",
      "created_at": "2025-08-20T09:00:00Z"
    },
    {
      "id": 18,
      "name_en": "Omar Hassan",
      "name_ar": "عمر حسن",
      "email": "omar.hassan@acme.sa",
      "role": {
        "id": 5,
        "name": "Procurement Officer"
      },
      "department": {
        "id": 2,
        "name": "Operations",
        "code": "OPS"
      },
      "status": "invited",
      "two_factor_enabled": false,
      "last_login_at": null,
      "created_at": "2026-04-01T11:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 20,
    "total": 34
  }
}

Create User (Invite)

POST /v1/users

Creates a user record and sends an invitation email when the account is in invited status until first login.

Request Body

{
  "name_en": "Layla Al-Qahtani",
  "name_ar": "ليلى القحطاني",
  "email": "layla.qahtani@acme.sa",
  "role": "procurement_officer",
  "department_id": 2,
  "phone": "+966501234567"
}

Response

{
  "data": {
    "id": 24,
    "name_en": "Layla Al-Qahtani",
    "name_ar": "ليلى القحطاني",
    "email": "layla.qahtani@acme.sa",
    "role": {
      "id": 5,
      "name": "Procurement Officer"
    },
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "status": "invited",
    "two_factor_enabled": false,
    "last_login_at": null,
    "created_at": "2026-04-04T12:00:00Z"
  }
}

Get User

GET /v1/users/{id}

Returns full user profile for the given identifier.

Example Request

curl -X GET "https://api.waqti.sa/v1/users/12" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Response

{
  "data": {
    "id": 12,
    "name_en": "Sara Al-Mutairi",
    "name_ar": "سارة المطيري",
    "email": "sara.mutairi@acme.sa",
    "role": {
      "id": 3,
      "name": "Department Head"
    },
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "status": "active",
    "two_factor_enabled": true,
    "last_login_at": "2026-04-03T08:15:00Z",
    "created_at": "2025-08-20T09:00:00Z"
  }
}

Update User

PUT /v1/users/{id}

Request Body

{
  "name_en": "Sara Al-Mutairi",
  "name_ar": "سارة بنت عبدالله المطيري",
  "email": "sara.almutairi@acme.sa",
  "role": "department_head",
  "department_id": 4,
  "phone": "+966507654321"
}

Response

{
  "data": {
    "id": 12,
    "name_en": "Sara Al-Mutairi",
    "name_ar": "سارة بنت عبدالله المطيري",
    "email": "sara.almutairi@acme.sa",
    "role": {
      "id": 3,
      "name": "Department Head"
    },
    "department": {
      "id": 4,
      "name": "Finance",
      "code": "FIN"
    },
    "status": "active",
    "two_factor_enabled": true,
    "last_login_at": "2026-04-03T08:15:00Z",
    "created_at": "2025-08-20T09:00:00Z"
  }
}

Deactivate User

DELETE /v1/users/{id}

WARNING

Deactivation revokes access for the user. The record is retained for audit history; use an admin action or support process if a hard delete is required.

Example Request

curl -X DELETE "https://api.waqti.sa/v1/users/24" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Response

{
  "data": {
    "id": 24,
    "name_en": "Layla Al-Qahtani",
    "name_ar": "ليلى القحطاني",
    "email": "layla.qahtani@acme.sa",
    "role": {
      "id": 5,
      "name": "Procurement Officer"
    },
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "status": "inactive",
    "two_factor_enabled": false,
    "last_login_at": null,
    "created_at": "2026-04-04T12:00:00Z"
  }
}

Get Current User

GET /v1/users/me

Returns the authenticated user’s profile (same shape as Get User).

Example Request

curl -X GET "https://api.waqti.sa/v1/users/me" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Response

{
  "data": {
    "id": 7,
    "name_en": "Khalid Al-Rashid",
    "name_ar": "خالد الراشد",
    "email": "khalid.rashid@acme.sa",
    "role": {
      "id": 1,
      "name": "Tenant Administrator"
    },
    "department": {
      "id": 1,
      "name": "Executive",
      "code": "EXE"
    },
    "status": "active",
    "two_factor_enabled": true,
    "last_login_at": "2026-04-04T07:45:00Z",
    "created_at": "2024-01-10T14:20:00Z"
  }
}