Skip to content

Quick Start

Make your first API call in minutes.

Prerequisites

  • A Knosc account with at least Procurement / View privilege
  • Your company subdomain (e.g., acme for acme.knosc.com)
  • An HTTP client (curl, Python requests, Postman, etc.)

Base URLs

Environment URL
Production https://{company}.knosc.com/api
Test https://{company}.knosc.io/api

All examples below use acme.knosc.com - replace with your own subdomain.

Step 1 - Authenticate

curl -c cookies.txt -X POST https://acme.knosc.com/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "you@acme.com", "password": "your-password"}'

-c cookies.txt saves the session cookies (access token, refresh token, CSRF tokens) for reuse.

If 2FA is enabled, you will receive {"requires_2fa": true}. Submit your TOTP code:

curl -c cookies.txt -X POST https://acme.knosc.com/api/verify-2fa \
  -H "Content-Type: application/json" \
  -d '{"username": "you@acme.com", "totp_code": "123456"}'

Step 2 - List Purchase Orders

curl -b cookies.txt https://acme.knosc.com/api/purchase-order

{
  "data": {
    "rows": [
      {
        "id": 42,
        "PO List Number": "PO-2024-001",
        "Supplier Name": "Acme Components Ltd.",
        "PO List Document Status": "Open",
        "PO List Quantity": 500
      }
    ]
  }
}

Step 3 - Get a Purchase Order

curl -b cookies.txt https://acme.knosc.com/api/purchase-order/42

Step 4 - Create a Purchase Order

State-modifying requests require the X-XSRF-TOKEN header:

CSRF=$(grep csrf_access_token cookies.txt | awk '{print $NF}')

curl -b cookies.txt -X POST https://acme.knosc.com/api/purchase-order \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
    "PO List Number": "PO-2024-100",
    "PO List Document Status": "Open",
    "PO List Order Date": "2024-03-15",
    "Supplier Number": "SUP-007",
    "Purchase Order Id": null,
    "details": [
      {
        "Item Number": "ITEM-A",
        "Warehouse Number": "WH-01",
        "Ship From Number": "SF-01",
        "PO Details Quantity": 100,
        "PO Details Document Status": "Open",
        "PO Details Order Date": "2024-03-15",
        "PO Details Ship Date": "2024-03-22",
        "PO Details ETA Date": "2024-03-28"
      }
    ]
  }'

Python Example

import requests

BASE = "https://acme.knosc.com"
session = requests.Session()

# 1 - Authenticate
r = session.post(f"{BASE}/api/authenticate", json={
    "username": "you@acme.com",
    "password": "your-password"
})
assert r.json().get("login"), f"Login failed: {r.json()}"

csrf = session.cookies.get("csrf_access_token")

# 2 - List POs
pos = session.get(f"{BASE}/api/purchase-order").json()["data"]["rows"]
print(f"{len(pos)} purchase orders found")

# 3 - Get details for the first PO
po = session.get(f"{BASE}/api/purchase-order/{pos[0]['id']}").json()

# 4 - Create a new PO
r = session.post(
    f"{BASE}/api/purchase-order",
    headers={"X-XSRF-TOKEN": csrf},
    json={
        "PO List Number": "PO-2024-200",
        "PO List Document Status": "Open",
        "Supplier Number": "SUP-007",
        "Purchase Order Id": None,
        "details": [{
            "Item Number": "ITEM-A",
            "Warehouse Number": "WH-01",
            "Ship From Number": "SF-01",
            "PO Details Quantity": 50,
            "PO Details Document Status": "Open"
        }]
    }
)
print(r.json())

Test Environment

Use the .knosc.io subdomain to run against your test environment:

curl -c cookies.txt -X POST https://acme.knosc.io/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "you@acme.com", "password": "your-test-password"}'

Data in the test environment is isolated from production.

Next Steps