POST /api/v1/invitations

Authorization: Bearer rz_live_...
Content-Type: application/json
Idempotency-Key: unique-key-12345 (optional)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "candidate_name": "Jane Smith",
  "candidate_cv": {
    "summary": "Experienced software engineer with 5+ years in React and TypeScript",
    "workExperiences": [
      {
        "company": "Tech Corp",
        "title": "Senior Developer",
        "startDate": "2020-01",
        "isCurrent": true,
        "description": "Lead frontend development team"
      }
    ],
    "skills": [
      { "name": "React", "category": "technical" },
      { "name": "TypeScript", "category": "technical" }
    ]
  },
  "question_config": {
    "excluded_question_ids": [
      "770g0622-g41d-63f6-c938-668877662222"
    ],
    "custom_questions": [
      {
        "question_text": "Why do you want to work at our company?",
        "question_type": "behavioral",
        "time_limit_seconds": 120,
        "order_index": 10
      }
    ],
    "question_order": [
      "880h1733-h52e-74g7-d049-779988773333",
      "custom_0",
      "990i2844-i63f-85h8-e150-880099884444"
    ]
  },
  "expires_in_days": 7
}

{
  "id": "660f9511-f30c-52e5-b827-557766551111",
  "interview_url": "https://interview.round0.io/interview/abc123def456...",
  "token": "abc123def456...",
  "status": "invited",
  "candidate_name": "Jane Smith",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Senior Frontend Developer"
  },
  "estimated_credits": 2,
  "estimated_duration_seconds": 1260,
  "expires_at": "2024-01-22T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}

curl -X POST https://rz-app-omega.vercel.app/api/v1/invitations \
  -H "Authorization: Bearer rz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "candidate_name": "Jane Smith"
  }'

curl -X POST https://rz-app-omega.vercel.app/api/v1/invitations \
  -H "Authorization: Bearer rz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "candidate_name": "Jane Smith",
    "question_config": {
      "custom_questions": [
        {
          "question_text": "What interests you most about this role?",
          "question_type": "behavioral",
          "time_limit_seconds": 120
        }
      ]
    }
  }'

curl -X POST https://rz-app-omega.vercel.app/api/v1/invitations \
  -H "Authorization: Bearer rz_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 880h1733-h52e-74g7-d049-779988773333" \
  -d '{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "candidate_name": "Jane Smith"
  }'

async function createInterview(jobId, candidateName) {
  const response = await fetch('https://rz-app-omega.vercel.app/api/v1/invitations', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ROUNDZERO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      job_id: jobId,
      candidate_name: candidateName
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const interview = await response.json();
  return interview;
}

{
  "error": {
    "type": "validation_error",
    "message": "Validation failed",
    "details": {
      "job_id": "Invalid job ID",
      "candidate.name": "Name is required"
    }
  }
}

{
  "error": {
    "type": "insufficient_credits",
    "message": "Insufficient available credits",
    "details": {
      "required_credits": 2,
      "available_credits": 0,
      "total_balance": 5,
      "reserved_credits": 5
    }
  }
}

{
  "error": {
    "type": "resource_not_found",
    "message": "Job not found"
  }
}

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 30 seconds."
  }
}

// Create interview with candidate name
const interview = await createInvitation({
  job_id: "job-123",
  candidate_name: "John Doe"
});
// Interview created with candidate_name: "John Doe"

{
  "candidate_cv": {
    "summary": "Brief professional summary",
    "workExperiences": [
      {
        "company": "Company Name",
        "title": "Job Title",
        "startDate": "2020-01",
        "endDate": "2024-01",
        "isCurrent": false,
        "description": "Role description and achievements"
      }
    ],
    "education": [
      {
        "institution": "University Name",
        "degree": "Bachelor",
        "field": "Computer Science",
        "endDate": "2019"
      }
    ],
    "skills": [
      { "name": "JavaScript", "category": "technical", "proficiency": "expert" },
      { "name": "Leadership", "category": "soft" }
    ],
    "certifications": [
      {
        "name": "AWS Solutions Architect",
        "issuer": "Amazon Web Services",
        "issueDate": "2023-06"
      }
    ],
    "linkedinUrl": "https://linkedin.com/in/candidate",
    "portfolioUrl": "https://candidate.dev"
  }
}

{
  "question_config": {
    "excluded_question_ids": [
      "770g0622-g41d-63f6-c938-668877662222",
      "880h1733-h52e-74g7-d049-779988773333"
    ]
  }
}

