Skip to main content
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 the catalog your API key uses. Inactive or missing models are excluded from best_matching_shoe and all_matches, even when they would otherwise match the runner profile. Things to know about the catalog:
  • An empty catalog is not an error. With no active shoe, the recommendation still completes successfully (status: success), but no shoe is returned in best_matching_shoe or all_matches. Activate shoes to get matches.
  • Self-serve keys have no stock filtering. Only the active flag decides which shoes are offered; use_stock, if you send it, has no effect.
  • Product links come from your own catalog only. product_link and shoe_asset.product_page in results are the links you set for your own shoes. They are empty or absent until you set them: Ochy never fills them in from its own catalog.

​
List brands

GET /shoeRecommendation/brands returns the brand keys of the models that are active in the catalog your API key uses. A brand is included when at least one of its models is active.
Each string is a brand_key. Send it in favorite_brands to keep a recommendation inside that brand. An empty catalog returns { "brands": [] } with status 200.

​
Activate shoes in the developer portal

Before you call the API, activate the models you want offered in results in the Shoes tab of the developer portal. Organization admins manage the organization’s catalog. With a self-serve account, you manage your own catalog.

​
External product catalogue

To connect an external product catalogue instead of (or in addition to) the catalog managed in Ochy, contact the Ochy team. This is available to organization accounts only. That integration is set up on your account by Ochy — it is not configured through the Partner API alone.

​
Three-step flow

1

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": "..." }.
2

Start processing

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

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.
You can also review the recommendations created with your API key, with their analyses and ranked matches, in the Shoe recommendations tab of the developer portal.

​
Request body: input (with form)

The JSON body is a single object { "input": { ... } }. Fields next to form apply to the whole recommendation request: 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.
Analyses started before October 2, 2026 are stored in a different workspace from analyses started since. If id_side_view_analysis and id_back_view_analysis come from different workspaces, the request is rejected with 400 and code analyses_mixed_owner. Reference only one of them, or use two analyses started on or after October 2, 2026.

​
Questionnaire: input.form

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

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