API Reference

Jobs API

Create and manage job descriptions programmatically

Jobs API

Create and manage job descriptions programmatically.

Create Job

Create a new job description.

POST /api/v1/jobs

Request

Headers:

Authorization: Bearer rz_live_...
Content-Type: application/json

Body:

{
  "title": "Senior Frontend Developer",
  "department": "Engineering",
  "location": "Remote",
  "description": "We are looking for an experienced Frontend Developer to join our team...",
  "requirements": "5+ years of experience with React, TypeScript, and modern web technologies...",
  "interview_goals": {
    "goals": [
      { "category": "technical_competency", "priority": "high" },
      { "category": "problem_solving", "priority": "high" },
      { "category": "communication", "priority": "medium" }
    ],
    "customGoals": ["Experience with React performance optimization"],
    "additionalContext": "Candidate will be working on our customer-facing dashboard"
  }
}

Parameters:

Field	Type	Required	Description
`title`	string	Yes	Job title
`department`	string	No	Department or team name
`location`	string	No	Job location (e.g., "Remote", "San Francisco")
`description`	string	Yes	Full job description
`requirements`	string	No	Job requirements and qualifications
`status`	string	No	Job status: "active" (default), "draft", "archived"
`interview_goals`	object	No	Interview goals configuration for AI question generation

Interview Goals Object:

Field	Type	Description
`goals`	array	Array of goal objects with `category` and `priority`
`customGoals`	array	Array of custom goal strings
`additionalContext`	string	Free-form context for question generation

Goal Categories:

technical_competency - Technical knowledge, coding ability, and tool proficiency
problem_solving - Analytical thinking and approach to challenges
communication - Verbal and written communication skills
leadership - Leadership potential and management skills
culture_fit - Alignment with company values and team dynamics
domain_expertise - Industry-specific knowledge and experience
collaboration - Teamwork abilities and cross-functional experience
adaptability - Flexibility and ability to learn new things
motivation - Career goals and drive for the role

Priority Levels: high, medium, low

Response

201 Created:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Senior Frontend Developer",
  "department": "Engineering",
  "location": "Remote",
  "description": "We are looking for...",
  "requirements": "5+ years of experience...",
  "status": "active",
  "interview_goals": {
    "goals": [
      { "category": "technical_competency", "priority": "high" },
      { "category": "problem_solving", "priority": "high" }
    ],
    "customGoals": [],
    "additionalContext": null
  },
  "questions_generated": true,
  "question_count": 12,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Response fields:

id: Unique job identifier (UUID)
interview_goals: Interview goals configuration (if set)
questions_generated: Whether interview questions have been generated
question_count: Number of questions generated
created_at: ISO 8601 timestamp
updated_at: ISO 8601 timestamp

Example

curl -X POST https://rz-app-omega.vercel.app/api/v1/jobs \
  -H "Authorization: Bearer rz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Frontend Developer",
    "department": "Engineering",
    "location": "Remote",
    "description": "We are looking for an experienced Frontend Developer...",
    "requirements": "5+ years with React, TypeScript..."
  }'

const response = await fetch('https://rz-app-omega.vercel.app/api/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Senior Frontend Developer',
    department: 'Engineering',
    location: 'Remote',
    description: 'We are looking for an experienced Frontend Developer...',
    requirements: '5+ years with React, TypeScript...'
  })
});

const job = await response.json();
console.log('Job created:', job.id);

Errors

400 Bad Request - Invalid parameters:

{
  "error": {
    "type": "validation_error",
    "message": "Validation failed",
    "details": {
      "title": "Title is required",
      "description": "Description must be at least 50 characters"
    }
  }
}

401 Unauthorized - Invalid API key:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

403 Forbidden - No Connectivity Package:

{
  "error": {
    "type": "permission_error",
    "message": "Connectivity Package subscription required for API access"
  }
}

List Jobs

Retrieve a list of all jobs.

GET /api/v1/jobs

Request

Headers:

Authorization: Bearer rz_live_...

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (max: 100)
`cursor`	string	-	Pagination cursor from previous response
`status`	string	-	Filter by status: "active", "draft", "archived"

