---
title: "Masters API — SpireStock REST API"
description: "Read and maintain the geography and logistics masters orders depend on: states, zones, towns, routes with their towns, and mobile app versions."
source: https://developers.spirestock.com/api-reference/masters
---

# Masters API

Read and maintain the geography and logistics masters orders depend on: states, zones, towns, routes with their towns, and mobile app versions.

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 /masters/states](https://developers.spirestock.com/api-reference/masters#get-masters-states)
- [GET /masters/zones](https://developers.spirestock.com/api-reference/masters#get-masters-zones)
- [GET /masters/towns](https://developers.spirestock.com/api-reference/masters#get-masters-towns)
- [GET /masters/routes](https://developers.spirestock.com/api-reference/masters#get-masters-routes)
- [POST /masters/routes](https://developers.spirestock.com/api-reference/masters#post-masters-routes)
- [GET /masters/app-versions](https://developers.spirestock.com/api-reference/masters#get-masters-app-versions)

## GET /masters/states

States with GST state code and the inter-state flag. Master lists return the full set (no pagination). POST creates, PUT /masters/states/{id} updates (a rename cascades to zones, towns, routes and cities). For India (the default country_id) POST needs a valid GST `state_code` and any `state` name must match that code (e.g. 08 is Rajasthan) — otherwise 400; other countries take a free-text name. There is no DELETE.

Access: API key `read` scope; staff need Master list (27) — list.

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 14,
      "organization_id": 6,
      "country_id": 1,
      "country_name": "India",
      "state": "State A",
      "state_code": "23",
      "inter_state": 0,
      "createdAt": "2021-10-07T10:21:57.000Z",
      "updatedAt": "2022-03-26T13:16:39.000Z"
    }
  ]
}
```

## GET /masters/zones

Zones with their towns (town_ids, town_names).

Access: API key `read` scope; staff need Master list (27) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `state_id` | number | no | State |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 12,
      "organization_id": 6,
      "state_id": 14,
      "state_name": "State A",
      "zone": "North Zone",
      "createdAt": "2021-10-20T06:51:33.000Z",
      "updatedAt": "2022-03-26T13:16:46.000Z",
      "town_ids": [
        392
      ],
      "town_names": "Town L, Town C, Town M"
    }
  ]
}
```

## GET /masters/towns

Towns, filterable by state and zone.

Access: API key `read` scope; staff need Master list (27) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `state_id` | number | no | State |
| `zone_id` | string | no | Zone id or comma-separated list |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 486,
      "organization_id": 6,
      "zone_id": 12,
      "zone_name": "North Zone",
      "state_id": 14,
      "state_name": "State A",
      "town": "Town P",
      "createdAt": "2024-04-03T11:22:41.000Z",
      "updatedAt": "2024-04-03T11:22:41.000Z"
    }
  ]
}
```

## GET /masters/routes

Routes with their plant and ordered towns. Route towns are managed through the towns array on POST /masters/routes and PUT /masters/routes/{id}; PATCH /masters/routes/{id}/status activates or deactivates a route.

Access: API key `read` scope; staff need Master list (27) or Vehicle Management (23) or Driver Registration (24) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `state_id` | number | no | State |
| `production_unit_id` | number | no | Plant |
| `status` | number | no | 1 active, 0 inactive |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 96,
      "organization_id": 6,
      "state_id": 14,
      "state_name": "State A",
      "route": "Route C",
      "route_code": "R0019",
      "production_unit_id": 17,
      "status": 1,
      "createdAt": "2022-12-28T08:21:35.000Z",
      "updatedAt": "2022-12-28T08:21:35.000Z",
      "production_unit_name": "North Plant",
      "towns": [
        {
          "town_id": 423,
          "town_name": "Town R",
          "order_index": 1
        }
      ],
      "town_names": "Town R"
    }
  ]
}
```

## POST /masters/routes

Create a route. towns replaces the route's town list; unknown towns are dropped. Names and codes are unique (409).

Access: API key `write` scope; staff need Master list (27) — add.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `route` | string | yes | Route name |
| `route_code` | string | no | Unique code |
| `state_id` | number | yes | State |
| `production_unit_id` | number | no | Plant |
| `towns` | array | no | [{ town_id, order_index }] |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/masters/routes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "route": "Route C",
    "route_code": "R0019",
    "state_id": 14,
    "production_unit_id": 17,
    "towns": [
      {
        "town_id": 423,
        "order_index": 1
      }
    ]
  }'
```

**Example response**

```json
{
  "response_code": 201,
  "message": "Record has been saved successfully.",
  "data": {
    "id": 97,
    "route": "Route C",
    "route_code": "R0019",
    "state_id": 14,
    "state_name": "State A",
    "production_unit_id": 17,
    "status": 1,
    "organization_id": 6,
    "updatedAt": "2026-10-22T09:02:36.863Z",
    "createdAt": "2026-10-22T09:02:36.863Z"
  }
}
```

## GET /masters/app-versions

Latest mobile-app version per app type in data, plus every version (versions) and the app types (app_types).

Access: API key `read` scope; staff need Master list (27) — list.

**Example request**

```bash
curl https://api.spirestock.com/api/v1/masters/app-versions \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "app_type_id": 26,
      "app_type": "Superstockist",
      "version": "-",
      "app_file": "",
      "description": "-",
      "created_on_date": null,
      "version_id": null
    }
  ],
  "versions": [
    {
      "id": 81,
      "organization_id": 6,
      "version": "0.0.6",
      "app_type_id": 27,
      "app_type": "Distributor",
      "app_file": "media/app_files/1648300847.apk",
      "description": "",
      "status": "0",
      "created_on_date": "2022-03-26T13:20:47.000Z",
      "createdAt": "2022-03-26T13:20:48.000Z",
      "updatedAt": "2022-03-26T13:20:48.000Z"
    }
  ],
  "app_types": [
    {
      "id": 26,
      "organization_id": 6,
      "app_type": "Superstockist",
      "createdAt": "2021-11-03T06:13:07.000Z",
      "updatedAt": "2022-03-26T13:16:37.000Z"
    }
  ]
}
```
