Prerequisites
- Optional
subject_idin 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_idyou will reference:id_side_view_analysismust point to a completed side analysis (analysis_typeside_viewor legacyrunningin stored metadata).id_back_view_analysismust point to a completed back analysis (analysis_typeback_viewor legacypronation).
- You may pass one or both analysis ids. Passing both yields the richest context. If you send
form.subject_idand an analysis was started with asubject_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 frombest_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?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": "..." }.Start processing
POST /shoeRecommendation/start?apiKey=... 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?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.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. |
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. |
/shoeRecommendation/{shoe_recommendation_id}/result page includes a full 200 response example (partner_success).
Result payload: catalog identifiers
On 200 fromGET /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 — how to obtain
video_idvalues and poll analysis results. - Subject management — creating subjects and linking analyses.