API Quickstart

Quick Start Guide

Get your first interview running in under 5 minutes with this step-by-step guide.

Get Your API Key

Sign up at app.jobhive.ai if you haven’t already
Navigate to Settings → API Keys
Click “Generate API Key” and copy it securely

export JOBHIVE_API_KEY="jh_live_your_api_key_here"

Create Your First Interview

Use our API to schedule an AI-powered interview:

cURL

curl -X POST "https://backend.jobhive.ai/v1/interviews" \
  -H "Authorization: Bearer $JOBHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_email": "candidate@example.com",
    "position": "Software Engineer", 
    "skills": ["JavaScript", "React", "Node.js"],
    "duration_minutes": 30
  }'

You’ll get a response like this:

{
  "success": true,
  "data": {
    "id": "int_abc123def456",
    "interview_url": "https://app.jobhive.ai/interview/int_abc123def456",
    "status": "scheduled",
    "candidate_email": "candidate@example.com"
  }
}

Share Interview Link

Send the interview_url to your candidate. They can start the interview immediately - no account required!

Get Results

Once completed, fetch the results:

cURL

curl -X GET "https://backend.jobhive.ai/v1/interviews/int_abc123def456?include_results=true" \
  -H "Authorization: Bearer $JOBHIVE_API_KEY"

Complete Code Examples

JavaScript/Node.js

const fetch = require('node-fetch');

const JOBHIVE_API_KEY = process.env.JOBHIVE_API_KEY;
const BASE_URL = 'https://backend.jobhive.ai/v1';

async function createInterview() {
  const response = await fetch(`${BASE_URL}/interviews`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${JOBHIVE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      candidate_email: 'john.doe@example.com',
      position: 'Full Stack Developer',
      skills: ['JavaScript', 'React', 'Python', 'Django'],
      duration_minutes: 45,
      difficulty: 'intermediate'
    })
  });

  const interview = await response.json();
  console.log('Interview created:', interview.data.id);
  console.log('Share this link:', interview.data.interview_url);
  
  return interview.data;
}

async function getResults(interviewId) {
  const response = await fetch(`${BASE_URL}/interviews/${interviewId}?include_results=true`, {
    headers: {
      'Authorization': `Bearer ${JOBHIVE_API_KEY}`
    }
  });

  const interview = await response.json();
  
  if (interview.data.status === 'completed') {
    console.log('Overall Score:', interview.data.results.overall_score);
    console.log('Recommendation:', interview.data.results.recommendation);
    console.log('Strengths:', interview.data.results.strengths);
  }
  
  return interview.data;
}

// Usage
createInterview()
  .then(interview => {
    console.log('Waiting for interview completion...');
    // In practice, use webhooks for real-time updates
    setTimeout(() => getResults(interview.id), 60000); // Check after 1 minute
  })
  .catch(console.error);

const { JobHive } = require('@jobhive/sdk');

const client = new JobHive({
  apiKey: process.env.JOBHIVE_API_KEY
});

async function quickInterview() {
  try {
    // Create interview
    const interview = await client.interviews.create({
      candidate_email: 'jane.smith@example.com',
      position: 'Frontend Developer',
      skills: ['React', 'TypeScript', 'CSS'],
      duration_minutes: 30,
      send_invitation: true // Automatically email candidate
    });

    console.log('✅ Interview scheduled:', interview.id);
    console.log('📧 Invitation sent to:', interview.candidate_email);
    console.log('🔗 Interview URL:', interview.interview_url);

    // Set up webhook listener (in practice)
    client.on('interview.completed', (data) => {
      console.log('🎉 Interview completed!');
      console.log('📊 Score:', data.results.overall_score);
      console.log('💡 Recommendation:', data.results.recommendation);
    });

    return interview;
  } catch (error) {
    console.error('❌ Error creating interview:', error.message);
  }
}

quickInterview();

Python

import requests
import os
import time

JOBHIVE_API_KEY = os.environ['JOBHIVE_API_KEY']
BASE_URL = 'https://backend.jobhive.ai/v1'

def create_interview():
    response = requests.post(f'{BASE_URL}/interviews', 
        headers={
            'Authorization': f'Bearer {JOBHIVE_API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'candidate_email': 'alice.johnson@example.com',
            'position': 'Data Scientist',
            'skills': ['Python', 'Machine Learning', 'SQL', 'Pandas'],
            'duration_minutes': 60,
            'difficulty': 'senior'
        }
    )
    
    interview = response.json()
    print(f"Interview created: {interview['data']['id']}")
    print(f"Share this link: {interview['data']['interview_url']}")
    
    return interview['data']

