Skip to main content
Prerequisites:
  • API key from your JobHive dashboard
  • Node.js version 18+ (for JavaScript/TypeScript)
  • Python 3.10+ (for Python integrations)
  • Docker and Docker Compose (for local development)
  • PostgreSQL 14+ (for database development)
Get up and running with JobHive’s AI-powered interview platform in minutes. This guide covers both platform integration and local development setup. JobHive Development Workflow - Diagram showing platform integration paths, local development setup, and API integration flow
1

Get Your API Key

  1. Log into your JobHive dashboard
  2. Navigate to SettingsAPI Keys
  3. Generate a new API key for your application
  4. Copy and securely store your API key
# Set your API key as environment variable
export JOBHIVE_API_KEY="your_api_key_here"
2

Choose Your Development Path

  • Platform Integration
  • Local Development
  • Frontend Development
Use JobHive’s hosted API for production applications and integrations.
# Test API connectivity
curl -X GET "https://backend.jobhive.ai/api/v1/health/" \
  -H "Authorization: Bearer YOUR_API_KEY"
Direct API Integration:
# Test API connectivity
curl -X GET "https://backend.jobhive.ai/api/v1/health/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
3

Create Your First Interview

  • JavaScript
  • Python
  • cURL
import axios from 'axios';

const apiClient = axios.create({
  baseURL: 'https://backend.jobhive.ai/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.JOBHIVE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const response = await apiClient.post('/interviews/', {
  job: {
    title: "Senior Full Stack Developer",
    description: "We're looking for an experienced developer...",
    requirements: "5+ years experience, React, Node.js, PostgreSQL"
  },
  candidate_email: "[email protected]",
  skills_to_assess: ["JavaScript", "React", "Node.js", "System Design"],
  duration_minutes: 60,
  difficulty_level: "senior"
});

const interview = response.data;
console.log(`Interview created: ${interview.session_id}`);
console.log(`Candidate link: ${interview.candidate_link}`);

Local Development Environment

Backend Setup

1

Database Setup

# Start PostgreSQL with Docker
docker run --name jobhive-postgres \
  -e POSTGRES_DB=jobhive_dev \
  -e POSTGRES_USER=jobhive \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 -d postgres:14

# Or use Docker Compose
docker-compose -f docker-compose.local.yml up postgres
2

Redis Setup

# Start Redis for caching and WebSockets
docker run --name jobhive-redis -p 6379:6379 -d redis:7-alpine
3

Environment Configuration

Create a .env.local file:
# Database
DATABASE_URL=postgresql://jobhive:password@localhost/jobhive_dev

# Redis
REDIS_URL=redis://localhost:6379/0

# API Keys
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# AWS (for local S3-compatible storage)
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_STORAGE_BUCKET_NAME=jobhive-dev
AWS_S3_ENDPOINT_URL=http://localhost:9000

# Development settings
DEBUG=True
USE_TZ=True
SECRET_KEY=your-secret-key-for-development
4

Start Development Server

# Install dependencies
pip install -r requirements/local.txt

# Run migrations
python manage.py migrate

# Load sample data
python manage.py loaddata fixtures/sample_data.json

# Start Celery worker (in separate terminal)
celery -A config worker -l info

# Start Celery beat (in separate terminal)
celery -A config beat -l info

# Start Django server
python manage.py runserver 0.0.0.0:8000

Frontend Development

# Install dependencies for real-time interview interface  
npm install axios socket.io-client react-webcam

# Example real-time interview component
import React, { useState, useEffect } from 'react';
import axios from 'axios';
import io from 'socket.io-client';
import Webcam from 'react-webcam';

