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);
    return response.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.ok:
        job = response.json()
        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 && $httpCode < 300) {
        $result = json_decode($response, true);
        echo "Job created: " . $result['id'] . "\n";
        return $result;
    } else {
        echo "Error: $httpCode\n";
        echo $response . "\n";
    }
}

createJob($apiKey, $baseUrl);
?>

Expected Response

{
  "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"
}

Complete Workflow Example

A complete workflow: create a job, add a contact, configure an agent, and have it place the call.

Create a Job

Use the example above to create a job posting

Create a Contact

Add the person to call, and associate them with the job

Create an Agent

Configure the agent that will run the call

Create a Conversation

Schedule the call

Retrieve Results

Fetch the 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.id;
  console.log("Job created:", jobId);

  // 2. Create a contact
  const contact = await client.post("/contacts", {
    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 contactId = contact.data.id;
  console.log("Contact created:", contactId);

  // 3. Create the agent that runs the call
  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.id;
  console.log("Agent created:", agentId);

  // 4. Create the conversation
  const conversation = await client.post("/conversations", {
    contactId: contactId,
    agentId: agentId,
    scheduleTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // Tomorrow
  });

  const conversationId = conversation.data.id;
  console.log("Conversation scheduled:", conversationId);

  // 5. Later: read the results
  // (once the call has completed)
  const results = await client.get(`/conversations/${conversationId}`);
  console.log("Conversation status:", results.data.status);

  if (results.data.analysis) {
    console.log("Overall rating:", results.data.analysis.general.overallRating);
  }
}

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()['id']
    print(f'Job created: {job_id}')

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

    # 3. Create the agent that runs the call
    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()['id']
    print(f'Agent created: {agent_id}')

    # 4. Create the conversation
    tomorrow = (datetime.now() + timedelta(days=1)).isoformat()
    conversation_response = requests.post(
        f'{base_url}/conversations',
        headers=headers,
        json={
            'contactId': contact_id,
            'agentId': agent_id,
            'scheduleTime': tomorrow
        }
    )
    conversation_id = conversation_response.json()['id']
    print(f'Conversation scheduled: {conversation_id}')

    # 5. Later: read the results
    results = requests.get(
        f'{base_url}/conversations/{conversation_id}',
        headers=headers
    )
    conversation = results.json()
    print(f'Conversation status: {conversation["status"]}')

    if conversation.get('analysis'):
        print(f'Overall rating: {conversation["analysis"]["general"]["overallRating"]}')

complete_workflow()

Understanding the Response Format

There is no envelope. A successful response body is the resource, as in the example above, and whether the call succeeded is carried by the HTTP status code rather than by a field in the body. A list endpoint returns a page object instead — the rows in data, the counts beside it:

{
  "data": [ { "id": "…" } ],
  "total": 25,
  "page": 1,
  "limit": 20,
  "totalPages": 2
}

An error is a flat object:

{
  "statusCode": 404,
  "message": "Job not found",
  "traceId": "4b1f0c9d2e6a47f8b3c5d7e9a1b2c3d4",
  "timestamp": "2026-08-03T10:30:00.000Z"
}

Every response also carries an x-trace-id header holding that same trace id. Quote it when you write to support.

Responses used to be wrapped in { statusCode, message, data, traceId }, which put list rows at data.data. An integration that predates the change keeps receiving the old shape until 4 September 2026, 00:00 Europe/Prague, and can tell because its responses carry a Sunset header until then. See the changelog. Anything you build today gets the shape above.

See Error Handling for the full list of status codes, and Pagination for the page object.

Next Steps

Authentication

Learn about API keys, scopes, and security best practices

Core Resources

Explore contacts, conversations, agents, jobs 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