{
  "question_config": {
    "custom_questions": [
      {
        "question_text": "Describe your experience with our specific tech stack.",
        "question_type": "technical",
        "time_limit_seconds": 240
      },
      {
        "question_text": "Why do you want to work at our company?",
        "question_type": "behavioral",
        "time_limit_seconds": 120
      }
    ]
  }
}

{
  "question_config": {
    "question_order": [
      "job-question-uuid-1",
      "custom_0",
      "job-question-uuid-2",
      "custom_1"
    ]
  }
}

{
  "question_config": {
    "excluded_question_ids": ["q1-uuid", "q2-uuid"],
    "custom_questions": [
      {
        "question_text": "Custom question here",
        "question_type": "behavioral",
        "time_limit_seconds": 180,
        "order_index": 10
      }
    ],
    "question_order": ["q3-uuid", "custom_0", "q4-uuid"]
  }
}

{
  "expires_in_days": 7
}

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "candidate_name": "Jane Smith",
  "voice_id": "TxGEqnHWrfWFTfGW9XjX"
}

curl -X POST https://rz-app-omega.vercel.app/api/v1/invitations \
  -H "Authorization: Bearer rz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "candidate_name": "Jane Smith",
    "voice_id": "TxGEqnHWrfWFTfGW9XjX"
  }'

// When candidate moves to "Screening" stage in your ATS
async function onCandidateScreening(atsCandidate) {
    // Get mapped ROUND0 job
    const mapping = await db.jobMappings.findOne({
        ats_job_id: atsCandidate.job_id
    });

    // Create interview
    const interview = await fetch('https://rz-app-omega.vercel.app/api/v1/invitations', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
            'Idempotency-Key': `ats-${atsCandidate.id}` // Prevent duplicates
        },
        body: JSON.stringify({
            job_id: mapping.round0_job_id,
            candidate_name: atsCandidate.name,
            expires_in_days: 7
        })
    }).then(r => r.json());

    // Update ATS with interview link
    await ats.updateCandidate(atsCandidate.id, {
        screening_url: interview.interview_url
    });

    // Send email via your system
    await sendEmail({
        to: atsCandidate.email,
        template: 'screening_invitation',
        data: {
            candidate_name: atsCandidate.name,
            job_title: mapping.job_title,
            interview_url: interview.interview_url,
            expires_at: interview.expires_at
        }
    });
}

async function createBulkInterviews(jobId, candidates) {
    const results = [];

    // Process in batches to respect rate limits
    const batchSize = 10;
    for (let i = 0; i < candidates.length; i += batchSize) {
        const batch = candidates.slice(i, i + batchSize);

        const promises = batch.map(candidate =>
            fetch('https://rz-app-omega.vercel.app/api/v1/invitations', {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${apiKey}`,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    job_id: jobId,
                    candidate_name: candidate.name
                })
            }).then(r => r.json())
        );

        const batchResults = await Promise.all(promises);
        results.push(...batchResults);

        // Small delay between batches
        if (i + batchSize < candidates.length) {
            await new Promise(resolve => setTimeout(resolve, 1000));
        }
    }

    return results;
}

const idempotencyKey = `${sourceSystem}-${candidateId}-${jobId}`;

const interview = await createInterview({
    headers: { 'Idempotency-Key': idempotencyKey },
    // ... rest of request
});

async function createInterviewSafely(jobId, candidate) {
    try {
        const response = await fetch('/api/v1/invitations', {
            method: 'POST',
            headers: { /* ... */ },
            body: JSON.stringify({ job_id: jobId, candidate })
        });

        if (!response.ok) {
            const error = await response.json();

            if (error.error.type === 'insufficient_credits') {
                await notifyAdmin('Need to purchase more credits');
                throw new Error('Insufficient credits');
            }

            if (error.error.type === 'rate_limit_exceeded') {
                // Retry with exponential backoff
                await sleep(5000);
                return createInterviewSafely(jobId, candidate);
            }

            throw new Error(error.error.message);
        }

        return await response.json();
    } catch (error) {
        console.error('Failed to create interview:', error);
        throw error;
    }
}

// Check credit balance first
const balance = await fetch('/api/v1/credits/balance', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());

const requiredCredits = candidates.length * 2; // Assuming 2 credits per interview

if (balance.available_credits < requiredCredits) {
    throw new Error(`Need ${requiredCredits} credits, only ${balance.available_credits} available`);
}

// Proceed with bulk creation