Shoe recommendation

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 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.

Shoe catalog

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.

Activate shoes in admin

Before you call the API, activate the models you want offered in results through the Organization API settings in the Ochy admin panel.

External product catalogue

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.

Three-step flow

Submit the questionnaire

POST /shoeRecommendation/form 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": "..." }.

Start processing

POST /shoeRecommendation/start with { "shoe_recommendation_id": "<id>" }.The response is 202 with a short confirmation message. Processing runs asynchronously.

Get results

GET /shoeRecommendation/{shoe_recommendation_id}/result.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.

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 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	Optional structured description of the runner’s current or last shoes.

Previous shoes object (`previous_shoes`)

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).

Analysis workflow — how to obtain video_id values and poll analysis results.
Subject management — creating subjects and linking analyses.

Getting started

Guides

Prerequisites

Shoe catalog

Activate shoes in admin

External product catalogue

Three-step flow

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

Questionnaire: `input.form`

Previous shoes object (`previous_shoes`)

Result payload: catalog identifiers

​Prerequisites

​Shoe catalog

​Activate shoes in admin

​External product catalogue

​Three-step flow

​Request body: input (with form)

​Questionnaire: input.form

​Previous shoes object (previous_shoes)

​Result payload: catalog identifiers

​Related guides

Prerequisites

Shoe catalog

Activate shoes in admin

External product catalogue

Three-step flow

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

Questionnaire: `input.form`

Previous shoes object (`previous_shoes`)

Result payload: catalog identifiers

Related guides