Quickstart

Get Your API Key

Before you can make API calls, you’ll need an API key from your InstaView dashboard.

Access the Dashboard

Navigate to API Settings

Go to Settings → API Keys

Create a New Key

Click Create API Key and select the scopes you need

Save Your Key

Copy and securely store your API key - you won’t be able to see it again!

Keep your API key secure! Never commit it to version control or expose it in client-side code. Use environment variables or secure secret management.

Make Your First Request

Let’s create your first job posting using the InstaView API.

curl -X POST https://api.instaview.sk/jobs \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Software Engineer",
    "description": "We are looking for an experienced software engineer...",
    "requiredSkills": ["JavaScript", "React", "Node.js"],
    "location": {
      "workMode": "HYBRID",
      "city": "San Francisco",
      "countryCode": "US"
    },
    "status": "OPEN"
  }'

const axios = require("axios");

const apiKey = process.env.INSTAVIEW_API_KEY;
const baseURL = "https://api.instaview.sk";

async function createJob() {
  try {
    const response = await axios.post(
      `${baseURL}/jobs`,
      {
        title: "Senior Software Engineer",
        description: "We are looking for an experienced software engineer...",
        requiredSkills: ["JavaScript", "React", "Node.js"],
        location: {
          workMode: "HYBRID",
          city: "San Francisco",
          countryCode: "US",
        },
        status: "OPEN",
      },
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
      },
    );

    console.log("Job created:", response.data.data);
    return response.data.data;
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
  }
}

createJob();

import os
import requests

api_key = os.environ.get('INSTAVIEW_API_KEY')
base_url = 'https://api.instaview.sk'

def create_job():
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }

    job_data = {
        'title': 'Senior Software Engineer',
        'description': 'We are looking for an experienced software engineer...',
        'requiredSkills': ['JavaScript', 'React', 'Node.js'],
        'location': {
            'workMode': 'HYBRID',
            'city': 'San Francisco',
            'countryCode': 'US'
        },
        'status': 'OPEN'
    }

    response = requests.post(
        f'{base_url}/jobs',
        headers=headers,
        json=job_data
    )

    if response.status_code == 200:
        job = response.json()['data']
        print(f"Job created: {job['id']}")
        return job
    else:
        print(f"Error: {response.status_code}")
        print(response.json())

create_job()

<?php

$apiKey = getenv('INSTAVIEW_API_KEY');
$baseUrl = 'https://api.instaview.sk';

function createJob($apiKey, $baseUrl) {
    $jobData = [
        'title' => 'Senior Software Engineer',
        'description' => 'We are looking for an experienced software engineer...',
        'requiredSkills' => ['JavaScript', 'React', 'Node.js'],
        'location' => [
            'workMode' => 'HYBRID',
            'city' => 'San Francisco',
            'countryCode' => 'US'
        ],
        'status' => 'OPEN'
    ];

    $ch = curl_init($baseUrl . '/jobs');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($jobData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        $result = json_decode($response, true);
        echo "Job created: " . $result['data']['id'] . "\n";
        return $result['data'];
    } else {
        echo "Error: $httpCode\n";
        echo $response . "\n";
    }
}

createJob($apiKey, $baseUrl);
?>

Expected Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "companyId": "987e6543-e21b-12d3-a456-426614174000",
    "title": "Senior Software Engineer",
    "description": "We are looking for an experienced software engineer...",
    "requiredSkills": ["JavaScript", "React", "Node.js"],
    "niceToHaveSkills": [],
    "location": {
      "workMode": "HYBRID",
      "city": "San Francisco",
      "countryCode": "US"
    },
    "status": "OPEN",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "error": null,
  "timestamp": "2024-01-15T10:30:00Z"
}

Complete Workflow Example

Here’s a complete workflow showing how to create a job, add a candidate, and schedule an AI interview:

Create a Job

Use the example above to create a job posting

Create a Candidate

Add a candidate and associate them with the job

Create an Agent

Configure an AI interview agent

Schedule an Interview

Schedule an AI-powered interview for the candidate

Retrieve Results

Fetch the interview transcript and analysis

const axios = require("axios");

