Users API

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

5 endpointsBase URL https://api.spirestock.com/api/v1

Every request needs an API key or a session token. Last updated .

On this page (5)

GEThttps://api.spirestock.com/api/v1/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.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

tabstring
primary, secondary or employee
typestring
Without tab: distributor, retailer, super_stockist, employee or driver
statusnumber
1 active (default without tab), 0 inactive; empty for all
searchstring
Name, store, SAP id, email or phone
role_idnumber
Role
town_idnumber
Town
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 20, max 100 (larger values are clamped)
Example request
curl "https://api.spirestock.com/api/v1/users?tab=primary&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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
  }
}

POSThttps://api.spirestock.com/api/v1/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

kindstring
primary (distributor) or employee
first_namestringrequired
First name
last_namestringrequired
Last name
primary_contact_numberstringrequired
Mobile number
store_namestring
Required for kind primary
official_emailstring
Required without kind; receives the invite
emp_sap_idstring
SAP id (unique)
role_idnumber
Role; for kind primary a Distributor or Super Stockist role sets is_distributor / is_super_stockist
town_idnumber
Area allocation
documentsobject
{ aadhaar_card, pan_card, cin, gstin, fssai }
Example request
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
{
  "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": "[email protected]",
    "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
}

GEThttps://api.spirestock.com/api/v1/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

idnumberrequired
User id
Example request
curl https://api.spirestock.com/api/v1/users/44663 \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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"
  }
}

GEThttps://api.spirestock.com/api/v1/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.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

role_idnumber
The role being assigned; limits options to its reporting role
searchstring
Case-insensitive contains on first name, last name, SAP id or role name; max 100 characters, % and _ match literally
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 50, max 100 (larger values are clamped)
Example request
curl "https://api.spirestock.com/api/v1/users/reporting-options?search=sales&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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
  }
}

GEThttps://api.spirestock.com/api/v1/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).

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

typestring
distributor, retailer or employee
user_typestring
1 is an alias of type=employee
production_unit_idnumber
Only users whose basic details name this plant
searchstring
Case-insensitive contains on first name, last name, store name, SAP id or phone; max 100 characters, % and _ match literally
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 50, max 100 (larger values are clamped)
Example request
curl "https://api.spirestock.com/api/v1/helpers/users?type=employee&search=sample" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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
    }
  ]
}