Complete Job Workflow: Create, Search & Assess

This recipe walks you through the complete hiring workflow using the B2D API: creating a job description, finding matching candidates, and assessing their fit.

Overview

What you’ll accomplish:
  1. Create a job description entry for AI-powered matching
  2. Search for developers that match your requirements
  3. Assess top candidates with detailed AI analysis
  4. Get personalized outreach emails and scoring
Total time: ~5 minutes
Credits used: 1 per candidate returned + 1 per assessment

Step 1: Create Your Job Description

First, create a job entry that will be used for AI-powered candidate matching.
import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

job_data = {
    "description": """Senior Python Developer - AI/ML Focus

We're looking for an experienced Python developer to join our AI/ML team at a fast-growing startup.

Requirements:
- 5+ years of Python development experience
- Strong experience with machine learning frameworks (PyTorch, TensorFlow, scikit-learn)
- Experience with REST APIs (Flask, FastAPI, Django)
- Cloud platforms (AWS, GCP) experience preferred
- Open source contributions are a plus

Responsibilities:
- Build and deploy ML models in production
- Design scalable data processing pipelines
- Develop REST APIs for ML services
- Collaborate with data scientists and engineers
- Contribute to our open-source ML toolkit

What we offer:
- Competitive salary + equity
- Remote-first culture
- Learning budget for conferences/courses
- Work with cutting-edge AI technology"""
}

# Create the job
response = requests.post("https://api.b2d.ai/jobs/create", 
                        headers=headers, json=job_data)

if response.status_code == 200:
    job_id = response.json()['id']
    print(f"✅ Job created successfully: {job_id}")
else:
    print(f"❌ Error creating job: {response.json()}")
    exit()
Expected output:
✅ Job created successfully: 550e8400-e29b-41d4-a716-446655440000

Step 2: Search for Matching Candidates

Use AI-powered semantic search to find developers whose GitHub profiles match your job requirements.
# Search for candidates matching our job
search_params = {
    "size": 25,  # Get top 25 candidates
    "countries": ["United States", "Canada", "United Kingdom"],
    "required_fields": ["email", "full_name"],  # Only candidates with contact info
    "summary_length": 2048  # Detailed summaries for assessment
}

search_response = requests.get(
    f"https://api.b2d.ai/jobs/{job_id}/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    params=search_params
)

if search_response.status_code == 200:
    candidates = search_response.json()['results']
    print(f"✅ Found {len(candidates)} matching candidates")
    
    # Show top 5 candidates
    print("\n🔍 Top candidates:")
    for i, candidate in enumerate(candidates[:5], 1):
        name = candidate.get('full_name', 'N/A')
        username = candidate['github_username']
        location = candidate.get('location', 'N/A')
        followers = candidate.get('followers', 0)
        
        print(f"{i}. {name} (@{username})")
        print(f"   📍 {location} | 👥 {followers} followers")
        
        # Show top skills
        skills = candidate.get('skills', [])[:3]
        if skills:
            skill_str = ', '.join([f"{s['skill']} ({s['score']})" for s in skills])
            print(f"   🛠️  Top skills: {skill_str}")
        print()
    
    # Check credit usage
    credits_used = int(search_response.headers.get('X-Credits-Used', 0))
    credits_remaining = search_response.headers.get('X-Credits-Remaining')
    print(f"💳 Credits used: {len(candidates)} | Remaining: {credits_remaining}")
    
else:
    print(f"❌ Error searching candidates: {search_response.json()}")
    exit()
Expected output:
✅ Found 25 matching candidates

🔍 Top candidates:
1. Sarah Chen (@sarah-ml-dev)
   📍 San Francisco, CA | 👥 1250 followers
   🛠️  Top skills: Python (95), PyTorch (88), Machine Learning (92)

2. Alex Rodriguez (@alexr-data)
   📍 Toronto, ON | 👥 890 followers
   🛠️  Top skills: TensorFlow (90), Python (94), FastAPI (85)

3. Jamie Thompson (@jamie-ai)
   📍 London, UK | 👥 2100 followers
   🛠️  Top skills: scikit-learn (89), AWS (87), Python (96)

💳 Credits used: 25 | Remaining: 4975

Step 3: Assess Top Candidates

Get detailed AI-powered assessments for your most promising candidates.
# Assess top 3 candidates
top_candidates = candidates[:3]
assessments = []

print("🔍 Assessing top candidates...\n")

