Quick start
From nothing to a delivery declared and an event received. Every example uses curl; any language that speaks HTTPS and JSON works.
1. Get a token
A token belongs to one factory (one company on Prodaksha) and carries abilities that decide what it may do.
- The factory needs the API and webhooks module switched on, and a plan with API access.
- Ask the factory to request a token from the Prodaksha platform administrator. Say what it is for (for example "Society system") and which abilities it needs. For a supplier or society system that is usually
read,read:catalog,write:consignments,approve:statementsandadmin(to register webhooks). - The token is shown once. Keep it like a password: in a secret store, never in code or in a browser.
FPOBox is the exception: the factory creates the FPOBox token itself on its Supply → FPOBox link page.
For testing, ask for a test company on Prodaksha with the value chain you work with switched on, so you never touch a real factory's records.
export TOKEN="12|aBcD…" # the token you were given
export BASE="https://prodaksha.com/api/v1"
2. Check the connection
No token needed:
curl -s $BASE/health
{"success": true, "data": {"version": "1.0.0", "time": "2026-11-15T08:00:00+00:00", "migrations": {"applied": 169, "pending": 0}}, "message": "Success"}
3. Your first call
curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" $BASE/company
The answer names the factory, its country, currency, time zone and the modules it uses. A 401 means the token is wrong or revoked; a 403 means the token lacks the ability, or the factory's API module or subscription is off.
4. Read the factory's items
What you send must use the factory's item codes (or your own codes, once the factory has mapped them to its items).
curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" "$BASE/items?type=raw&limit=50"
Each value chain's usual codes are listed on its page under Value chains: for example COFFEE-PARCHMENT at a coffee dry mill, GREEN-LEAF at a tea factory.
5. Register a webhook
Your address must be https:// and answer 2xx within 10 seconds.
curl -s -X POST $BASE/webhooks \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"url": "https://your-system.example/prodaksha/events", "events": ["consignment.received", "run.completed", "statement.issued", "sale.proceeds", "payment.recorded"]}'
The answer carries secret (starts with whsec_) once. Store it: you need it to check every event's signature (Webhooks).
6. Declare a delivery
When goods leave your side, tell the factory they are coming:
curl -s -X POST $BASE/consignments \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reference_no": "VAB-26-7",
"source": "society_api",
"kind": "value_addition",
"sender": {"external_system": "your-system", "society_id": 39, "name": "Example Farmers Co-operative"},
"item": {"code": "MANGO-FRESH"},
"declared_qty": 1250.5, "unit": "kg",
"dispatched_at": "2026-11-15T08:10:00+03:00",
"lots": [{"lot_no": "EX-2026-11-15", "qty": 1250.5}]
}'
{"success": true, "data": {"id": "01JD…", "status": "pending_intake", "supplier_ref": "39", "client_ref": null}, "message": "Created"}
reference_no is your number for the delivery. The factory stores it and every event about this delivery carries it back.
7. Watch it happen
When the factory weighs the delivery in, your address receives consignment.received; when it processes it, run.completed; and so on. Or ask at any time:
curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" $BASE/consignments/VAB-26-7
Next
- Learn the words in Key ideas.
- Follow the whole journey in Connecting a supplier or society system.
