> ## Documentation Index > Fetch the complete documentation index at: https://docs.fribl.co/llms.txt > Use this file to discover all available pages before exploring further. # Match CVs to a job > Match one or more candidate CVs against a job description using AI-powered scoring. Configure optional weights to prioritize specific dimensions such as experience, hard skills, soft skills, or education. The sum of all weights must not exceed 1.0. Billable — charges the `job_matching` action once per match request. See `GET /tokens/costs` for live pricing. ## OpenAPI ````yaml /api-reference/openapi.json post /match openapi: 3.1.0 info: title: Fribl API description: >- The Fribl API enables intelligent talent matching powered by AI. Analyze CVs and job descriptions from text or file uploads, search and manage skills, match candidates to positions with configurable scoring weights, and source candidate profiles from external databases. All document processing is asynchronous — submit documents for analysis, poll for status, and retrieve structured results when ready. version: 1.0.0 contact: name: Fribl Support url: https://fribl.co servers: - url: https://api-service.fribl.co/api/v1 description: Production security: - apiKey: [] tags: - name: CVs description: >- Upload, analyze, retrieve, update, and delete candidate CVs. CVs can be submitted as raw text or as PDF file uploads. Processing is asynchronous — use the status endpoint to track progress. - name: Jobs description: >- Upload, analyze, retrieve, update, and delete job descriptions. Jobs can be submitted as raw text or as PDF file uploads. Processing is asynchronous — use the status endpoint to track progress. - name: Matching description: >- Match analyzed CVs against job descriptions using AI-powered scoring. Configure weights across experience, hard skills, soft skills, and education dimensions to tailor match results to your hiring priorities. - name: Sourcing description: >- Search for candidate profiles from external sources, retrieve cached search results, and ingest selected profiles into your Fribl workspace for matching. - name: Skills description: >- Search the Fribl skills taxonomy and retrieve available languages for skill translation. These endpoints are publicly accessible and do not require authentication. - name: Tokens description: >- Inspect your workspace's usage-based token balance, review the ledger of every charge and refund, and read the live per-action price list. Billable endpoints deduct tokens and return 402 when the balance is insufficient. Tokens are purchased and managed in the Fribl Console (https://console.fribl.co). paths: /match: post: tags: - Matching summary: Match CVs to a job description: >- Match one or more candidate CVs against a job description using AI-powered scoring. Configure optional weights to prioritize specific dimensions such as experience, hard skills, soft skills, or education. The sum of all weights must not exceed 1.0. Billable — charges the `job_matching` action once per match request. See `GET /tokens/costs` for live pricing. operationId: matchCvsToJob requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MatchBody' responses: '200': description: Match results with scored candidates. content: application/json: schema: type: object properties: message: type: string example: Match result length: type: integer description: Number of result sets returned. data: type: array items: type: array items: $ref: '#/components/schemas/MatchCandidate' description: >- Nested array of match results. Each inner array contains scored candidates for a match operation. required: - message - length - data '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' components: schemas: MatchBody: type: object description: Request body for matching CVs to a job. properties: jobId: type: string format: uuid description: Unique identifier of the job to match against. candidatesIds: type: array items: type: string format: uuid description: List of CV identifiers to match against the job. topK: type: integer minimum: 1 description: Maximum number of top-scoring candidates to return. weights: $ref: '#/components/schemas/MatchWeights' cache: type: boolean description: Whether to cache the match results for later retrieval. required: - jobId - candidatesIds - topK MatchCandidate: type: object description: >- A candidate's match result with detailed scoring breakdown across all dimensions. properties: score_meta: type: object description: Average scores per dimension (0–10 scale). properties: education: type: number description: Average education score. hard_skills: type: number description: Average hard skills score. soft_skills: type: number description: Average soft skills score. experience: type: number description: Average experience score. score_dict: type: object description: >- Detailed per-requirement scoring. Each dimension maps requirement/skill names to a score detail object. properties: education: type: object additionalProperties: $ref: '#/components/schemas/ScoreDetail' description: Education requirements with individual scores. hard_skills: type: object additionalProperties: $ref: '#/components/schemas/ScoreDetail' description: Hard skill requirements with individual scores. soft_skills: type: object additionalProperties: $ref: '#/components/schemas/ScoreDetail' description: Soft skill requirements with individual scores. experience: type: object additionalProperties: $ref: '#/components/schemas/ScoreDetail' description: Experience requirements with individual scores. summary_score: type: number description: Weighted overall match score (0–10 scale). final_score: type: number description: Final normalized match score (0–10 scale). person_id: type: string format: uuid description: Unique identifier of the matched candidate. job_id: type: string format: uuid description: Unique identifier of the job matched against. required: - score_meta - score_dict - summary_score - final_score - person_id - job_id MatchWeights: type: object description: >- Custom weights for each scoring dimension. The sum of all weights must not exceed 1.0. If omitted, equal weights are applied. properties: experience: type: number minimum: 0 maximum: 1 description: Weight for experience scoring. example: 0.25 hardSkills: type: number minimum: 0 maximum: 1 description: Weight for hard skills scoring. example: 0.25 softSkills: type: number minimum: 0 maximum: 1 description: Weight for soft skills scoring. example: 0.25 education: type: number minimum: 0 maximum: 1 description: Weight for education scoring. example: 0.25 ScoreDetail: type: object description: Scoring detail for a single requirement or skill. properties: score: type: integer minimum: 0 maximum: 10 description: Score from 0 to 10 for this requirement. criteria: type: string description: The evaluation criteria used for scoring. explanation: type: string description: >- Detailed justification for the score, referencing specific CV content. required: - score - criteria - explanation ErrorResponse: type: object description: Standard error response. properties: error: type: string description: Human-readable error message. required: - error InsufficientTokensError: type: object description: >- Returned with HTTP 402 when the workspace balance can't cover a billable request. No work is performed and nothing is charged. properties: code: type: string enum: - INSUFFICIENT_TOKENS description: Machine-readable error code. Switch on this rather than the message. example: INSUFFICIENT_TOKENS message: type: string example: 'Insufficient tokens: have 3, need 10' balance: type: integer description: Current workspace balance. example: 3 required: type: integer description: Tokens required for this request (worst case for sourcing searches). example: 10 required: - code - message - balance - required responses: BadRequest: description: The request was malformed or contained invalid parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: >- Authentication failed. Provide a valid API key in the `x-api-key` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PaymentRequired: description: >- The workspace has insufficient tokens for the requested operation. Nothing was charged. content: application/json: schema: $ref: '#/components/schemas/InsufficientTokensError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- API key in UUID format. Include this header with every authenticated request. ````