def get_results(interview_id):
    response = requests.get(f'{BASE_URL}/interviews/{interview_id}?include_results=true',
        headers={'Authorization': f'Bearer {JOBHIVE_API_KEY}'}
    )
    
    interview = response.json()
    
    if interview['data']['status'] == 'completed':
        results = interview['data']['results']
        print(f"Overall Score: {results['overall_score']}")
        print(f"Technical Score: {results['technical_score']}")
        print(f"Communication Score: {results['communication_score']}")
        print(f"Recommendation: {results['recommendation']}")
        
        print("\nStrengths:")
        for strength in results['strengths']:
            print(f"  ✅ {strength}")
            
        print("\nAreas for Improvement:")
        for area in results['areas_for_improvement']:
            print(f"  📈 {area}")
    
    return interview['data']

# Usage
if __name__ == "__main__":
    interview = create_interview()
    
    print("Waiting for interview completion...")
    # In practice, use webhooks for real-time updates
    time.sleep(60)  # Wait 1 minute then check
    get_results(interview['id'])

import jobhive
import os

client = jobhive.JobHive(api_key=os.environ['JOBHIVE_API_KEY'])

def quick_interview():
    try:
        # Create interview
        interview = client.interviews.create(
            candidate_email='bob.wilson@example.com',
            position='Backend Engineer',
            skills=['Python', 'Django', 'PostgreSQL', 'Redis'],
            duration_minutes=45,
            company_name='TechCorp',
            instructions='Focus on database design and API architecture'
        )

        print(f"✅ Interview scheduled: {interview.id}")
        print(f"📧 Candidate: {interview.candidate_email}")
        print(f"🔗 Interview URL: {interview.interview_url}")

        # Monitor interview status
        @client.webhooks.on('interview.completed')
        def handle_completion(event):
            print("🎉 Interview completed!")
            results = event.data.results
            
            print(f"📊 Overall Score: {results.overall_score}/100")
            print(f"🧠 Technical Score: {results.technical_score}/100")
            print(f"💬 Communication Score: {results.communication_score}/100")
            print(f"💡 Recommendation: {results.recommendation}")
            
            if results.recommendation == 'hire':
                print("🎯 Strong candidate - recommend moving forward!")

        return interview
        
    except jobhive.APIError as e:
        print(f"❌ API Error: {e.message}")
    except Exception as e:
        print(f"❌ Error: {e}")

if __name__ == "__main__":
    quick_interview()

Common Use Cases

Bulk Interview Creation

Create multiple interviews efficiently:

async function createBulkInterviews(candidates) {
  const interviews = [];
  
  for (const candidate of candidates) {
    const interview = await fetch(`${BASE_URL}/interviews`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${JOBHIVE_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        candidate_email: candidate.email,
        position: candidate.position,
        skills: candidate.skills,
        duration_minutes: 30
      })
    });
    
    interviews.push(await interview.json());
  }
  
  return interviews;
}

// Usage
const candidates = [
  { email: 'dev1@example.com', position: 'Frontend Developer', skills: ['React', 'TypeScript'] },
  { email: 'dev2@example.com', position: 'Backend Developer', skills: ['Node.js', 'PostgreSQL'] },
  { email: 'dev3@example.com', position: 'Full Stack Developer', skills: ['React', 'Node.js'] }
];

createBulkInterviews(candidates)
  .then(results => console.log(`Created ${results.length} interviews`))
  .catch(console.error);

import concurrent.futures
import requests

def create_single_interview(candidate):
    response = requests.post(f'{BASE_URL}/interviews',
        headers={
            'Authorization': f'Bearer {JOBHIVE_API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'candidate_email': candidate['email'],
            'position': candidate['position'],
            'skills': candidate['skills'],
            'duration_minutes': 30
        }
    )
    return response.json()

def create_bulk_interviews(candidates):
    with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
        futures = [executor.submit(create_single_interview, candidate) 
                  for candidate in candidates]
        
        results = []
        for future in concurrent.futures.as_completed(futures):
            results.append(future.result())
        
        return results

# Usage
candidates = [
    {'email': 'eng1@example.com', 'position': 'Software Engineer', 'skills': ['Python', 'Django']},
    {'email': 'eng2@example.com', 'position': 'DevOps Engineer', 'skills': ['Docker', 'Kubernetes']},
    {'email': 'eng3@example.com', 'position': 'Data Engineer', 'skills': ['Spark', 'Airflow']}
]

interviews = create_bulk_interviews(candidates)
print(f"Created {len(interviews)} interviews successfully")

