Approvals & Permissions API

List what is waiting for approval, forward, approve or decline orders, leave and FOC in bulk, read an approval trail, and inspect the permission workflow behind it.

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

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

On this page (7)

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

Records waiting on the caller (workspace admins see everything at status 1 or 2), with pending counts and the caller's level per type. Types: order, leave, foc, merged into one list newest first (orders by order_date) with id as the tie-break; summary counts every pending record, not just the page.

Access: API key read scope; staff need Orders (8) or Manage Leaves (38) or FOC Management (39) — list.

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

Parameters

typestring
order, leave or foc
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/approvals \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 334097,
      "type": "order",
      "module": "Orders",
      "status": 2,
      "status_label": "Forwarded",
      "created_at": "2024-03-25T12:00:52.000Z",
      "title": "Order ORD0062581",
      "subtitle": "Sample User A — Rs.19,520"
    }
  ],
  "summary": {
    "pending_orders": 1988,
    "pending_leaves": 0,
    "pending_foc": 0,
    "total": 1988
  },
  "levels": {
    "order": 3,
    "leave": 3,
    "foc": 3
  },
  "is_admin": true,
  "pagination": {
    "total": 1988,
    "page": 2,
    "limit": 2,
    "total_pages": 994
  }
}

GEThttps://api.spirestock.com/api/v1/approvals/{type}/{id}/trail

Who initiated a record, who acted at each level, and who is still pending.

Access: API key read scope; staff need Orders (8) or Manage Leaves (38) or FOC Management (39) — list.

Parameters

typestringrequired
order, leave or foc
idnumberrequired
Record id
Example request
curl https://api.spirestock.com/api/v1/approvals/order/339403/trail \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "type": "order",
    "id": 339403,
    "code": "ORD0001004",
    "status": 1,
    "status_label": "Initiated",
    "approvers": [],
    "history": {
      "initiated": {
        "by": "Sample User AE",
        "at": "2024-06-12T13:30:50.000Z"
      },
      "steps": [],
      "pending": []
    }
  }
}

POSThttps://api.spirestock.com/api/v1/approvals/{type}/action

Forward, approve or decline up to 500 records. Levels come from the workspace's permission workflow: rank 2 Forward, rank 3 Approve. Admins can approve at any point; others act only at their own level, and approve waits until Forward is done. Orders cannot be declined. With several ids the response is 200 with a result per record.

Access: API key write scope; by type: order — Orders (8) — edit; leave — Manage Leaves (38) — edit; foc — FOC Management (39) — edit.

Parameters

typestringrequired
order, leave or foc

Request body

idsarrayrequired
1-500 record ids
actionstringrequired
forward, approve or decline
remarkstring
Shown in the trail
Example request
curl -X POST https://api.spirestock.com/api/v1/approvals/order/action \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      339403,
      338021
    ],
    "action": "approve",
    "remark": "OK"
  }'
Example response
{
  "response_code": 200,
  "message": "1 updated, 1 failed",
  "data": [
    {
      "id": 339403,
      "ok": true,
      "status": 3,
      "status_label": "Approved",
      "waiting": false
    },
    {
      "id": 338021,
      "ok": false,
      "code": 400,
      "error": "Order is already approved"
    }
  ]
}

GEThttps://api.spirestock.com/api/v1/approvals/my-level

The caller's approval level per type: 0 not an approver, 2 Forward, 3 Approve (admins get 3).

Access: API key read scope; staff need Orders (8) or Manage Leaves (38) or FOC Management (39) — list.

Example request
curl https://api.spirestock.com/api/v1/approvals/my-level \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "is_admin": true,
    "levels": {
      "order": 3,
      "leave": 3,
      "foc": 3
    }
  }
}

GEThttps://api.spirestock.com/api/v1/settings/my-permissions

The caller's effective sub-module grants, workflow levels and what they can do per approval type. Staff routes are default-deny: a route with no rule in the permission table is admin-only.

Access: API key read scope; any staff user, for their own records.

Example request
curl https://api.spirestock.com/api/v1/settings/my-permissions \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "is_admin": true,
    "grants": [],
    "workflow_levels": {
      "order": 3,
      "leave": 3,
      "foc": 3
    },
    "can": {
      "order": {
        "list": true,
        "edit": true
      },
      "leave": {
        "list": true,
        "edit": true
      },
      "foc": {
        "list": true,
        "edit": true
      }
    }
  }
}

GEThttps://api.spirestock.com/api/v1/settings/permission-workflows

The approval workflow matrix: levels (Initiate, Forward, Approve) and, per sub-module and permission, which roles sit at each level. Writing it (PUT) needs a signed-in admin; API keys are refused.

Access: API key read scope; staff need Manage Permission Workflows (33) — list.

Example request
curl https://api.spirestock.com/api/v1/settings/permission-workflows \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "levels": [
      {
        "id": 14,
        "level": "Initiate",
        "rank": 1
      },
      {
        "id": 15,
        "level": "Forward",
        "rank": 2
      }
    ],
    "cells": [
      {
        "sub_module_id": 1,
        "permission_id": 1,
        "levels": [
          {
            "level_id": 14,
            "rank": 1,
            "description": "can",
            "role_ids": [
              416
            ]
          }
        ]
      }
    ]
  }
}

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

Active employees with a role, for the FOC request filter. Sorted by first name, then id.

Access: API key read scope; staff need FOC Management (39) — list.

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

Parameters

searchstring
Case-insensitive contains on first name, last name or SAP id; 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/foc/users?search=sample" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 44223,
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User A",
      "emp_sap_id": "EMP-001",
      "name": "Sample User A"
    }
  ],
  "pagination": {
    "total": 82,
    "page": 1,
    "limit": 2,
    "total_pages": 41
  }
}