Skip to main content

​
Quickstart

This guide walks you through the complete Fribl workflow: analyzing a CV, analyzing a job description, polling for completion, and running a match.

​
Prerequisites

  • A Fribl API key (contact Fribl to obtain one)
  • A tool for making HTTP requests (cURL, Postman, or any HTTP client)

​
Step 1: Analyze a CV

Submit one or more CVs for analysis. The inputs field accepts an array of CV text strings. 
curl -X POST https://api-service.fribl.co/api/v1/cvs/analyze \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      "John Doe\nSenior Software Engineer\n\nExperience:\n- Senior Software Engineer at Tech Corp (2020-2023)\n  Led development of microservices architecture using Node.js and Python\n\n- Software Engineer at StartupCo (2017-2020)\n  Built REST APIs and React frontends\n\nSkills: JavaScript, Python, React, Node.js, Docker, Team Leadership, Communication\n\nEducation:\n- MSc Computer Science, University of Amsterdam (2015-2017)\n\nLanguages: English (Native), Dutch (B2)"
    ]
  }'
The API returns task IDs and a PENDING status. Save the ID for status polling.
Response
{
  "message": "Analyze CVs request received!",
  "data": {
    "ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "status": "PENDING"
  }
}

​
Step 2: Poll for completion

Check the processing status until it reaches completed. Continue polling while the task is in_progress or retrying, and handle not_found explicitly. 
curl -X POST https://api-service.fribl.co/api/v1/cvs/status \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'
Response
{
  "message": "Successfully retrieved CVs status",
  "length": 1,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "original_id": null,
      "status": "completed"
    }
  ]
}

​
Step 3: Analyze a job description

Submit a job description for analysis using the same pattern. 
curl -X POST https://api-service.fribl.co/api/v1/jobs/analyze \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      "Senior Software Engineer\n\nWe are looking for a Senior Software Engineer to join our team in Amsterdam.\n\nRequirements:\n- 5+ years of experience with JavaScript and Python\n- Experience with React and Node.js\n- Knowledge of Docker and CI/CD\n- Strong communication and leadership skills\n- MSc in Computer Science or related field"
    ]
  }'
Poll POST /jobs/status for the job as well, using the same pattern as Step 2. Both the CV and job must reach completed before matching.

​
Step 4: Match the candidate to the job

Once both reach completed status, run a match with your preferred scoring weights. 
curl -X POST https://api-service.fribl.co/api/v1/match \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "topK": 5,
    "weights": {
      "experience": 0.25,
      "hardSkills": 0.25,
      "softSkills": 0.25,
      "education": 0.25
    },
    "candidatesIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'
The response includes ranked candidates with per-dimension scoring and explanations:
Response
{
  "message": "Match result",
  "length": 1,
  "data": [
    [
      {
        "score_meta": {
          "education": 8.5,
          "hard_skills": 7.2,
          "soft_skills": 8.0,
          "experience": 6.5
        },
        "score_dict": {
          "education": {
            "MSc in Computer Science": {
              "score": 9,
              "criteria": "Relevant degree in required field",
              "explanation": "Candidate holds an MSc in Computer Science from the University of Amsterdam, directly matching the required qualification."
            }
          },
          "hard_skills": {
            "JavaScript": {
              "score": 8,
              "criteria": "Proficiency in JavaScript",
              "explanation": "Demonstrated extensive JavaScript experience across multiple roles including React and Node.js projects."
            },
            "Python": {
              "score": 7,
              "criteria": "Proficiency in Python",
              "explanation": "Used Python for microservices development at Tech Corp."
            }
          },
          "soft_skills": {
            "Team Leadership": {
              "score": 8,
              "criteria": "Leadership capability",
              "explanation": "Led development teams and managed cross-functional projects at Tech Corp."
            }
          },
          "experience": {
            "5+ years software development": {
              "score": 7,
              "criteria": "Years of relevant experience",
              "explanation": "Candidate has 6 years of professional software engineering experience across two roles."
            }
          }
        },
        "summary_score": 7.55,
        "final_score": 7.55,
        "person_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "job_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      }
    ]
  ]
}

​
File upload alternative

You can upload CV and job files directly instead of providing text: 
curl -X POST https://api-service.fribl.co/api/v1/cvs/analyze/files \
  -H "x-api-key: your-api-key-here" \
  -F "files=@/path/to/cv.pdf"
Supported formats: PDF, DOC, DOCX (max 50MB).

​
Next steps

API Reference

Explore all 21 endpoints in detail with interactive examples.

Error Handling

Understand error responses and processing statuses.