List Referrals (v1)

Method & Path

GET /api/v1/admin/referrals

Description

Retrieve admin referrals with pagination and search.

Backend path: /v1/admin/referrals

Authentication

Required: Admin authentication with businesses.manage permission.

Authorization: Bearer <admin_token>

Headers

Authorization: Bearer <admin_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20, max: 100)
search	string	No	Search by name or phone

Request Body

None.

Response 200 OK

{
  "referrals": [
    {
      "id": "65f1c1a2b3c4d5e6f7a8b901",
      "name": "Ahmed Ali",
      "phone": "0599123456",
      "sharePercentage": 10,
      "createdBy": "65aab1c2d3e4f5a6b7c8d901",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Common Errors

• 400 Bad Request: Invalid query parameters
• 401 Unauthorized: Missing or invalid admin authentication token
• 403 Forbidden: Insufficient permissions
• 500 Internal Server Error: Server error