for candidate in top_candidates:
    username = candidate['github_username']
    
    # Optional: Add context for better assessment
    assess_params = {
        "context": "Early-stage startup, remote-first, equity package, fast growth",
        "summary_length": 1500
    }
    
    assess_response = requests.get(
        f"https://api.b2d.ai/jobs/{job_id}/assess/{username}",
        headers={"x-api-key": "YOUR_API_KEY"},
        params=assess_params
    )
    
    if assess_response.status_code == 200:
        assessment = assess_response.json()
        assessments.append(assessment)
        
        # Display assessment results
        name = assessment.get('full_name', username)
        fit_score = assessment['fit']
        hire_score = assessment['hireability']
        
        print(f"📊 Assessment for {name} (@{username})")
        print(f"   🎯 Job Fit: {fit_score}/10")
        print(f"   ⭐ Hireability: {hire_score}/10")
        print(f"   📝 Summary: {assessment['fit_summary']}")
        print(f"\n   📧 Suggested Outreach:")
        print(f"   \"{assessment['email_copy']}\"\n")
        
        # Check assessment credits
        assess_credits = assess_response.headers.get('X-Credits-Used-Assess')
        print(f"   💳 Assessment credits used: {assess_credits}")
        print("-" * 80)
        
    else:
        print(f"❌ Error assessing {username}: {assess_response.json()}")

print(f"\n✅ Completed assessments for {len(assessments)} candidates")
Expected output:
🔍 Assessing top candidates...

📊 Assessment for Sarah Chen (@sarah-ml-dev)
   🎯 Job Fit: 9/10
   ⭐ Hireability: 8/10
   📝 Summary: Excellent fit with extensive PyTorch experience and ML pipeline work at her pytorch-experiments and ml-production-tools repositories, directly matching the ML engineering requirements.

   📧 Suggested Outreach:
   "Hi Sarah, I noticed your impressive work on pytorch-experiments and ml-production-tools repositories. Your experience building production ML pipelines and PyTorch implementations would be perfect for our AI/ML team. Would you be interested in discussing this Senior Python Developer opportunity?"

   💳 Assessment credits used: 1
--------------------------------------------------------------------------------
📊 Assessment for Alex Rodriguez (@alexr-data)
   🎯 Job Fit: 8/10
   ⭐ Hireability: 9/10
   📝 Summary: Strong match with TensorFlow expertise and FastAPI experience shown in his data-api-framework and tf-serving-utils repos, plus solid cloud deployment background.

   📧 Suggested Outreach:
   "Hi Alex, your work on data-api-framework and tf-serving-utils caught my attention. Your combination of TensorFlow expertise and FastAPI skills aligns perfectly with our ML infrastructure needs. I'd love to discuss a Senior Python Developer role with us!"

   💳 Assessment credits used: 2
--------------------------------------------------------------------------------
📊 Assessment for Jamie Thompson (@jamie-ai)
   🎯 Job Fit: 8/10
   ⭐ Hireability: 9/10
   📝 Summary: Great fit with scikit-learn mastery and AWS deployment experience from scikit-pipeline-tools and aws-ml-deploy repositories, showing both ML and cloud operations skills.

   📧 Suggested Outreach:
   "Hi Jamie, I'm impressed by your scikit-pipeline-tools and aws-ml-deploy projects. Your expertise in ML pipelines and AWS deployments would be valuable for our growing AI team. Are you open to exploring a Senior Python Developer opportunity?"

   💳 Assessment credits used: 3
--------------------------------------------------------------------------------

✅ Completed assessments for 3 candidates

Step 4: Export Results and Next Steps

Save your results and plan your outreach strategy.
import json
from datetime import datetime

# Create summary report
report = {
    "job_id": job_id,
    "search_date": datetime.now().isoformat(),
    "search_results": len(candidates),
    "assessments_completed": len(assessments),
    "top_candidates": []
}

# Add top candidates to report
for assessment in assessments:
    candidate_summary = {
        "name": assessment.get('full_name'),
        "github_username": assessment['github_username'],
        "email": assessment.get('email'),
        "fit_score": assessment['fit'],
        "hireability_score": assessment['hireability'],
        "fit_summary": assessment['fit_summary'],
        "email_copy": assessment['email_copy'],
        "location": assessment.get('location'),
        "company": assessment.get('company'),
        "followers": assessment.get('followers')
    }
    report["top_candidates"].append(candidate_summary)

# Save report
with open(f"hiring_report_{job_id[:8]}.json", "w") as f:
    json.dump(report, f, indent=2)

