Matching endpoints¶

src/matching owns three products: Job Offer Matching (JOM), Job Proximity Matching (JPM) and Training Matching. Current /api/v1 operations require the standard API key. Historical /jom/admin and /jpm/admin operations preserve their existing unauthenticated environment contract.

JPM rationale¶

POST /api/v1/jpm/rationale¶

Returns a compact, localized explanation of a job's relevance using JPM user skills and current/target job evidence. The JSON body requires client_id, user_id, job_id and locale; data_source defaults to smartmobility. The response is {"rationale": "..."}, capped at 300 characters. See JPM rationale for examples and errors.

Matching operations¶

GET /api/v1/user/process¶

Loads one user and runs the selected products. jom=true and jpm=true by default; selected calculations execute concurrently and are returned under their product keys. At least one flag must be true. Each product independently builds candidates, calculates scores and applies its configured persistence and publishing behavior.

GET /api/v1/opportunity/process¶

Loads one opportunity and calculates JOM scores against eligible users. Missing entities and unknown tenant databases are returned as public errors by the processing boundary.

GET /api/v1/job/process¶

Loads one job and calculates JPM scores against eligible users. The service selects MongoDB documents or PostgreSQL projections, then persists results in the active score repository.

POST /api/v1/feedback/process¶

Processes a JOM feedback event through the same feedback flow as the consumer. It normalizes the event, updates the corresponding user preference signal and persists the operational effect. call_from_consumer=true archives the raw feedback in Datalake before processing. The JSON body and client/data-source query parameters are unchanged; this operation remains MongoDB-only.

JOM scores¶

POST /api/v1/jom/user/scores¶

Reads persisted current-model scores for a user, with ordering and a default limit of 100. recompute_scores=true runs the complete user-to-opportunities pipeline first; save_scores and send_scores control persistence and outbound publication for that calculation.

POST /jom/admin/get_one_user_scores¶

Preserves the historical JOM user-score contract and delegates to the same backend-aware score service. Its default is read-only: recomputation, saving and publishing are all disabled.

POST /api/v1/jom/opportunity/scores¶

Returns user scores for one opportunity. By default it recomputes, saves and publishes the opportunity-side results; callers can disable each behavior and control result order/limit.

POST /jom/admin/get_one_offer_scores¶

Historical alias of the opportunity score workflow using offer_id. It keeps the legacy defaults, which also recompute, persist and publish unless explicitly disabled.

GET /jom/health-check¶

Returns the JOM router health payload. It does not validate downstream database or model availability.

Talent Match Insight¶

POST /api/v1/jom/rationale¶

Loads a user, opportunity and their persisted JOM score, builds a constrained evidence payload and asks the configured LLM for a two-sentence localized rationale. insight_type=skills or motivation narrows the evidence; omission uses both. See Talent Match Insight for the complete pipeline and failure behavior.

POST /jom/admin/talent_match_insights_by_id¶

Preserves the historical query-parameter contract but invokes the same insight service and output rules.

JPM scores¶

POST /api/v1/jpm/user/scores¶

Returns persisted job-proximity scores for a user. Optional recomputation runs hard filters, skill and job-text scoring; saving and publishing remain disabled by default.

POST /jpm/admin/get_one_user_scores¶

Historical contract for the same backend-aware user JPM score service. It keeps the legacy environment resolution and optional unbounded limit.

Galaxy¶

POST /api/v1/jpm/galaxy/path¶

Uses a JSON body with tenant, user and target-job IDs to generate a validated career path from stored JPM results. Returns authoritative job metadata, transitions, an explanation and an explicit reason when no path is returned.

POST /api/v1/jpm/galaxy/rationale¶

Accepts the same context and an ordered path_job_ids list. Explains the supplied path's training needs and skills to develop in the employee's locale, in at most 20 words. See Galaxy for contracts, examples, rules and configuration.

Training Matching¶

POST /api/v1/get_training_matching¶

Resolves a natural-language request plus optional user context into a hybrid training search. Full-text and vector rankings are fused with weighted RRF, hard filters and exclusions are applied in the active backend, and the requested number of results is returned directly in RRF order. See Training Matching.

GET /api/v1/get_training_matching_rationale¶

Loads one user and training and generates a rationale in the validated BCP 47 locale. Optional search_query (at most 4,000 characters) requests a search-based explanation in 1–2 sentences. An omitted, empty or whitespace-only query preserves the profile-based 80–120-character prompt. It explains an existing pair and does not alter search order or stored scores. See rationale modes.

POST /api/v1/development-objectives/suggestions¶

Builds personalized development objectives from the authenticated user's profile, skill gaps and relevant context. Strict structured model output is validated and adapted to the public response; invalid or incomplete generated records fail rather than being silently invented.

Statistics and exports¶

The matching and skill-score exports below support MongoDB and PostgreSQL. The legacy/current JPM comparison is available only in MongoDB mode.

In PostgreSQL mode, matching exports download stored scores as XLSX, with identifier selection, ordering and per-entity limits. They do not apply recomputation, source enrichment, Talent Match Insight generation, email or SFTP delivery options. The skill_scores exports return the stored score for the requested pair, rather than the detailed skill-pair calculation available in MongoDB mode. The additional capabilities described below apply to MongoDB.

POST /api/v1/jom/stats/matchings/users¶

Generates a user-side JOM workbook for an uploaded selection or tenant scope. It can recompute scores, add source information, include Talent Match Insight, sort/limit results and send the artifact by email or SFTP.

POST /api/v1/jom/stats/matchings/opportunities¶

Generates the opportunity-side JOM workbook, optionally resolving uploaded opportunity codes, recomputing scores and enriching the export before email delivery.

POST /api/v1/jom/stats/skill_scores¶

Produces the detailed skill-pair calculation for one user/opportunity pair, including selected semantic matches, levels, weights and the resulting skill score.

POST /api/v1/jpm/stats/matchings¶

Exports JPM results for selected or discovered users, with optional recomputation, source enrichment, ordering, email and SFTP delivery.

POST /api/v1/jpm/stats/compare_v1_v2_matchings¶

Builds a comparison workbook between legacy and current JPM scores for the selected users. It is a reporting operation and does not migrate stored scores. PostgreSQL requests return HTTP 400 because this comparison requires MongoDB.

POST /api/v1/jpm/stats/skill_scores¶

Produces the detailed shared skill-score calculation for one user/job pair, making the semantic match, level ratio and configured type weights inspectable.

Administrator batch and publication routes are catalogued under Administration.

The generated main HTTP reference is the authoritative source for parameters, schemas, responses and examples.