Requests & RITM API

Endpoints Overview

Method	Path	Description
GET	/prod/api/requests	List service requests
GET	/prod/api/requests/:id	Get service request
POST	/prod/api/requests	Submit new service request
PATCH	/prod/api/requests/:id	Update request
GET	/prod/api/requests/:id/items	List RITM items on request
GET	/prod/api/ritm/:id	Get single RITM item
PATCH	/prod/api/ritm/:id	Update RITM item state
POST	/prod/api/ritm/:id/approve	Approve RITM (approver role)
POST	/prod/api/ritm/:id/reject	Reject RITM (approver role)

List Requests

curl -H "Authorization: Bearer $TOKEN"   "https://your-instance.stackflow-tech.com/prod/api/requests?state=pending_approval&limit=25"

Get Request

{
  "id": "REQ0000789",
  "catalog_item_id": "cat_item_laptop_pro",
  "short_description": "Request for MacBook Pro 16" M4",
  "state": "pending_approval",
  "requested_by": "bob.jones@example.com",
  "requested_for": "bob.jones@example.com",
  "items": [
    {"id": "RITM0001001", "catalog_item": "MacBook Pro 16 M4", "quantity": 1, "state": "pending_approval"}
  ],
  "approvals": [
    {"approver": "manager@example.com", "state": "pending", "due_at": "2026-05-21T17:00:00Z"}
  ],
  "created_at": "2026-05-19T10:00:00Z"
}

Submit Service Request

curl -X POST   https://your-instance.stackflow-tech.com/prod/api/requests   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{
    "catalog_item_id": "cat_item_vpn_access",
    "requested_for": "newuser@example.com",
    "variables": {
      "vpn_region": "us-east-1",
      "access_level": "standard",
      "justification": "Remote work from home office"
    }
  }'

RITM Items

Each service request can have one or more RITM (Request Item) records, one per catalog item ordered. RITM items are fulfilled independently and may have different assignment groups and approval chains.

# Get a specific RITM
curl -H "Authorization: Bearer $TOKEN"   https://your-instance.stackflow-tech.com/prod/api/ritm/RITM0001001

# Update RITM state (fulfiller)
curl -X PATCH   https://your-instance.stackflow-tech.com/prod/api/ritm/RITM0001001   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"state": "in_fulfillment", "work_note": "Ordered from vendor, ETA 3 business days"}'

Approval State Machine

RITM States:
  pending_approval → approved → in_fulfillment → fulfilled → closed
  pending_approval → rejected → cancelled
  in_fulfillment → on_hold → in_fulfillment
  in_fulfillment → cancelled

Approval workflow (multi-stage):
  Stage 1: Direct manager approval (auto-assigned based on org chart)
  Stage 2: Department head (if cost > $1000)
  Stage 3: Finance approval (if cost > $5000)
  
  Each stage has a configurable SLA (default: 48 hours per stage)

Field Reference

Field	Type	Description
catalog_item_id	string	Service catalog item ID (required)
requested_for	string	Email of user the request is for
variables	object	Catalog item form variables (key-value)
state	enum	draft, submitted, pending_approval, approved, in_fulfillment, fulfilled, closed, cancelled, rejected
approvals	array	Approval chain with approver, state, due_at