Skip to main content

​
Get Your API Key

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

Access the Dashboard

Log in to your InstaView dashboard
2

Navigate to API Settings

Go to Settings → API Keys
3

Create a New Key

Click Create API Key and select the scopes you need
4

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

​
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:
1

Create a Job

Use the example above to create a job posting
2

Create a Candidate

Add a candidate and associate them with the job
3

Create an Agent

Configure an AI interview agent
4

Schedule an Interview

Schedule an AI-powered interview for the candidate
5

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);

​
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!