const client = axios.create({
  baseURL: "https://api.instaview.sk",
  headers: {
    Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
});

async function completeWorkflow() {
  // 1. Create a job
  const job = await client.post("/jobs", {
    title: "Frontend Developer",
    description: "React and TypeScript expert needed",
    requiredSkills: ["React", "TypeScript"],
    status: "OPEN",
  });

  const jobId = job.data.data.id;
  console.log("Job created:", jobId);

  // 2. Create a candidate
  const candidate = await client.post("/candidates", {
    jobId: jobId,
    firstName: "Jane",
    lastName: "Doe",
    email: "jane.doe@example.com",
    phoneNumber: "+1234567890",
    gdprExpiryDate: new Date(
      Date.now() + 365 * 24 * 60 * 60 * 1000,
    ).toISOString(),
  });

  const candidateId = candidate.data.data.id;
  console.log("Candidate created:", candidateId);

  // 3. Create an interview agent
  const agent = await client.post("/agents", {
    name: "Technical Screening Agent",
    voiceId: "ALEX",
    type: "ONLINE",
    focus: "SCREENING",
    questions: [
      "Tell me about your React experience",
      "Explain the difference between props and state",
      "How do you handle async operations in React?",
    ],
    duration: 30,
  });

  const agentId = agent.data.data.id;
  console.log("Agent created:", agentId);

  // 4. Schedule an interview
  const interview = await client.post("/interviews", {
    candidateId: candidateId,
    agentId: agentId,
    scheduleTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // Tomorrow
  });

  const interviewId = interview.data.data.id;
  console.log("Interview scheduled:", interviewId);

  // 5. Later: Retrieve interview results
  // (after the interview has been completed)
  const results = await client.get(`/interviews/${interviewId}`);
  console.log("Interview status:", results.data.data.status);

  if (results.data.data.analysis) {
    console.log("Candidate score:", results.data.data.analysis.overallScore);
    console.log("Transcript:", results.data.data.transcript);
  }
}

completeWorkflow().catch(console.error);

import os
import requests
from datetime import datetime, timedelta

base_url = 'https://api.instaview.sk'
headers = {
    'Authorization': f'Bearer {os.environ["INSTAVIEW_API_KEY"]}',
    'Content-Type': 'application/json'
}

def complete_workflow():
    # 1. Create a job
    job_response = requests.post(
        f'{base_url}/jobs',
        headers=headers,
        json={
            'title': 'Frontend Developer',
            'description': 'React and TypeScript expert needed',
            'requiredSkills': ['React', 'TypeScript'],
            'status': 'OPEN'
        }
    )
    job_id = job_response.json()['data']['id']
    print(f'Job created: {job_id}')

    # 2. Create a candidate
    candidate_response = requests.post(
        f'{base_url}/candidates',
        headers=headers,
        json={
            'jobId': job_id,
            'firstName': 'Jane',
            'lastName': 'Doe',
            'email': 'jane.doe@example.com',
            'phoneNumber': '+1234567890',
            'gdprExpiryDate': (datetime.now() + timedelta(days=365)).isoformat()
        }
    )
    candidate_id = candidate_response.json()['data']['id']
    print(f'Candidate created: {candidate_id}')

    # 3. Create an interview agent
    agent_response = requests.post(
        f'{base_url}/agents',
        headers=headers,
        json={
            'name': 'Technical Screening Agent',
            'voiceId': 'ALEX',
            'type': 'ONLINE',
            'focus': 'SCREENING',
            'questions': [
                'Tell me about your React experience',
                'Explain the difference between props and state',
                'How do you handle async operations in React?'
            ],
            'duration': 30
        }
    )
    agent_id = agent_response.json()['data']['id']
    print(f'Agent created: {agent_id}')

    # 4. Schedule an interview
    tomorrow = (datetime.now() + timedelta(days=1)).isoformat()
    interview_response = requests.post(
        f'{base_url}/interviews',
        headers=headers,
        json={
            'candidateId': candidate_id,
            'agentId': agent_id,
            'scheduleTime': tomorrow
        }
    )
    interview_id = interview_response.json()['data']['id']
    print(f'Interview scheduled: {interview_id}')

    # 5. Later: Retrieve interview results
    results = requests.get(
        f'{base_url}/interviews/{interview_id}',
        headers=headers
    )
    interview_data = results.json()['data']
    print(f'Interview status: {interview_data["status"]}')

    if interview_data.get('analysis'):
        print(f'Candidate score: {interview_data["analysis"]["overallScore"]}')

complete_workflow()

Understanding the Response Format

All InstaView API responses follow a consistent structure:

{
  "success": boolean,
  "data": object | array | null,
  "error": string | null,
  "timestamp": string (ISO 8601)
}

success: true for successful requests, false for errors
data: The requested resource or null if an error occurred
error: Error message string if success is false, otherwise null
timestamp: Server timestamp of the response

For errors, NestJS returns standard error objects:

{
  "message": "Error description",
  "error": "Error type (e.g., Unauthorized, Forbidden)",
  "statusCode": 401
}

Next Steps

Authentication

Learn about API keys, scopes, and security best practices

Core Resources

Explore jobs, candidates, interviews, and more

Error Handling

Handle errors gracefully in your integration

API Reference

Browse complete API documentation

Pro Tip: Use our interactive API playground in the API Reference section to test endpoints without writing code!

Getting Started

Core Concepts

Resources

Advanced

Get Your API Key

Make Your First Request

Expected Response

Complete Workflow Example

Understanding the Response Format

Next Steps

Authentication

Core Resources

Error Handling

API Reference

​Get Your API Key

​Make Your First Request

​Expected Response

​Complete Workflow Example

​Understanding the Response Format

​Next Steps

Authentication

Core Resources

Error Handling

API Reference

Get Your API Key

Make Your First Request

Expected Response

Complete Workflow Example

Understanding the Response Format

Next Steps