---
title: "Users API — SpireStock REST API"
description: "Manage distributors, retailers and employees. Create users, assign roles and territories, and list the people attached to a workspace."
source: https://developers.spirestock.com/api-reference/users
---

# Users API

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

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [GET /users](https://developers.spirestock.com/api-reference/users#get-users)
- [POST /users](https://developers.spirestock.com/api-reference/users#post-users)
- [GET /users/{id}](https://developers.spirestock.com/api-reference/users#get-users-id)
- [GET /users/reporting-options](https://developers.spirestock.com/api-reference/users#get-users-reporting-options)
- [GET /helpers/users](https://developers.spirestock.com/api-reference/users#get-helpers-users)

## GET /users

List users. Use tab for the user-management tabs — primary (distributors, user_type 2), secondary (retailers, 3), employee (staff, 0 and 1) — or the older type filter. Rows include role, basic details, contact person, outstanding_amount and platform (App, Web or -).

Access: API key `read` scope; staff need Manage Users (3) or Create User (4) — list.

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tab` | string | no | primary, secondary or employee |
| `type` | string | no | Without tab: distributor, retailer, super_stockist, employee or driver |
| `status` | number | no | 1 active (default without tab), 0 inactive; empty for all |
| `search` | string | no | Name, store, SAP id, email or phone |
| `role_id` | number | no | Role |
| `town_id` | number | no | Town |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 20, max 100 (larger values are clamped) (default 20) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/users?tab=primary&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 51850,
      "salutation": "Mr",
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User",
      "store_name": "Demo Store F",
      "store_image": null,
      "official_email": null,
      "primary_contact_number": "9876500003",
      "emp_sap_id": "CUST-018",
      "organization_id": 6,
      "organization_name": "Demo Dairy",
      "department_id": 131,
      "department_name": "Sales and Marketing",
      "role_id": 396,
      "role_name": "Distributor",
      "reporting_to_id": null,
      "reporting_to_name": "",
      "reporting_to_emp_id": null,
      "profile_image": null,
      "device_id": null,
      "last_login": null,
      "last_auth_method": null,
      "auth_methods_used": [],
      "onboarding_state": null,
      "last_ip": null,
      "status": 1,
      "user_type": 2,
      "is_distributor": 1,
      "is_super_stockist": 0,
      "is_retailer": 0,
      "is_tagged": 0,
      "tagged_by": null,
      "tagged_date": null,
      "periphery": null,
      "timing": null,
      "latitude": null,
      "longitude": null,
      "self_owned": 0,
      "other_brand_id": null,
      "other_brand_name": null,
      "retailer_type_id": null,
      "retailer_class_type_id": null,
      "purchase_milk_from_org": 0,
      "visit_date_time": null,
      "created_by": null,
      "oauth_provider": null,
      "portal_onboarding_completed_at": null,
      "app_version": null,
      "createdAt": "2024-06-11T12:38:40.000Z",
      "updatedAt": "2024-06-11T12:40:24.000Z",
      "sp_role": {
        "id": 396,
        "role_name": "Distributor"
      },
      "basicDetails": {
        "id": 51824,
        "organization_id": 6,
        "user_id": 51850,
        "father_name": "Sample Parent",
        "mother_name": "Sample Parent",
        "date_of_birth": "1990-01-01",
        "gender": "male",
        "blood_group": "",
        "aadhaar_nubmer": "000000000000",
        "pan_number": "AAAAA0000A",
        "cin": "U00000AA2020PTC000001",
        "gstin": "22AAAAA0000A1Z5",
        "fssai": "10000000000001",
        "working_shift_id": 10,
        "working_shift_name": "Morning",
        "order_timing": "18:08",
        "date_of_joining": "2024-06-11",
        "personal_email": null,
        "outlet_owned": null,
        "outstanding_amount": 0,
        "security_amount": 0,
        "opening_crates": null,
        "production_unit_id": "17",
        "tcs_applicable": 0,
        "tcs_value": 0,
        "per_crate_incentive": 0,
        "leave_count": null,
        "week_of_day": null,
        "status": 1,
        "createdAt": "2024-06-11T12:38:40.000Z",
        "updatedAt": "2024-06-11T12:40:24.000Z"
      },
      "contact_person": "Sample Contact",
      "outstanding_amount": 0,
      "platform": "-"
    }
  ],
  "pagination": {
    "total": 307,
    "page": 1,
    "limit": 1,
    "total_pages": 307
  }
}
```

## POST /users

Create a user. kind primary creates a distributor (store_name required); kind employee a staff member. Contact numbers, contact persons, addresses, basic details (plants, credit limit, security amount), area (zone_id, town_id, route_id) and KYC documents (aadhaar_card, pan_card, cin, gstin, fssai) are accepted in the same call. Without a password, an invite email valid for 7 days is sent. Distributors get the product catalogue mapped automatically (mapped_variants). For kind primary the is_distributor / is_super_stockist flags follow role_id (a Distributor or Super Stockist role) unless sent explicitly; without either they stay 0 and the customer cannot sign in to the customer portal. data is the full user record (never the password). Fires user.created.

Access: API key `write` scope; staff need Manage Users (3) or Create User (4) — add (never on administrator accounts).

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | primary (distributor) or employee |
| `first_name` | string | yes | First name |
| `last_name` | string | yes | Last name |
| `primary_contact_number` | string | yes | Mobile number |
| `store_name` | string | no | Required for kind primary |
| `official_email` | string | no | Required without kind; receives the invite |
| `emp_sap_id` | string | no | SAP id (unique) |
| `role_id` | number | no | Role; for kind primary a Distributor or Super Stockist role sets is_distributor / is_super_stockist |
| `town_id` | number | no | Area allocation |
| `documents` | object | no | { aadhaar_card, pan_card, cin, gstin, fssai } |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/users \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "primary",
    "first_name": "Sample",
    "last_name": "User",
    "store_name": "Demo Store E",
    "primary_contact_number": "9876543210",
    "emp_sap_id": "CUST-019",
    "role_id": 396,
    "zone_id": 12,
    "town_id": 427,
    "route_id": 82
  }'
```

**Example response**

```json
{
  "response_code": 201,
  "message": "User created",
  "data": {
    "auth_methods_used": [],
    "is_tagged": 0,
    "self_owned": 0,
    "purchase_milk_from_org": 0,
    "id": 51900,
    "first_name": "Sample",
    "last_name": "User",
    "store_name": "Demo Store E",
    "emp_sap_id": "CUST-019",
    "primary_contact_number": "9876543210",
    "role_id": 396,
    "role_name": "Distributor",
    "is_distributor": 1,
    "is_super_stockist": 0,
    "official_email": "user@example.com",
    "user_type": 2,
    "organization_id": 6,
    "organization_name": "Demo Dairy",
    "is_retailer": 0,
    "status": 1,
    "created_by": 41500,
    "updatedAt": "2026-10-22T10:59:00.364Z",
    "createdAt": "2026-10-22T10:59:00.364Z",
    "salutation": null,
    "middle_name": null,
    "store_image": null,
    "department_id": null,
    "department_name": null,
    "reporting_to_id": null,
    "reporting_to_name": null,
    "reporting_to_emp_id": null,
    "profile_image": null,
    "device_id": null,
    "last_login": null,
    "last_auth_method": null,
    "onboarding_state": null,
    "last_ip": null,
    "tagged_by": null,
    "tagged_date": null,
    "periphery": null,
    "timing": null,
    "latitude": null,
    "longitude": null,
    "other_brand_id": null,
    "other_brand_name": null,
    "retailer_type_id": null,
    "retailer_class_type_id": null,
    "visit_date_time": null,
    "oauth_provider": null,
    "portal_onboarding_completed_at": null,
    "app_version": null
  },
  "mapped_variants": 48
}
```

## GET /users/{id}

One user with role, basic details, addresses, contact numbers and persons, KYC documents, area allocations and plant names. Users in another workspace give 404.

Access: API key `read` scope; staff need Manage Users (3) — view.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | number | yes | User id |

**Example request**

```bash
curl https://api.spirestock.com/api/v1/users/44663 \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "id": 44663,
    "salutation": "Mr",
    "first_name": "Sample",
    "middle_name": "",
    "last_name": "User",
    "store_name": "Demo Store F",
    "store_image": "https://media.example.com/sample.png",
    "official_email": null,
    "primary_contact_number": "9876500003",
    "emp_sap_id": "CUST-011",
    "organization_id": 6,
    "organization_name": "Demo Dairy",
    "department_id": 131,
    "department_name": "Sales and Marketing ",
    "role_id": 396,
    "role_name": "Distributor",
    "reporting_to_id": null,
    "reporting_to_name": "",
    "reporting_to_emp_id": null,
    "profile_image": null,
    "device_id": "sample-device-0001",
    "last_login": null,
    "last_auth_method": null,
    "auth_methods_used": [],
    "onboarding_state": null,
    "last_ip": null,
    "status": 1,
    "user_type": 2,
    "is_distributor": 1,
    "is_super_stockist": 0,
    "is_retailer": 0,
    "is_tagged": 0,
    "tagged_by": null,
    "tagged_date": null,
    "periphery": null,
    "timing": null,
    "latitude": null,
    "longitude": null,
    "self_owned": 0,
    "other_brand_id": null,
    "other_brand_name": null,
    "retailer_type_id": null,
    "retailer_class_type_id": null,
    "purchase_milk_from_org": 0,
    "visit_date_time": null,
    "created_by": null,
    "oauth_provider": null,
    "portal_onboarding_completed_at": null,
    "app_version": null,
    "createdAt": "2023-05-02T06:24:43.000Z",
    "updatedAt": "2024-06-11T05:25:25.000Z",
    "sp_role": {
      "id": 396,
      "role_name": "Distributor",
      "reporting_role_id": 395
    },
    "basicDetails": {
      "id": 44637,
      "organization_id": 6,
      "user_id": 44663,
      "father_name": "Sample Parent",
      "mother_name": "Sample Parent",
      "date_of_birth": "1990-01-01",
      "gender": "male",
      "blood_group": "",
      "aadhaar_nubmer": "000000000000",
      "pan_number": "AAAAA0000A",
      "cin": "U00000AA2020PTC000001",
      "gstin": "22AAAAA0000A1Z5",
      "fssai": "10000000000001",
      "working_shift_id": 10,
      "working_shift_name": "Morning",
      "order_timing": "14:00",
      "date_of_joining": "2023-05-02",
      "personal_email": null,
      "outlet_owned": null,
      "outstanding_amount": 0,
      "security_amount": 0,
      "opening_crates": null,
      "production_unit_id": "17",
      "tcs_applicable": 0,
      "tcs_value": 0,
      "per_crate_incentive": 0,
      "leave_count": null,
      "week_of_day": null,
      "status": 1,
      "createdAt": "2023-05-02T06:24:44.000Z",
      "updatedAt": "2023-12-29T07:46:39.000Z"
    },
    "addresses": [
      {
        "id": 46921,
        "organization_id": 6,
        "user_id": 44663,
        "type": "correspondence",
        "address_line_1": "Plot 1, Industrial Area, Town A",
        "address_line_2": "",
        "country_id": 6,
        "country_name": "India",
        "state_id": 14,
        "state_name": "State A",
        "city_id": 363,
        "city_name": "Town A",
        "pincode": "100001",
        "createdAt": "2023-12-29T07:46:23.000Z",
        "updatedAt": "2023-12-29T07:46:23.000Z"
      }
    ],
    "contactNumbers": [
      {
        "id": 44850,
        "organization_id": 6,
        "user_id": 44663,
        "country_code": "+91",
        "contact_type": 14,
        "contact_type_name": "Home",
        "contact_number": "9876500020",
        "is_primary": 1,
        "status": 1,
        "createdAt": "2023-12-29T07:46:23.000Z",
        "updatedAt": "2023-12-29T07:46:23.000Z"
      }
    ],
    "contactPersons": [
      {
        "id": 1490,
        "organization_id": 6,
        "user_id": 44663,
        "contact_person_name": "",
        "designation": "",
        "contact_number": "",
        "status": 1,
        "createdAt": "2023-12-29T07:46:23.000Z",
        "updatedAt": "2023-12-29T07:46:23.000Z"
      }
    ],
    "documents": {
      "id": 2075,
      "organization_id": 6,
      "user_id": 44663,
      "aadhaar_card": null,
      "pan_card": null,
      "cin": null,
      "gstin": null,
      "fssai": null,
      "createdAt": "2023-05-02T06:27:19.000Z",
      "updatedAt": "2023-12-29T07:46:41.000Z"
    },
    "areaAllocations": [
      {
        "id": 48048,
        "organization_id": 6,
        "user_id": 44663,
        "state_id": 14,
        "state_name": "State A",
        "zone_id": 12,
        "zone_name": "Zone A",
        "town_id": 464,
        "town_name": "Town A",
        "route_id": 82,
        "route_name": "Route A",
        "createdAt": "2023-05-02T06:25:42.000Z",
        "updatedAt": "2023-12-29T07:46:39.000Z"
      }
    ],
    "platform": "-",
    "has_device": true,
    "production_unit_names": "North Plant"
  }
}
```

## GET /users/reporting-options

Staff (user_type 0 or 1) a user can report to, for the reporting-to picker. With role_id, only users of that role's reporting role. Sorted by first name, then id.

Access: API key `read` scope; staff need Manage Users (3) or Create User (4) — list.

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `role_id` | number | no | The role being assigned; limits options to its reporting role |
| `search` | string | no | Case-insensitive contains on first name, last name, SAP id or role name; max 100 characters, % and _ match literally |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 50, max 100 (larger values are clamped) (default 50) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/users/reporting-options?search=sales&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 44223,
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User A",
      "role_name": "RSM",
      "emp_sap_id": "EMP-001",
      "name": "Sample User A"
    }
  ],
  "pagination": {
    "total": 87,
    "page": 1,
    "limit": 2,
    "total_pages": 44
  }
}
```

## GET /helpers/users

Search-as-you-type user picker over active users. Customer pickers (thousands of retailers) should search rather than page. Field staff without a user-management grant only see their reporting tree and the customers allocated to their towns that they created. Sorted by first name, then id.

Access: API key `read` scope; staff need Manage Users (3) or Create User (4) or Orders (8) or Order Grievance Request (11) or Amount to be paid (12) or Product and Variant Management (17) or Manage Schemes (20) or Vehicle Management (23) or Driver Registration (24) or Manage Leaves (38) or FOC Management (39) or Bulk Notifications (40) or Crate Summary (41) or User Crate Summary (42) — list (without it, only their own records).

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | distributor, retailer or employee |
| `user_type` | string | no | 1 is an alias of type=employee |
| `production_unit_id` | number | no | Only users whose basic details name this plant |
| `search` | string | no | Case-insensitive contains on first name, last name, store name, SAP id or phone; max 100 characters, % and _ match literally |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 50, max 100 (larger values are clamped) (default 50) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/helpers/users?type=employee&search=sample" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "pagination": {
    "total": 82,
    "page": 1,
    "limit": 2,
    "total_pages": 41
  },
  "data": [
    {
      "id": 44223,
      "name": "Sample User A",
      "first_name": "Sample",
      "last_name": "User A",
      "store_name": null,
      "emp_sap_id": "EMP-001",
      "primary_contact_number": "9876500010",
      "user_type": 1,
      "is_distributor": 0,
      "is_retailer": 0,
      "is_super_stockist": 0
    }
  ]
}
```
