> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ochy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Shoe recommendation

> Three-step flow: submit a questionnaire with optional subject link and analyses, start processing, then poll for ranked shoe matches and parameter recommendations.

This guide describes the **Partner API** shoe recommendation flow. It combines a short runner
questionnaire with one or two **completed** biomechanical analyses (side view and/or back view),
then returns ideal shoe characteristics and a ranked list of catalog matches.

## Prerequisites

* Optional **`subject_id`** in the questionnaire from [Subject management](/guides/subject-management) when you want the recommendation tied to a known subject. If you send it, it must exist for your account.
* At least one **successful** analysis whose `video_id` you will reference:
  * `id_side_view_analysis` must point to a completed **side** analysis (`analysis_type` `side_view` or legacy `running` in stored metadata).
  * `id_back_view_analysis` must point to a completed **back** analysis (`analysis_type` `back_view` or legacy `pronation`).
* You may pass **one or both** analysis ids. Passing both yields the richest context. If you send
  `form.subject_id` and an analysis was started with a `subject_id`, those values must match.

<h2 id="shoe-catalog">
  Shoe catalog
</h2>

Recommendations only include shoes that are **active** in your organization's catalog.
Inactive or missing models are excluded from `best_matching_shoe` and `all_matches`, even when
they would otherwise match the runner profile.

<h3 id="activate-shoes-in-admin">
  Activate shoes in admin
</h3>