function LiveInterview({ sessionId, apiKey }) {
  const [socket, setSocket] = useState(null);
  const [interviewState, setInterviewState] = useState(null);
  const [isConnected, setIsConnected] = useState(false);
  
  useEffect(() => {
    // Initialize WebSocket connection
    const newSocket = io(`wss://backend.jobhive.ai/ws/interview/${sessionId}/`, {
      auth: { token: apiKey }
    });
    
    newSocket.on('connect', () => {
      setIsConnected(true);
    });
    
    newSocket.on('interview_update', (data) => {
      setInterviewState(data);
    });
    
    newSocket.on('question', (data) => {
      console.log('New question:', data.question);
    });
    
    setSocket(newSocket);
    
    return () => newSocket.close();
  }, [sessionId, apiKey]);
  
  const sendResponse = (response) => {
    if (socket && isConnected) {
      socket.emit('candidate_response', {
        session_id: sessionId,
        response: response,
        timestamp: new Date().toISOString()
      });
    }
  };
  
  return (
    <div className="interview-container">
      <div className="video-section">
        <Webcam
          audio={true}
          width={640}
          height={480}
        />
      </div>
      <div className="chat-section">
        {interviewState?.current_question && (
          <div className="question">
            <h3>Current Question:</h3>
            <p>{interviewState.current_question}</p>
          </div>
        )}
        <div className="status">
          Status: {isConnected ? 'Connected' : 'Disconnected'}
        </div>
      </div>
    </div>
  );
}
Frontend Interview Component - React component structure showing video feed, WebSocket connection, and real-time interview state management

Webhook Setup

Configure webhooks to receive real-time updates about interview events.
  • Express.js
  • Django
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Webhook signature verification
function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/jobhive', (req, res) => {
  const signature = req.headers['x-jobhive-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.JOBHIVE_WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  
  const { event, data } = req.body;
  
  switch(event) {
    case 'interview.completed':
      handleInterviewCompleted(data);
      break;
    case 'interview.started':
      handleInterviewStarted(data);
      break;
    case 'candidate.joined':
      handleCandidateJoined(data);
      break;
    case 'analysis.ready':
      handleAnalysisReady(data);
      break;
  }
  
  res.status(200).send('OK');
});

function handleInterviewCompleted(data) {
  console.log('Interview completed:', data);
  // Update your database
  // Send notifications
  // Generate reports
}

Environment Configuration

  • Development
  • Production
  • Docker Compose
# JobHive API Configuration
JOBHIVE_API_KEY=jh_dev_your_api_key_here
JOBHIVE_WEBHOOK_SECRET=whsec_your_webhook_secret
JOBHIVE_ENVIRONMENT=development
JOBHIVE_BASE_URL=https://backend.jobhive.ai/api/v1

# AI Service Configuration
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Database Configuration
DATABASE_URL=postgresql://jobhive:password@localhost/jobhive_dev
REDIS_URL=redis://localhost:6379/0

# File Storage
AWS_STORAGE_BUCKET_NAME=jobhive-dev-bucket
AWS_S3_REGION_NAME=us-east-1

# Security
SECRET_KEY=your-development-secret-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

Testing Your Integration

Test Mode

Use our test mode to validate your integration without consuming credits or creating real interviews.
  • JavaScript
  • Python
// Create a test interview
const response = await apiClient.post('/interviews/', {
  job: {
    title: "Test Position",
    description: "This is a test interview",
    requirements: "No real requirements"
  },  
  candidate_email: "[email protected]",
  skills_to_assess: ["JavaScript", "Problem Solving"],
  test_mode: true,
  duration_minutes: 30
});

const testInterview = response.data;
console.log(`Test interview created: ${testInterview.session_id}`);
console.log(`Test candidate link: ${testInterview.candidate_link}`);

Mock Interview Results

Test interviews return mock results for development purposes:
{
  "session_id": "test_session_123",
  "status": "completed",
  "overall_score": 85.5,
  "skill_scores": {
    "JavaScript": 88.0,
    "Problem Solving": 83.0
  },
  "recommendations": [
    {
      "type": "hire",
      "confidence": 92.3,
      "reasoning": "Strong technical skills with excellent problem-solving approach"
    }
  ],
  "test_mode": true
}

Rate Limits & Quotas

JobHive enforces the following rate limits based on your subscription:
PlanAPI Calls/minConcurrent InterviewsMonthly Interviews
Free60210
Starter1805100
Professional30015500
Enterprise100050Unlimited

Rate Limit Headers