Real-time Interview Monitoring

Set up webhooks to monitor interview progress:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

app.post('/webhooks/jobhive', (req, res) => {
  const signature = req.headers['x-jobhive-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.JOBHIVE_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event, data } = req.body;
  
  switch(event) {
    case 'interview.started':
      console.log(`🎬 Interview ${data.id} started by ${data.candidate.email}`);
      // Notify hiring team
      break;
      
    case 'interview.completed':
      console.log(`✅ Interview ${data.id} completed`);
      console.log(`📊 Score: ${data.results.overall_score}`);
      console.log(`💡 Recommendation: ${data.results.recommendation}`);
      
      // Auto-schedule next round for strong candidates
      if (data.results.overall_score >= 80) {
        scheduleHumanInterview(data);
      }
      break;
      
    case 'candidate.no_show':
      console.log(`❌ Candidate ${data.candidate_email} didn't show for interview ${data.interview_id}`);
      // Send follow-up email
      break;
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

def verify_webhook(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, f"sha256={expected_signature}")

@app.route('/webhooks/jobhive', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-JobHive-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook(payload, signature, os.environ['JOBHIVE_WEBHOOK_SECRET']):
        return 'Invalid signature', 401
    
    data = request.get_json()
    event = data.get('event')
    event_data = data.get('data')
    
    if event == 'interview.completed':
        process_interview_results(event_data)
    elif event == 'interview.started':
        notify_hiring_team(event_data)
    elif event == 'results.analyzed':
        update_candidate_record(event_data)
    
    return jsonify({'status': 'success'}), 200

def process_interview_results(data):
    interview_id = data['id']
    score = data['results']['overall_score']
    recommendation = data['results']['recommendation']
    
    print(f"Interview {interview_id} completed with score {score}")
    
    # Auto-advance strong candidates
    if recommendation == 'hire':
        schedule_next_round(data['candidate_email'])

if __name__ == '__main__':
    app.run(port=5000)

Error Handling

Common Errors and Solutions

401 Unauthorized

Problem: API key missing or invalidSolution:

// Check your API key format and environment variable
if (!process.env.JOBHIVE_API_KEY) {
  throw new Error('JOBHIVE_API_KEY environment variable is required');
}

if (!process.env.JOBHIVE_API_KEY.startsWith('jh_')) {
  throw new Error('Invalid API key format. Should start with jh_');
}

429 Rate Limit Exceeded

Problem: Too many requests per minuteSolution:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('X-RateLimit-Retry-After');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

400 Validation Error

Problem: Invalid request parametersSolution:

function validateInterviewData(data) {
  const errors = [];
  
  if (!data.candidate_email || !data.candidate_email.includes('@')) {
    errors.push('Valid candidate_email is required');
  }
  
  if (!data.position || data.position.length < 2) {
    errors.push('Position must be at least 2 characters');
  }
  
  if (!data.skills || data.skills.length === 0) {
    errors.push('At least one skill is required');
  }
  
  if (data.duration_minutes < 15 || data.duration_minutes > 90) {
    errors.push('Duration must be between 15 and 90 minutes');
  }
  
  if (errors.length > 0) {
    throw new Error(`Validation errors: ${errors.join(', ')}`);
  }
}

Next Steps

Explore Full API Reference

Complete documentation for all endpoints and features

Set Up Webhooks

Real-time notifications for interview events

JavaScript SDK

Official SDK for Node.js and browser applications

Python SDK

Official SDK for Python applications

Development Tip: Start with test mode interviews to familiarize yourself with the API without consuming production credits. Add "test_mode": true to any interview creation request.

Pro Tip: Use webhooks instead of polling for real-time updates. They’re more efficient and provide better user experience.

Getting Started

Core Resources

Advanced Features

Quick Start Guide

Complete Code Examples

JavaScript/Node.js

Python

Common Use Cases

Bulk Interview Creation

Real-time Interview Monitoring

Error Handling

Common Errors and Solutions

Next Steps

Explore Full API Reference

Set Up Webhooks

JavaScript SDK

Python SDK

​Quick Start Guide

​Complete Code Examples

​JavaScript/Node.js

​Python

​Common Use Cases

​Bulk Interview Creation

​Real-time Interview Monitoring

​Error Handling

​Common Errors and Solutions

​Next Steps

Explore Full API Reference

Set Up Webhooks

JavaScript SDK

Python SDK

Quick Start Guide

Complete Code Examples

JavaScript/Node.js

Python

Common Use Cases

Bulk Interview Creation

Real-time Interview Monitoring

Error Handling

Common Errors and Solutions

Next Steps