Before you call the API, activate the models you want offered in results through the
[Organization API settings](https://app.ochy.io/organization/api) in the Ochy admin panel.

<h3 id="external-catalogue">
  External product catalogue
</h3>

<Note>
  To connect an **external product catalogue** instead of (or in addition to) the catalog managed
  in Ochy, contact the Ochy team. That integration is set up on your account by Ochy — it is not
  configured through the Partner API alone.
</Note>

## Three-step flow

<Steps>
  <Step title="Submit the questionnaire">
    `POST /shoeRecommendation/form?apiKey=...` with JSON body `input.form` (runner profile),
    optional `id_side_view_analysis`, `id_back_view_analysis`, and optional `favorite_brands`.

    The response is **201** with `{ "shoe_recommendation_id": "..." }`.
  </Step>

  <Step title="Start processing">
    `POST /shoeRecommendation/start?apiKey=...` with `{ "shoe_recommendation_id": "<id>" }`.

    The response is **202** with a short confirmation message. Processing runs asynchronously.
  </Step>

  <Step title="Get results">
    `GET /shoeRecommendation/{shoe_recommendation_id}/result?apiKey=...`.

    While the job is queued or running, the API returns **404** with a JSON body that includes
    `status` (`pending` or `processing`). If processing fails, you get **404** with `status: failed`.
    On success, **200** returns only the business payload: `recommendations`, `best_matching_shoe`,
    `all_matches`, and `user_id`. Each catalog shoe in `best_matching_shoe` and in `all_matches`
    includes top-level **`gtins`** and **`mpns`** (arrays of strings, possibly empty), copied from
    the catalog model for GTIN/EAN and manufacturer part numbers.
  </Step>
</Steps>

## Request body: `input` (with `form`)

The JSON body is a single object `{ "input": { ... } }`. Fields **next to** `form` apply to the
whole recommendation request:

| Field                   | Type      | Required | Default | Allowed values                                                           | Description                               |
| ----------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| `form`                  | object    | **Yes**  | —       | —                                                                        | Runner questionnaire (see table below).   |
| `id_side_view_analysis` | string    | No       | —       | Any `video_id` of a **successful** `side_view` analysis for your account | Biomechanical input from the side camera. |
| `id_back_view_analysis` | string    | No       | —       | Any `video_id` of a **successful** `back_view` analysis for your account | Biomechanical input from the back camera. |
| `favorite_brands`       | string\[] | No       | —       | Array of non-empty strings (your brand keys)                             | Optional filter on the shoe catalog.      |

At least **one** of `id_side_view_analysis` or `id_back_view_analysis` must be non-empty. Each id
must match an analysis you own, with the correct `analysis_type`, and `source` from the Partner API.
If you send `form.subject_id` and an analysis was created with a `subject_id`, that id must equal `form.subject_id`.

## Questionnaire: `input.form`

All fields below live under `input.form` in the JSON body.

| Field                          | Type      | Required | Default                                | Allowed values                                                                                                     | Description                                                                                                                                                                                      |
| ------------------------------ | --------- | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `subject_id`                   | string    | No       | —                                      | —                                                                                                                  | Subject identifier from [Subject management](/guides/subject-management) when linking this recommendation to a subject (same value as `subject_id` on analysis start when you link an analysis). |
| `running_experience`           | string    | **Yes**  | —                                      | `beginner`, `novice`, `intermediate`, `advanced`                                                                   | How long the runner has been running: `beginner` (under 6 months), `novice` (6 months to 1 year), `intermediate` (1 to 3 years), `advanced` (more than 3 years).                                 |
| `running_session`              | string    | **Yes**  | —                                      | `low_frequency`, `moderate_frequency`, `high_frequency`, `very_high_frequency`                                     | Typical training frequency per week (`low_frequency` once or less; `moderate_frequency` 2--3; `high_frequency` 3--5; `very_high_frequency` more than 5).                                         |
| `weekly_km`                    | string    | **Yes**  | —                                      | `low_volume`, `moderate_volume`, `high_volume`, `very_high_volume`                                                 | Weekly running distance band (`low_volume` up to \~10 km; `moderate_volume` \~10--20 km; `high_volume` \~20--50 km; `very_high_volume` above \~50 km).                                           |
| `shoe_purpose`                 | string\[] | **Yes**  | —                                      | Each element **must** be one of: `jogging`, `racing`, `tempo_training`, `interval_training`.                       | Intended uses for the new shoes (multi-select).                                                                                                                                                  |
| `pain`                         | string\[] | No       | `[]` (empty)                           | Each element **must** be one of: `back`, `hip`, `knee`, `shin_splints`, `calf`, `ankle`, `achilles_tendon`, `foot` | Current pain or discomfort areas. Omit the field or send `[]` if none.                                                                                                                           |
| `treadmill`                    | boolean   | **Yes**  | —                                      | Only `true` or `false`                                                                                             | Whether the runner trains mostly on a treadmill.                                                                                                                                                 |
| `weight`                       | number    | No       | `70`                                   | Any number greater than 0 (kilograms)                                                                              | Body weight.                                                                                                                                                                                     |
| `height`                       | number    | No       | `1.70`                                 | Any number greater than 0 (meters)                                                                                 | Standing height.                                                                                                                                                                                 |
| `carbon_plate`                 | string    | No       | *(omitted → engine default `unknown`)* | `with_plate`, `without_plate`, `unknown`                                                                           | Preference regarding a carbon plate in the **new** shoe.                                                                                                                                         |
| `comfort_heel_cushioning`      | integer   | No       | null / omitted                         | Integer **0**--**100**, or omit / `null` for unknown                                                               | Perceived heel cushioning of current shoes.                                                                                                                                                      |
| `comfort_forefoot_cushioning`  | integer   | No       | null / omitted                         | Integer **0**--**100**, or omit / `null`                                                                           | Perceived forefoot cushioning of current shoes.                                                                                                                                                  |
| `comfort_shoe_stability`       | integer   | No       | null / omitted                         | Integer **0**--**100**, or omit / `null`                                                                           | Perceived stability of current shoes.                                                                                                                                                            |
| `comfort_forefoot_flexibility` | integer   | No       | null / omitted                         | Integer **0**--**100**, or omit / `null`                                                                           | Perceived forefoot flexibility of current shoes.                                                                                                                                                 |
| `previous_shoes`               | object    | No       | *(omitted)*                            | See [Previous shoes object](#previous-shoes)                                                                       | Optional structured description of the runner's current or last shoes.                                                                                                                           |

<h3 id="previous-shoes">Previous shoes object (<code>previous\_shoes</code>)</h3>

When you send `previous_shoes`, each property is optional; only include keys you know. If you send
a key, its value **must** be one of the tokens listed for that key.

| Field          | Type   | Allowed values                                                 | Description                                           |
| -------------- | ------ | -------------------------------------------------------------- | ----------------------------------------------------- |
| `stability`    | string | `motion_control`, `neutral`, `unknown`                         | Overall stability category of the previous shoe.      |
| `drop`         | string | `zero_drop`, `low_drop`, `medium_drop`, `high_drop`, `unknown` | Heel-to-toe drop of the previous shoe.                |
| `carbon_plate` | string | `with_plate`, `without_plate`, `unknown`                       | Whether the previous shoe had a rigid / carbon plate. |
| `shoe_weight`  | string | `medium`, `light`, `heavy`, `barefoot`, `unknown`              | Perceived weight of the previous shoe.                |

For request/response examples and full OpenAPI schemas, see the **API reference** tab under **Shoe recommendation**. The **GET** `/shoeRecommendation/{shoe_recommendation_id}/result` page includes a full **200** response example (`partner_success`).

## Result payload: catalog identifiers

On **200** from `GET /shoeRecommendation/{shoe_recommendation_id}/result`, every shoe object returned
as `best_matching_shoe` or as an element of `all_matches` includes:

| Field   | Type      | Description                                                                         |
| ------- | --------- | ----------------------------------------------------------------------------------- |
| `gtins` | string\[] | GTIN/EAN identifiers linked to the shoe model in the catalog (empty array if none). |
| `mpns`  | string\[] | Manufacturer part numbers for model variants (empty array if none).                 |

## Related guides

* [Analysis workflow](/guides/analysis-workflow) -- how to obtain `video_id` values and poll analysis results.
* [Subject management](/guides/subject-management) -- creating subjects and linking analyses.