---
title: "Approvals & Permissions API — SpireStock REST API"
description: "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."
source: https://developers.spirestock.com/api-reference/approvals
---

# 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.

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 /approvals](https://developers.spirestock.com/api-reference/approvals#get-approvals)
- [GET /approvals/{type}/{id}/trail](https://developers.spirestock.com/api-reference/approvals#get-approvals-type-id-trail)
- [POST /approvals/{type}/action](https://developers.spirestock.com/api-reference/approvals#post-approvals-type-action)
- [GET /approvals/my-level](https://developers.spirestock.com/api-reference/approvals#get-approvals-my-level)
- [GET /settings/my-permissions](https://developers.spirestock.com/api-reference/approvals#get-settings-my-permissions)
- [GET /settings/permission-workflows](https://developers.spirestock.com/api-reference/approvals#get-settings-permission-workflows)
- [GET /foc/users](https://developers.spirestock.com/api-reference/approvals#get-foc-users)

## GET /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.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | order, leave or foc |
| `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/approvals \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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
  }
}
```

## GET /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes | order, leave or foc |
| `id` | number | yes | Record id |

**Example request**

```bash
curl https://api.spirestock.com/api/v1/approvals/order/339403/trail \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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": []
    }
  }
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes | order, leave or foc |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ids` | array | yes | 1-500 record ids |
| `action` | string | yes | forward, approve or decline |
| `remark` | string | no | Shown in the trail |

**Example request**

```bash
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**

```json
{
  "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"
    }
  ]
}
```

## GET /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**

```bash
curl https://api.spirestock.com/api/v1/approvals/my-level \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "is_admin": true,
    "levels": {
      "order": 3,
      "leave": 3,
      "foc": 3
    }
  }
}
```

## GET /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**

```bash
curl https://api.spirestock.com/api/v1/settings/my-permissions \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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
      }
    }
  }
}
```

## GET /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**

```bash
curl https://api.spirestock.com/api/v1/settings/permission-workflows \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "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
            ]
          }
        ]
      }
    ]
  }
}
```

## GET /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.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | no | Case-insensitive contains on first name, last name or SAP id; 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/foc/users?search=sample" \
  -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",
      "emp_sap_id": "EMP-001",
      "name": "Sample User A"
    }
  ],
  "pagination": {
    "total": 82,
    "page": 1,
    "limit": 2,
    "total_pages": 41
  }
}
```