All API responses include rate limit information:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299  
X-RateLimit-Reset: 1234567890
X-RateLimit-Resource: interviews

Handling Rate Limits

  • JavaScript
  • Python
async function createInterviewWithRetry(interviewData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await apiClient.post('/interviews/', interviewData);
      return response.data;
    } catch (error) {
      if (error.response?.status === 429 && attempt < maxRetries) {
        const retryAfter = error.response.headers['retry-after'] || Math.pow(2, attempt);
        console.log(`Rate limited, retrying after ${retryAfter} seconds`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
}

Troubleshooting

Common Causes:
  • Incorrect or missing API key in Authorization header
  • API key for wrong environment (dev vs prod)
  • Expired or revoked API key
Solutions:
# Verify your API key format
curl -X GET "https://backend.jobhive.ai/api/v1/auth/verify/" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Check API key permissions
curl -X GET "https://backend.jobhive.ai/api/v1/auth/permissions/" \
  -H "Authorization: Bearer YOUR_API_KEY"
Symptoms:
  • HTTP 429 responses from API
  • “Rate limit exceeded” error messages
  • Delayed interview creation
Solutions:
  • Implement exponential backoff with jitter
  • Monitor rate limit headers in responses
  • Consider upgrading your subscription plan
  • Cache API responses to reduce redundant calls
  • Use webhooks instead of polling for status updates
Troubleshooting Steps:
  1. Verify webhook URL is publicly accessible (use tools like ngrok for local testing)
  2. Check webhook secret is correctly configured
  3. Ensure endpoint returns HTTP 200 status
  4. Verify request signature validation
  5. Check firewall and security group settings
Test Webhook:
# Test webhook endpoint
curl -X POST "https://your-domain.com/webhooks/jobhive" \
  -H "Content-Type: application/json" \
  -H "X-JobHive-Signature: test-signature" \
  -d '{"event": "test", "data": {}}'
Common Problems:
  • Connection drops during interviews
  • Unable to establish WebSocket connection
  • Authentication failures on WebSocket
Solutions:
// Implement connection retry logic
const connectWithRetry = (sessionId, apiKey, maxRetries = 3) => {
  let retries = 0;
  
  const connect = () => {
    const socket = io(`wss://backend.jobhive.ai/ws/interview/${sessionId}/`, {
      auth: { token: apiKey },
      transports: ['websocket', 'polling']
    });
    
    socket.on('connect_error', (error) => {
      if (retries < maxRetries) {
        retries++;
        setTimeout(connect, Math.pow(2, retries) * 1000);
      }
    });
    
    return socket;
  };
  
  return connect();
};
Validation Errors:
  • Missing required fields (job title, candidate email)
  • Invalid skill names or difficulty levels
  • Malformed email addresses
Example Valid Request:
{
  "job": {
    "title": "Software Engineer",
    "description": "Looking for a full-stack developer",
    "requirements": "React, Node.js, 3+ years experience"
  },
  "candidate_email": "[email protected]",
  "skills_to_assess": ["JavaScript", "React", "Node.js"],
  "duration_minutes": 45,
  "difficulty_level": "intermediate"
}
Database Connection Problems:
# Check PostgreSQL is running
docker ps | grep postgres

# Test database connection
psql postgresql://jobhive:password@localhost/jobhive_dev
Redis Connection Issues:
# Check Redis is running
docker ps | grep redis

# Test Redis connection
redis-cli -h localhost -p 6379 ping
Django Migration Errors:
# Reset migrations (development only)
python manage.py migrate --fake-initial

# Check migration status
python manage.py showmigrations

Support & Resources

Getting Help

When reaching out for support, please include:
  • API Version: Which API version you’re using
  • Request/Response: Full HTTP request and response (remove sensitive data)
  • Error Details: Complete error messages and stack traces
  • Environment: Development, staging, or production
  • Timestamp: When the issue occurred (with timezone)
Response Times:
  • Free Plan: 2-3 business days
  • Paid Plans: 24 hours for technical issues
  • Enterprise: Dedicated Slack channel with 4-hour response SLA