Getting started

1. Obtain an API key

A GetSize admin creates a key for you from the admin console. The raw key is shown exactly once on creation, so store it in your secret manager immediately.

2. Create a session

A session represents one end user of your integration. Create one at the start of each end-user conversation:

curl -X POST https://www.getsize.shoes/api/public/v1/sessions \
  -H "X-Api-Key: gsk_live_..."

{
  "sessionId": "abc123-def456-...",
  "createdAt": "2026-04-15T10:00:00Z",
  "expiresAt": "2026-04-22T10:00:00Z",
  "shoeCount": 0,
  "hasFootMeasurement": false
}

Store sessionId; every subsequent call threads it through the URL.

3. Add a foot measurement (optional)

curl -X POST https://www.getsize.shoes/api/public/v1/sessions/$SESSION_ID/foot-measurement \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"rightFootLengthMm": 268, "leftFootLengthMm": 270}'

4. Identify a shoe the user owns

Use the unified /shoe-selection loop to walk the catalog. See Identifying shoes for the full pattern.

5. Add the identified shoe to the session rack

curl -X POST https://www.getsize.shoes/api/public/v1/sessions/$SESSION_ID/shoes \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"shoe": { ...canonical shoe from /shoe-selection... }}'

6. Get a size recommendation for a target shoe

curl -X POST https://www.getsize.shoes/api/public/v1/sessions/$SESSION_ID/recommendations \
  -H "X-Api-Key: gsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target": { ...canonical target shoe... }}'

{
  "recommendedSize": "42",
  "sizeSystem": "EU",
  "confidenceBasis": [ ... ]
}