print(f"📄 Report saved to hiring_report_{job_id[:8]}.json")

# Display action items
print("\n📋 Next Steps:")
print("1. Review the personalized email templates above")
print("2. Reach out to high-scoring candidates (8+ fit score)")
print("3. Schedule initial screening calls")
print("4. Use /user endpoint to get complete profiles for finalists")
print("5. Check out their GitHub repositories mentioned in assessments")

# Show final credit usage
final_credits = search_response.headers.get('X-Credits-Used')
assess_credits = assess_response.headers.get('X-Credits-Used-Assess')
remaining = assess_response.headers.get('X-Credits-Remaining')

print(f"\n💰 Final Credit Usage:")
print(f"   Search: {len(candidates)} credits")
print(f"   Assessments: {assess_credits} credits") 
print(f"   Total used: {final_credits}")
print(f"   Remaining: {remaining}")

Complete Workflow Script

Here’s the complete script that combines all steps:
import requests
import json
from datetime import datetime

def complete_hiring_workflow(api_key, job_description):
    """Complete hiring workflow: create job, search, and assess candidates"""
    
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json"
    }
    
    print("🚀 Starting complete hiring workflow...\n")
    
    # Step 1: Create job
    print("📝 Creating job description...")
    job_response = requests.post("https://api.b2d.ai/jobs/create", 
                                headers=headers, json={"description": job_description})
    
    if job_response.status_code != 200:
        print(f"❌ Failed to create job: {job_response.json()}")
        return None
    
    job_id = job_response.json()['id']
    print(f"✅ Job created: {job_id}")
    
    # Step 2: Search candidates
    print("\n🔍 Searching for candidates...")
    search_params = {
        "size": 20,
        "countries": ["United States", "Canada", "United Kingdom"],
        "required_fields": ["email", "full_name"],
        "summary_length": 2048
    }
    
    search_response = requests.get(f"https://api.b2d.ai/jobs/{job_id}/search",
                                  headers={"x-api-key": api_key}, params=search_params)
    
    if search_response.status_code != 200:
        print(f"❌ Search failed: {search_response.json()}")
        return None
    
    candidates = search_response.json()['results']
    print(f"✅ Found {len(candidates)} candidates")
    
    # Step 3: Assess top 5 candidates
    print("\n🎯 Assessing top candidates...")
    assessments = []
    
    for candidate in candidates[:5]:
        username = candidate['github_username']
        assess_response = requests.get(f"https://api.b2d.ai/jobs/{job_id}/assess/{username}",
                                      headers={"x-api-key": api_key})
        
        if assess_response.status_code == 200:
            assessment = assess_response.json()
            assessments.append(assessment)
            
            name = assessment.get('full_name', username)
            print(f"  📊 {name}: Fit {assessment['fit']}/10, Hire {assessment['hireability']}/10")
    
    # Generate report
    report = {
        "job_id": job_id,
        "date": datetime.now().isoformat(),
        "candidates_found": len(candidates),
        "assessments": len(assessments),
        "top_candidates": [
            {
                "name": a.get('full_name'),
                "github_username": a['github_username'],
                "email": a.get('email'),
                "fit_score": a['fit'],
                "hireability": a['hireability'],
                "outreach": a['email_copy']
            }
            for a in assessments
        ]
    }
    
    print(f"\n✅ Workflow complete! Assessed {len(assessments)} candidates")
    return report

# Usage
if __name__ == "__main__":
    API_KEY = "YOUR_API_KEY"
    
    JOB_DESCRIPTION = """Senior Python Developer - AI/ML Focus
    
We're seeking an experienced Python developer for our AI/ML team...
[Your full job description here]"""
    
    result = complete_hiring_workflow(API_KEY, JOB_DESCRIPTION)
    if result:
        with open("hiring_results.json", "w") as f:
            json.dump(result, f, indent=2)
        print("📄 Results saved to hiring_results.json")

Key Benefits

AI-Powered Matching: Find candidates based on actual GitHub activity, not just keywords
Comprehensive Assessment: Get detailed fit analysis and personalized outreach
Time Efficient: Complete workflow in under 5 minutes
Cost Effective: ~25-30 credits for a complete hiring pipeline
Actionable Results: Ready-to-use email templates and scoring

Next Steps

  • Scale Up: Use larger search sizes (up to 1000 candidates)
  • Filter Better: Add more specific required_fields or geographic filters
  • Iterate: Refine your job description based on candidate quality
  • Integrate: Build this workflow into your existing hiring tools