Skip to main content

​
Endpoint

curl -X POST https://api.fairmatch.ai/api/jobs/{job_id}/import_excel \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]"

​
Path parameters

​
job_id
string
required
The unique identifier of the job to import candidates for

​
Request body

​
file
file
required
Excel file (.xlsx) containing candidate data. Must include required columns.

​
Excel file format

Your Excel file must include these required columns:
​
name
string
required
The candidate’s full name
​
email
string
required
The candidate’s email address
​
skills
string
required
Comma-separated list of skills (e.g., “Python, React, PostgreSQL”)
​
experience
integer
required
Years of professional experience
Optional columns:
​
projects
string
Description of relevant projects or work experience
​
resume_text
string
Full text content of the candidate’s resume

​
How it works

When you upload an Excel file, FairMatch AI:
  1. Validates that the file is in .xlsx format
  2. Checks for all required columns (name, email, skills, experience)
  3. Processes each row, skipping rows with missing name or email
  4. Parses comma-separated skills into an array
  5. Creates candidate records with unique IDs
  6. Inserts all candidates into the database
  7. Returns the array of created candidate objects

​
Response

Returns an array of successfully imported candidate objects.
​
id
string
Unique identifier assigned to the candidate
​
job_id
string
The job posting identifier
​
name
string
The candidate’s full name
​
email
string
The candidate’s email address
​
skills
array
Array of skill strings
​
experience
integer
Years of professional experience
​
projects
string
Description of relevant projects (empty string if not provided)
​
resume_text
string
Full resume text content (empty string if not provided)
​
github_link
string
GitHub profile URL (empty string by default)
​
linkedin_link
string
LinkedIn profile URL (empty string by default)
​
interview_answers
array
Array of interview responses (empty array by default)

​
Response example

[
  {
    "id": "a1b2c3d4",
    "job_id": "job_123",
    "name": "Sarah Johnson",
    "email": "[email protected]",
    "skills": ["Python", "React", "PostgreSQL"],
    "experience": 5,
    "projects": "Built scalable microservices architecture",
    "resume_text": "Experienced full-stack engineer...",
    "github_link": "",
    "linkedin_link": "",
    "interview_answers": []
  },
  {
    "id": "e5f6g7h8",
    "job_id": "job_123",
    "name": "Michael Chen",
    "email": "[email protected]",
    "skills": ["JavaScript", "TypeScript", "Node.js"],
    "experience": 3,
    "projects": "",
    "resume_text": "",
    "github_link": "",
    "linkedin_link": "",
    "interview_answers": []
  }
]

​
Error responses

​
detail
string
Error message describing what went wrong

​
Status codes

  • 200 - Candidates imported successfully
  • 400 - Invalid file format, missing columns, or data parsing error
  • 500 - Internal server error during import

​
Example Excel file

nameemailskillsexperienceprojectsresume_text
Sarah Johnson[email protected]Python, React, PostgreSQL5Built scalable microservicesExperienced engineer…
Michael Chen[email protected]JavaScript, TypeScript3E-commerce platformFrontend specialist…
Emma Davis[email protected]Java, Spring Boot, AWS7Cloud migration projectSenior backend dev…
Rows with missing or empty name or email values will be automatically skipped during import.

​
Use cases

  • Bulk candidate upload: Import dozens or hundreds of candidates at once
  • Recruitment events: Upload attendee data from job fairs or campus recruiting
  • ATS migration: Transfer candidate data from another applicant tracking system
  • Agency partnerships: Import candidate pools from recruiting agencies

Build docs developers (and LLMs) love

Get started for freeTalk to us