PwC JOM compatibility API¶

The Main API exposes five operations migrated from pwc-jom-php. Their paths, request field names, success status codes and JSON or plain-text response bodies remain compatible with the original consumers. They appear under the PwC JOM Compatibility tag in /main/docs.

All five operations:

• require the standard X-API-Key instead of the former CID/JWT login flow;
• prefer the API key's clientId, fall back to Client-ID, and use the fixed pwc data source and environment resolved at FastAPI startup;
• use the shared AI Hub MongoDB connection and are unavailable in PostgreSQL mode;
• support application/json and, for Talent Match Insight success responses, text/plain; API Platform/Hydra application/ld+json is not exposed.

Job-offer generation¶

POST /v1/ai/jobOfferGenerator

The JSON request accepts nullable fields:

Unknown JSON fields are ignored as they were by the original serializer. The legacy prompt template formats both dates, so a request without either date cannot be generated and returns the sanitized 500 response.

Before the LLM call, the service removes the same case-sensitive generic-skill list as the PHP processor, calculates complete elapsed days from the full datetimes and maps the management level and working arrangement. The legacy PHP-empty value "0" omits both management level and skills from the prompt. The service sends the historical six messages once, at temperature zero, through the tenant's default AI Hub LLM profile. No provider or model is hard-coded and no retry or fallback is added.

A successful call returns 201 application/json:

{
  "description": "We are seeking an experienced ...",
  "tasks": ["Plan the engagement", "Review the deliverables"]
}

Talent Match Insight from text¶

POST /v1/ai/talentMatchInsights

Both JSON fields are documented as required:

{
  "cv": "Level: Senior\nTop skills: Audit",
  "offer": "Role: Controls Manager\nSkills: Controls testing"
}

Missing, null, empty or legacy PHP-empty ("0") text returns 400 with The CV or the offer is empty or missing.. Success returns the unwrapped LLM text as 201 text/plain. The eight-message English prompt requires no more than two sentences and 50 words, informal second-person wording and the terms Profile and Opportunity.

The assessment distinguishes listed skills, documented experience and explicit Opportunity requirements. A job title identifies the role's subject or field; it does not alone establish required prior experience, proficiency or duration. For a Profile stating "no SQL experience" and an Opportunity containing only "SQL data analyst", a sufficient comparison is: "Your Profile states that you have no SQL experience; the Opportunity is for a SQL data analyst role." One factual sentence is sufficient; no second sentence is added just to fill the format.

Talent Match Insight by ID¶

POST /v1/ai/talentMatchInsightsById

{
  "userId": "a5ec-b1cf5d",
  "jobOfferId": "12345"
}

Missing or empty IDs return 400 with The userId or jobOfferId is missing or empty.. An unknown user or opportunity returns 404 with The userId or the jobOfferId does not match..

The service first verifies the JobOffers document and then the Users document, retaining the original not-found precedence before resolving the AI configuration. It maps skillsInformation to the historical skill arrays, maps the stored job classification back to its tenant staff level, and formats current ISO dates in the former CV and opportunity layouts. It filters the historical generic skill list from user skills and top skills, builds the other-skill list, then uses the same text-based Talent Match Insight call described above.

Score retrieval¶

GET /v1/scores/jobOffer/{jobOfferId}
GET /v1/scores/user/{userId}

The first operation reads OpportunityMatchingScore and returns up to 100 users. The second reads UsersMatchingScore and returns up to 100 job offers. The default response is a bare JSON array:

[
  {
    "userId": "user-123",
    "skillScore": 0.81,
    "motivationScore": 0.72,
    "overallScore": 0.79
  }
]

The user route replaces userId with jobOfferId. overallScore is the weighted average rounded to two decimals. Each PwC tenant database contains one document in the legacy Company collection; the service uses its exact scoresWeight.skill and scoresWeight.motivation attributes. A missing or non-numeric attribute retains the PHP default of 80 or 20, respectively.

Common query parameters¶

PHP numeric coercion is retained for these values, including scientific notation such as 1e1, which is cast to 10.

Department fallback first returns exact matches for the deepest supplied level. If that group does not fill the limit, the service queries the next parent and excludes documents that already matched a deeper level. This continues until the requested limit is filled or all supplied levels are exhausted.

GET /v1/scores/user/{userId} additionally accepts:

Skill and Motivation order use the selected score as the primary key and the other component as the tie breaker. Overall order uses overallScore first and skillScore as its tie breaker.

Error document¶

Expected filter/input errors and sanitized internal failures retain the historical JSON shape:

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "An error occurred.",
  "status": 400,
  "detail": "All weights must be provided when specified."
}

Authentication failures occur before the compatibility adapter and therefore retain AI Hub's normal {"detail": "..."} authentication response.

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