| 1 | --- |
| 2 | title: "GET /api/v7/sessions/{id}/prefill — Buyer Prefill Data" |
| 3 | sidebarTitle: "GET /prefill" |
| 4 | description: "Retrieve cached buyer profile and payment preferences for a resolved session. Only available when the session's Wallet Confidence Score is 100 or above." |
| 5 | --- |
| 6 | |
| 7 | When ProcureNet resolves a session with a Wallet Confidence Score of 100 or higher, it caches the buyer's known profile data and makes it available through the prefill endpoint. Fetching this data lets your checkout UI pre-populate name, address, and payment preference fields, reducing friction for returning buyers. If the session was classified as `partial` or `anonymous`, this endpoint returns `403` — you must present the buyer with a manual entry form instead. |
| 8 | |
| 9 | ## Authentication |
| 10 | |
| 11 | <Warning> |
| 12 | This endpoint requires a valid Bearer JWT in the `Authorization` header. Requests without a token, or with an expired or malformed token, receive `401 Unauthorized`. |
| 13 | </Warning> |
| 14 | |
| 15 | ``` |
| 16 | Authorization: Bearer <your_jwt> |
| 17 | ``` |
| 18 | |
| 19 | ## Path Parameters |
| 20 | |
| 21 | <ParamField path="id" type="string" required> |
| 22 | The session ID returned by `POST /api/v7/orchestrate`. This scopes the prefill lookup to the correct buyer session. |
| 23 | </ParamField> |
| 24 | |
| 25 | ## Request Example |
| 26 | |
| 27 | ```typescript |
| 28 | const sessionId = 'sess_abc123'; |
| 29 | |
| 30 | const res = await fetch( |
| 31 | `https://api.procurenet.io/api/v7/sessions/${sessionId}/prefill`, |
| 32 | { |
| 33 | method: 'GET', |
| 34 | headers: { |
| 35 | 'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', |
| 36 | 'Content-Type': 'application/json' |
| 37 | } |
| 38 | } |
| 39 | ); |
| 40 | |
| 41 | const prefill = await res.json(); |
| 42 | // { |
| 43 | // "customer": { |
| 44 | // "name": "Jordan Reeves", |
| 45 | // "email": "buyer@example.com", |
| 46 | // "address": { |
| 47 | // "line1": "123 Main St", |
| 48 | // "city": "Austin", |
| 49 | // "state": "TX", |
| 50 | // "zip": "78701", |
| 51 | // "country": "US" |
| 52 | // } |
| 53 | // }, |
| 54 | // "payment_preferences": ["usdc", "card"] |
| 55 | // } |
| 56 | ``` |
| 57 | |
| 58 | ## Response Fields |
| 59 | |
| 60 | <ResponseField name="customer" type="object" required> |
| 61 | A profile object containing the buyer's known identity fields. The exact shape depends on what was available when ProcureNet built the WCS profile. |
| 62 | |
| 63 | <Expandable title="customer fields"> |
| 64 | <ResponseField name="customer.name" type="string"> |
| 65 | The buyer's full name as stored in the resolved profile. |
| 66 | </ResponseField> |
| 67 | |
| 68 | <ResponseField name="customer.email" type="string"> |
| 69 | The buyer's email address. |
| 70 | </ResponseField> |
| 71 | |
| 72 | <ResponseField name="customer.address" type="object"> |
| 73 | Structured shipping or billing address, when available. |
| 74 | </ResponseField> |
| 75 | </Expandable> |
| 76 | </ResponseField> |
| 77 | |
| 78 | <ResponseField name="payment_preferences" type="string[]" required> |
| 79 | An ordered list of the buyer's preferred payment methods, from most to least preferred. Possible values include `"usdc"`, `"card"`, and `"bank_transfer"`. Use this list to rank the options you present in your funding-method UI. |
| 80 | </ResponseField> |
| 81 | |
| 82 | ## Response Example |
| 83 | |
| 84 | ```json |
| 85 | { |
| 86 | "customer": { |
| 87 | "name": "Jordan Reeves", |
| 88 | "email": "buyer@example.com", |
| 89 | "address": { |
| 90 | "line1": "123 Main St", |
| 91 | "city": "Austin", |
| 92 | "state": "TX", |
| 93 | "zip": "78701", |
| 94 | "country": "US" |
| 95 | } |
| 96 | }, |
| 97 | "payment_preferences": ["usdc", "card"] |
| 98 | } |
| 99 | ``` |
| 100 | |
| 101 | <Tip> |
| 102 | Use `payment_preferences[0]` as the default selection in your funding-method UI, then pass it to `POST /api/v7/sessions/{id}/funding-method` when the buyer confirms. |
| 103 | </Tip> |
| 104 | |
| 105 | ## Eligibility Check |
| 106 | |
| 107 | Before calling this endpoint, inspect the `mode` field from your `POST /api/v7/orchestrate` response: |
| 108 | |
| 109 | <Tabs> |
| 110 | <Tab title="Eligible — resolved"> |
| 111 | ```typescript |
| 112 | if (session.mode === 'resolved') { |
| 113 | const prefill = await fetchPrefill(session.session_id, jwt); |
| 114 | populateCheckoutForm(prefill); |
| 115 | } |
| 116 | ``` |
| 117 | </Tab> |
| 118 | <Tab title="Not eligible — partial / anonymous"> |
| 119 | ```typescript |
| 120 | if (session.mode !== 'resolved') { |
| 121 | // Skip prefill — render manual entry form |
| 122 | renderManualEntryForm(); |
| 123 | } |
| 124 | ``` |
| 125 | </Tab> |
| 126 | </Tabs> |
| 127 | |
| 128 | ## Error Codes |
| 129 | |
| 130 | | HTTP Status | Description | |
| 131 | |---|---| |
| 132 | | `401 Unauthorized` | Missing, expired, or invalid Bearer JWT. | |
| 133 | | `403 Forbidden` | The session's WCS is below 100 (`partial` or `anonymous` mode). Prefill is not available for this session. | |
| 134 | | `404 Not Found` | No session exists for the provided `id`. | |
| 135 | | `500 Internal Server Error` | Profile data lookup failure. Retry the request. | |