| 1 | --- |
| 2 | title: "POST /api/v7/orchestrate — Start Procurement Session" |
| 3 | sidebarTitle: "POST /orchestrate" |
| 4 | description: "Start a procurement session. ProcureNet scores buyer identity hints and returns a session ID, WCS score, routing mode, and transport channel." |
| 5 | --- |
| 6 | |
| 7 | The `/api/v7/orchestrate` endpoint is the entry point for every procurement session. You submit a transaction amount, currency, and optional buyer identity hints; ProcureNet's Wallet Confidence Score (WCS) engine evaluates those hints, assigns a score from 0 to 200, and returns a session ID along with the resolved routing mode and the transport channel your client should open. No authentication is required on this call — the WCS engine derives trust from the hints you supply, not from a credential. |
| 8 | |
| 9 | ## Request Body |
| 10 | |
| 11 | <ParamField body="amount" type="number" required> |
| 12 | The transaction amount in the specified currency. For example, `1500.00`. |
| 13 | </ParamField> |
| 14 | |
| 15 | <ParamField body="currency" type="string" required> |
| 16 | ISO 4217 currency code for the transaction. For example, `"USD"` or `"EUR"`. |
| 17 | </ParamField> |
| 18 | |
| 19 | <ParamField body="hints" type="object"> |
| 20 | Optional buyer identity signals used to calculate the WCS. The more signals you provide, the higher the score and the more prefill and SSE transport features become available. |
| 21 | |
| 22 | <Expandable title="hints fields"> |
| 23 | <ParamField body="hints.customerId" type="string"> |
| 24 | A known, persistent customer ID from your system. Contributes **100 points** to the WCS — the single highest-weight signal. Providing this alone is sufficient to reach the `resolved` threshold. |
| 25 | </ParamField> |
| 26 | |
| 27 | <ParamField body="hints.email" type="string"> |
| 28 | The buyer's email address. Contributes **40 points** to the WCS. |
| 29 | </ParamField> |
| 30 | |
| 31 | <ParamField body="hints.phone" type="string"> |
| 32 | The buyer's phone number in E.164 format (e.g., `"+15551234567"`). Contributes **40 points** to the WCS. |
| 33 | </ParamField> |
| 34 | |
| 35 | <ParamField body="hints.deviceId" type="string"> |
| 36 | A device fingerprint or identifier for the buyer's current device. Contributes **20 points** to the WCS. |
| 37 | </ParamField> |
| 38 | </Expandable> |
| 39 | </ParamField> |
| 40 | |
| 41 | <Note> |
| 42 | The maximum possible WCS is **200** (all four hints provided). A score of **≥ 100** resolves the session to `resolved` mode with SSE transport. Scores of **40–99** produce `partial` mode, and scores **below 40** produce `anonymous` mode — both use WebSocket transport. |
| 43 | </Note> |
| 44 | |
| 45 | ## Request Example |
| 46 | |
| 47 | ```typescript |
| 48 | const res = await fetch('https://api.procurenet.io/api/v7/orchestrate', { |
| 49 | method: 'POST', |
| 50 | headers: { 'Content-Type': 'application/json' }, |
| 51 | body: JSON.stringify({ |
| 52 | amount: 1500.00, |
| 53 | currency: 'USD', |
| 54 | hints: { |
| 55 | customerId: 'cust_8f2a1b', |
| 56 | email: 'buyer@example.com', |
| 57 | phone: '+15551234567', |
| 58 | deviceId: 'dev_9c3d2e' |
| 59 | } |
| 60 | }) |
| 61 | }); |
| 62 | |
| 63 | const session = await res.json(); |
| 64 | // { |
| 65 | // session_id: 'sess_abc123', |
| 66 | // wcs_score: 200, |
| 67 | // mode: 'resolved', |
| 68 | // transport: 'sse' |
| 69 | // } |
| 70 | ``` |
| 71 | |
| 72 | ## Response Fields |
| 73 | |
| 74 | <ResponseField name="session_id" type="string" required> |
| 75 | The unique session identifier. Pass this as the `{id}` path parameter in all subsequent session calls: prefill, transition, escrow-accept, and funding-method. |
| 76 | </ResponseField> |
| 77 | |
| 78 | <ResponseField name="wcs_score" type="integer" required> |
| 79 | The calculated Wallet Confidence Score, ranging from `0` to `200`. Reflects the sum of the hint weights provided. |
| 80 | </ResponseField> |
| 81 | |
| 82 | <ResponseField name="mode" type="string" required> |
| 83 | The resolved session classification. One of: |
| 84 | |
| 85 | | Value | WCS Range | Meaning | |
| 86 | |---|---|---| |
| 87 | | `resolved` | ≥ 100 | Full buyer identity confirmed; prefill available | |
| 88 | | `partial` | 40–99 | Partial identity; limited prefill | |
| 89 | | `anonymous` | < 40 | No reliable identity signals | |
| 90 | </ResponseField> |
| 91 | |
| 92 | <ResponseField name="transport" type="string" required> |
| 93 | The recommended transport channel for real-time session events. `sse` for `resolved` sessions; `websocket` for `partial` and `anonymous`. |
| 94 | </ResponseField> |
| 95 | |
| 96 | ## Response Example |
| 97 | |
| 98 | ```json |
| 99 | { |
| 100 | "session_id": "sess_abc123", |
| 101 | "wcs_score": 200, |
| 102 | "mode": "resolved", |
| 103 | "transport": "sse" |
| 104 | } |
| 105 | ``` |
| 106 | |
| 107 | ## WCS Score Reference |
| 108 | |
| 109 | <CardGroup cols={3}> |
| 110 | <Card title="resolved" icon="circle-check"> |
| 111 | Score **≥ 100** — Full prefill access, SSE transport, all session features unlocked. |
| 112 | </Card> |
| 113 | <Card title="partial" icon="circle-half-stroke"> |
| 114 | Score **40–99** — Reduced prefill, WebSocket transport required. |
| 115 | </Card> |
| 116 | <Card title="anonymous" icon="circle-xmark"> |
| 117 | Score **< 40** — No prefill available, WebSocket transport required. |
| 118 | </Card> |
| 119 | </CardGroup> |
| 120 | |
| 121 | ## Error Codes |
| 122 | |
| 123 | | HTTP Status | Description | |
| 124 | |---|---| |
| 125 | | `400 Bad Request` | Missing required fields (`amount` or `currency`), or malformed request body. | |
| 126 | | `422 Unprocessable Entity` | Field validation failed — for example, an unrecognized `currency` code. | |
| 127 | | `500 Internal Server Error` | WCS engine or orchestration pipeline failure. Retry with exponential backoff. | |