Users API

Manage distributors, retailers and employees. Create users, assign roles and territories, and list the people attached to a workspace.

3 endpoints. Every request needs an API key or a session token — see Authentication. To send one of these calls from the browser, use the interactive reference.

GEThttps://api.spirestock.com/api/v1/users

List all users in the organization with pagination and type filtering. User types: 0 (admin), 1 (employee), 2 (distributor).

Parameters

page (number) — Page number (default: 1)
limit (number) — Items per page (default: 20, max: 100)
type (string) — Filter by type: admin, employee, distributor
search (string) — Search by name, email, or phone
status (number) — Filter by status: 1 (active), 0 (inactive)

Example request

curl "https://api.spirestock.com/api/v1/users?type=distributor&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example response

{
  "response_code": 200,
  "data": [
    {
      "id": 42,
      "first_name": "Rajesh",
      "last_name": "Gupta",
      "official_email": "[email protected]",
      "primary_contact_number": "+919876543210",
      "role_id": 3,
      "role_name": "Distributor",
      "user_type": 2,
      "status": 1,
      "store_name": "Gupta Dairy Store",
      "organization_id": 5,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "total_pages": 3
  }
}

POSThttps://api.spirestock.com/api/v1/users

Create a new user in the organization. User type determines their role in the system.

Request body

first_name (string)required — First name
last_name (string)required — Last name
official_email (string) — Email address
primary_contact_number (string)required — Phone number
password (string)required — Initial password
role_id (number)required — Role ID
user_type (number)required — User type: 0 (admin), 1 (employee), 2 (distributor)

Example request

curl -X POST https://api.spirestock.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Priya",
    "last_name": "Singh",
    "official_email": "[email protected]",
    "primary_contact_number": "+919123456789",
    "password": "secureP@ss123",
    "role_id": 3,
    "user_type": 2
  }'

Example response

{
  "response_code": 201,
  "message": "User created",
  "data": {
    "id": 100,
    "first_name": "Priya",
    "last_name": "Singh",
    "official_email": "[email protected]",
    "primary_contact_number": "+919123456789",
    "role_id": 3,
    "role_name": "Distributor",
    "user_type": 2,
    "status": 1,
    "organization_id": 5,
    "createdAt": "2026-06-01T11:00:00Z"
  }
}

GEThttps://api.spirestock.com/api/v1/users/{id}

Retrieve a single user profile by ID, including role and organization details.

Parameters

id (number)required — User ID (integer)

Example request

curl https://api.spirestock.com/api/v1/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example response

{
  "response_code": 200,
  "data": {
    "id": 42,
    "first_name": "Rajesh",
    "last_name": "Gupta",
    "official_email": "[email protected]",
    "primary_contact_number": "+919876543210",
    "role_id": 3,
    "role_name": "Distributor",
    "user_type": 2,
    "status": 1,
    "store_name": "Gupta Dairy Store",
    "organization_id": 5,
    "organization_name": "Acme Dairy",
    "profile_image": null,
    "latitude": "26.8467",
    "longitude": "80.9462",
    "createdAt": "2026-01-15T10:00:00Z"
  }
}