Response

200 OK:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Senior Frontend Developer",
      "department": "Engineering",
      "location": "Remote",
      "status": "active",
      "question_count": 12,
      "interview_count": 5,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "660f9511-f30c-52e5-b827-557766551111",
      "title": "Product Manager",
      "department": "Product",
      "location": "San Francisco",
      "status": "active",
      "question_count": 10,
      "interview_count": 3,
      "created_at": "2024-01-14T15:20:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjY2MGY5NTExIn0=",
    "has_more": true
  }
}

Example

# Get first page
curl https://rz-app-omega.vercel.app/api/v1/jobs?limit=20 \
  -H "Authorization: Bearer rz_live_..."

# Get next page
curl https://rz-app-omega.vercel.app/api/v1/jobs?limit=20&cursor=eyJpZCI6IjY2MGY5NTExIn0= \
  -H "Authorization: Bearer rz_live_..."

# Filter by status
curl https://rz-app-omega.vercel.app/api/v1/jobs?status=active \
  -H "Authorization: Bearer rz_live_..."

Get Job

Retrieve details for a specific job.

GET /api/v1/jobs/:id

Request

Headers:

Authorization: Bearer rz_live_...

Path Parameters:

id: Job UUID

Response

200 OK:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Senior Frontend Developer",
  "department": "Engineering",
  "location": "Remote",
  "description": "We are looking for an experienced Frontend Developer to join our team...",
  "requirements": "5+ years of experience with React, TypeScript, and modern web technologies...",
  "status": "active",
  "questions": [
    {
      "id": "770g0622-g41d-63f6-c938-668877662222",
      "question_text": "Describe your experience with React hooks and when you would use them.",
      "question_type": "technical",
      "time_limit_seconds": 180,
      "order": 0
    },
    {
      "id": "880h1733-h52e-74g7-d049-779988773333",
      "question_text": "Tell me about a time when you had to optimize a slow-performing web application.",
      "question_type": "experience",
      "time_limit_seconds": 180,
      "order": 1
    }
  ],
  "question_count": 12,
  "interview_count": 5,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Example

curl https://rz-app-omega.vercel.app/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer rz_live_..."

Errors

404 Not Found - Job doesn't exist:

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

Best Practices

Job Description Quality

For better AI-generated questions:

Be specific: Include concrete technologies, tools, and skills
Describe responsibilities: What will the person actually do day-to-day?
List requirements: Both required and nice-to-have skills
Add context: Team size, company stage, product details
Use clear language: Avoid jargon and acronyms when possible

Example of a good description:

{
  "title": "Senior Backend Engineer - Payments",
  "department": "Engineering",
  "description": "Join our payments team to build and scale our transaction processing infrastructure. You'll work on high-throughput systems processing millions of transactions daily, collaborate with product and design teams, and mentor junior engineers.",
  "requirements": "5+ years backend development with Python or Go. Experience with PostgreSQL, Redis, message queues (RabbitMQ/Kafka). Familiarity with payment processing, PCI compliance, and distributed systems. Strong API design skills."
}

Reusing Jobs

Instead of creating duplicate jobs:

Create once: Use the same job for multiple candidates
Update when needed: Edit existing jobs if requirements change
Archive, don't delete: Preserve historical data
Use status field: Mark as "draft" while refining

Automation

Workflow example:

// When job is posted in your ATS
async function onJobPosted(atsJob) {
  // Create job in ROUND0
  const job = await createROUND0Job({
    title: atsJob.title,
    department: atsJob.department,
    location: atsJob.location,
    description: atsJob.description,
    requirements: atsJob.requirements
  });

  // Store mapping in your database
  await db.jobMappings.create({
    ats_job_id: atsJob.id,
    round0_job_id: job.id
  });

  return job;
}

Next Steps

Create Interview Invitations - Create interviews for this job
Retrieve Interview Results - Get candidate responses
Webhooks - Real-time notifications

API Overview

Introduction to the ROUND0 REST API, authentication, and rate limiting.

Invitations API

Create interview invitations for candidates via API