Tanova API Documentation

Create a new job posting

Request Body

{
  "title": "Senior Full-Stack Engineer",
  "company": "Acme Inc",
  "description": "Full job description including requirements, responsibilities, etc...",
  "requirements_json": {  // Optional - AI will extract from description if not provided
    "must_have_skills": ["React", "Node.js", "PostgreSQL"],
    "nice_to_have_skills": ["TypeScript", "Docker"],
    "years_experience": 5,
    "education_level": "Bachelor's degree"
  },
  "is_public": true,  // optional - default false
  "public_slug": "senior-fullstack-engineer"  // optional - auto-generated if not provided
}

Response

{
  "id": 123,
  "title": "Senior Full-Stack Engineer",
  "company": "Acme Inc",
  "is_public": true,
  "public_slug": "senior-fullstack-engineer",
  "public_url": "https://tanova.ai/jobs/senior-fullstack-engineer",
  "created_at": "2025-01-15T10:30:00Z"
}

Asynchronous: Creates a new evaluation and queues it for processing. The evaluation takes 60 seconds to complete. Poll the GET endpoint to retrieve results. (1.0 credits)

Request Body (Option 1: Existing Candidate)

{
  "job_id": 123,
  "candidate_id": 456  // Use existing candidate by ID
}

Request Body (Option 2: Inline Candidate Data)

{
  "job_id": 123,
  "candidate": {
    "name": "Sarah Johnson",
    "email": "sarah@example.com",
    "cv_text": "Full CV text..."
  }
}

Immediate Response (Status: Processing)

{
  "id": 890,
  "candidate_id": 458,
  "job_id": 123,
  "status": "processing",
  "aggregate_score": null,
  "recommendation": null,
  "summary": null,
  "created_at": "2025-01-15T10:45:00Z",
  "estimated_completion": "60 seconds"
}

Completed Response (After Polling GET /api/v1/evaluations/{id})

{
  "id": 890,
  "candidate": {
    "id": 458,
    "name": "Sarah Johnson",
    "email": "sarah@example.com",
    "cv_url": "https://tanova.ai/storage/cvs/458.pdf"
  },
  "job": {
    "id": 123,
    "title": "Senior Full-Stack Engineer",
    "company": "Acme Inc"
  },
  "aggregate_score": 82,
  "recommendation": "yes",
  "confidence_level": "high",
  "summary": "Strong candidate with excellent technical skills...",
  "strengths": ["5+ years React experience", "Strong problem-solving"],
  "concerns": ["Limited backend experience"],
  "scores": {
    "qualification": 9,
    "capability": 9,
    "situational": 7,
    "reward": 8,
    "culture": 8,
    "career": 7,
    "compensation": 8
  },
  "high_level_assessment": {
    "skills": 9.0,
    "judgment": 8.0,
    "agency": 7.0
  },
  "hidden_gem_potential": "Self-taught developer with strong portfolio despite non-traditional background. Shows exceptional problem-solving ability.",
  "interview_questions": [
    "Tell me about your experience with React performance optimization",
    "How do you approach database design?"
  ],
  "status": "completed",
  "created_at": "2025-01-15T10:45:00Z",
  "updated_at": "2025-01-15T10:46:23Z"
}