> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first API call to InstaView in under 5 minutes

## Get Your API Key

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

<Steps>
  <Step title="Access the Dashboard">
    Log in to your [InstaView dashboard](https://app.instaview.sk)
  </Step>

  <Step title="Navigate to API Settings">
    Go to **Settings** → **API Keys**
  </Step>

  <Step title="Create a New Key">
    Click **Create API Key** and select the scopes you need
  </Step>

  <Step title="Save Your Key">
    Copy and securely store your API key - you won't be able to see it again!
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## Make Your First Request

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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);
  ?>
  ```
</CodeGroup>

### Expected Response

```json theme={null}
{
  "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:

<Steps>
  <Step title="Create a Job">
    Use the example above to create a job posting
  </Step>

  <Step title="Create a Candidate">
    Add a candidate and associate them with the job
  </Step>

  <Step title="Create an Agent">Configure an AI interview agent</Step>

  <Step title="Schedule an Interview">
    Schedule an AI-powered interview for the candidate
  </Step>

  <Step title="Retrieve Results">
    Fetch the interview transcript and analysis
  </Step>
</Steps>

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## Understanding the Response Format

All InstaView API responses follow a consistent structure:

```json theme={null}
{
  "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:

```json theme={null}
{
  "message": "Error description",
  "error": "Error type (e.g., Unauthorized, Forbidden)",
  "statusCode": 401
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API keys, scopes, and security best practices
  </Card>

  <Card title="Core Resources" icon="database" href="/guides/resources/jobs">
    Explore jobs, candidates, interviews, and more
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle errors gracefully in your integration
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Browse complete API documentation
  </Card>
</CardGroup>

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