Jobs - InstaView API

Overview

The Jobs API creates and organizes job postings within your company. A job groups contacts and the conversations held about it — the backbone of a hiring workflow, and optional everywhere else.

Resource Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "987e6543-e21b-12d3-a456-426614174000",
  "title": "Senior Software Engineer",
  "description": "We are seeking an experienced software engineer...",
  "requiredSkills": ["JavaScript", "React", "Node.js", "TypeScript"],
  "niceToHaveSkills": ["GraphQL", "Docker", "AWS"],
  "languageRequirements": [
    { "language": "EN", "proficiency": "C1" },
    { "language": "ES", "proficiency": "B1" }
  ],
  "location": {
    "workMode": "HYBRID",
    "street": "123 Tech Street",
    "city": "San Francisco",
    "postalCode": "94105",
    "countryCode": "US"
  },
  "salary": {
    "min": 120000,
    "max": 180000,
    "currency": "USD",
    "period": "YEARLY"
  },
  "jobUrl": "https://company.com/careers/senior-engineer",
  "status": "OPEN",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Required Scopes

Operation	Required Scope
List jobs	`read:jobs`
Get job by ID	`read:jobs`
Create job	`write:jobs`
Create job from URL	`write:jobs`
Update job	`write:jobs`
Delete job	`delete:jobs`

Creating Jobs

Basic Job Creation

curl -X POST https://api.instaview.sk/jobs \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Software Engineer",
    "description": "We are seeking an experienced software engineer...",
    "requiredSkills": ["JavaScript", "React", "Node.js"],
    "status": "OPEN"
  }'

const job = await fetch("https://api.instaview.sk/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Senior Software Engineer",
    description: "We are seeking an experienced software engineer...",
    requiredSkills: ["JavaScript", "React", "Node.js"],
    status: "OPEN",
  }),
});

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

response = requests.post(
    'https://api.instaview.sk/jobs',
    headers={
        'Authorization': f'Bearer {os.environ["INSTAVIEW_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Senior Software Engineer',
        'description': 'We are seeking an experienced software engineer...',
        'requiredSkills': ['JavaScript', 'React', 'Node.js'],
        'status': 'OPEN'
    }
)

job = response.json()
print(f'Job created: {job["id"]}')

Create Job from URL

You can also create a job by providing a URL to an existing job posting. The API will scrape the page, extract structured data using AI, and create the job automatically. Set createJob to false to only extract data without creating a job entity:

curl -X POST https://api.instaview.sk/jobs/url \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jobUrl": "https://example.com/careers/senior-developer"
  }'

const response = await fetch("https://api.instaview.sk/jobs/url", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jobUrl: "https://example.com/careers/senior-developer",
  }),
});

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

response = requests.post(
    'https://api.instaview.sk/jobs/url',
    headers={
        'Authorization': f'Bearer {os.environ["INSTAVIEW_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'jobUrl': 'https://example.com/careers/senior-developer'
    }
)

result = response.json()
print(f'Job created: {result["data"]["id"]}')

Set createJob to false to preview extracted data without creating a job. The response returns 200 (instead of 201) and data contains a preview with all extracted fields — id and timestamps will be empty strings.

This endpoint has a stricter rate limit of 5 requests per minute due to web scraping and AI processing.

Comprehensive Job Creation

const comprehensiveJob = {
  // Required fields
  title: "Senior Software Engineer",
  description:
    "We are seeking an experienced software engineer with 5+ years of experience...",

  // Skills
  requiredSkills: ["JavaScript", "React", "Node.js", "TypeScript", "REST APIs"],
  niceToHaveSkills: ["GraphQL", "Docker", "Kubernetes", "AWS"],

  // Language requirements (ISO 639-1 language codes + CEFR proficiency levels)
  languageRequirements: [
    { language: "EN", proficiency: "C1" }, // English - Proficient
    { language: "ES", proficiency: "B1" }, // Spanish - Intermediate
  ],

  // Location
  location: {
    workMode: "HYBRID", // Options: REMOTE, HYBRID, ONSITE
    street: "123 Tech Street",
    city: "San Francisco",
    postalCode: "94105",
    countryCode: "US",
  },

  // Compensation
  salary: {
    min: 120000,
    max: 180000,
    currency: "USD",
    period: "YEARLY",
  },

  // Additional info
  jobUrl: "https://company.com/careers/senior-engineer",
  status: "OPEN",
};

const response = await createJob(comprehensiveJob);

Listing Jobs

List All Jobs

async function listJobs(page = 1, limit = 20) {
  const response = await fetch(
    `https://api.instaview.sk/jobs?page=${page}&limit=${limit}`,
    {
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  );

  const result = await response.json();
  return result.data;
}

// Usage
const { items, pagination } = await listJobs(1, 50);
console.log(`Found ${pagination.total} jobs`);

Filter by Status

async function getActiveJobs() {
  const response = await fetch(
    "https://api.instaview.sk/jobs?status=OPEN&limit=100",
    {
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  );

  return await response.json();
}

Search Jobs

async function searchJobs(query) {
  const response = await fetch(
    `https://api.instaview.sk/jobs?search=${encodeURIComponent(query)}`,
    {
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  );

  return await response.json();
}

// Search by title
const engineerJobs = await searchJobs("engineer");

Best Practice: For production integrations, always implement request timeouts.

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s timeout

try {
const response = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
signal: controller.signal,
});
} finally {
clearTimeout(timeoutId);
}

Updating Jobs

Partial Update

async function updateJob(jobId, updates) {
const response = await fetch(`https://api.instaview.sk/jobs/${jobId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(updates),
});

return await response.json();
}

// Update only specific fields
await updateJob("job-uuid", {
title: "Staff Software Engineer", // Promoted!
salary: {
min: 150000,
max: 220000,
currency: "USD",
period: "YEARLY",
},
});

Best Practice: For production integrations, always implement request timeouts.

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s timeout

try {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: controller.signal,
  });
} finally {
  clearTimeout(timeoutId);
}

Change Job Status

// Mark job as closed
await updateJob("job-uuid", { status: "CLOSED" });

// Reopen job
await updateJob("job-uuid", { status: "OPEN" });

Job Status Management

Available Statuses

OPEN
CLOSED

Job is open for applications - Can schedule conversations against it - Accepts new applications

Status Workflow

class JobWorkflow {
  async createJob(jobData) {
    return await createJob({
      ...jobData,
      status: "OPEN", // Jobs start as OPEN
    });
  }

  async closeJob(jobId) {
    return await updateJob(jobId, { status: "CLOSED" });
  }

  async reopenJob(jobId) {
    return await updateJob(jobId, { status: "OPEN" });
  }
}

Location and Work Mode

Work Modes

Mode	Description
`REMOTE`	Fully remote position
`ONSITE`	Office-based only
`HYBRID`	Mix of remote and office

Location Structure

{
  location: {
    street: '123 Tech Street',      // Optional
    city: 'San Francisco',           // Recommended
    postalCode: '94105',             // Optional
    countryCode: 'US'                // Required (ISO 3166-1 alpha-2)
  }
}

Examples

// Fully remote position
{
  location: {
    workMode: 'REMOTE',
    countryCode: 'US' // Country for legal/tax purposes
  }
}

// Hybrid with specific office
{
  location: {
    workMode: 'HYBRID',
    street: '1 Apple Park Way',
    city: 'Cupertino',
    postalCode: '95014',
    countryCode: 'US'
  }
}

// On-site position
{
  location: {
    workMode: 'ONSITE',
    city: 'New York',
    countryCode: 'US'
  }
}

Salary Information

Salary Structure

{
  salary: {
    min: 100000,           // Minimum compensation
    max: 150000,           // Maximum compensation
    currency: 'USD',       // ISO 4217 currency code
    period: 'YEARLY'       // Options: 'YEARLY', 'MONTHLY', 'HOURLY'
  }
}

Examples

// Annual salary range
{
  salary: {
    min: 120000,
    max: 180000,
    currency: 'USD',
    period: 'YEARLY'
  }
}

// Hourly rate
{
  salary: {
    min: 75,
    max: 125,
    currency: 'USD',
    period: 'HOURLY'
  }
}

// Monthly salary (common in some regions)
{
  salary: {
    min: 8000,
    max: 12000,
    currency: 'EUR',
    period: 'MONTHLY'
  }
}

// Omit salary (not disclosed)
{
  // salary field can be omitted entirely
}

Skills Management

Best Practices

Be Specific

// ✅ Good: Specific technologies
requiredSkills: ['React 18+', 'Node.js', 'PostgreSQL', 'TypeScript']

// ❌ Too vague
requiredSkills: ['Frontend', 'Backend', 'Database']

Separate Required vs Nice-to-Have

{
  requiredSkills: [
    'JavaScript',
    'React',
    'REST APIs'
  ],
  niceToHaveSkills: [
    'TypeScript',
    'GraphQL',
    'Docker'
  ]
}

Use Consistent Naming

// ✅ Consistent
requiredSkills: ['JavaScript', 'TypeScript', 'Node.js']

// ❌ Inconsistent casing/spelling
requiredSkills: ['javascript', 'Typescript', 'NodeJS']

Deleting Jobs

Soft Delete

Jobs are soft-deleted by default:

async function deleteJob(jobId) {
  const response = await fetch(`https://api.instaview.sk/jobs/${jobId}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return await response.json();
}

This is a hard delete, and it cascades. The job goes, and so does every contact whose job it is — and with them their conversations, transcripts, recordings and analyses. A contact assigned to this job and others goes too: the cascade follows the job, not “contacts left with no job”. None of it is readable through the API afterwards.To stop using a job without losing anything, set its status to CLOSED instead. See Delete Job.

Before Deleting

Consider the impact:

async function safeDeleteJob(jobId) {
  // Check for contacts attached to the job
  const contacts = await listContacts({ jobId });

  if (contacts.total > 0) {
    console.warn(`Job has ${contacts.total} contacts — deleting it deletes them`);
    const confirm = await askUser("Delete anyway?");
    if (!confirm) return;
  }

  // Proceed with deletion
  return await deleteJob(jobId);
}

Common Patterns

Bulk Job Creation

async function bulkCreateJobs(jobsData) {
  const results = [];
  const errors = [];

  for (const jobData of jobsData) {
    try {
      const job = await createJob(jobData);
      results.push(job);

      // Rate limiting: wait between requests
      await sleep(200);
    } catch (error) {
      errors.push({
        jobData,
        error: error.message,
      });
    }
  }

  return { results, errors };
}

Job Synchronization

async function syncJobsFromATS(atsJobs) {
  const existingJobs = await listAllJobs();
  const existingJobsMap = new Map(existingJobs.map((j) => [j.externalId, j]));

  for (const atsJob of atsJobs) {
    const existing = existingJobsMap.get(atsJob.id);

    if (!existing) {
      // Create new job
      await createJob(transformAtsJob(atsJob));
    } else if (hasChanges(existing, atsJob)) {
      // Update existing job
      await updateJob(existing.id, transformAtsJob(atsJob));
    }
  }
}

Job Analytics

async function getJobStats(jobId) {
  const [contacts, conversations] = await Promise.all([
    listContacts({ jobId }),
    listConversations({ jobId }),
  ]);

  return {
    totalContacts: contacts.total,
    activeContacts: contacts.data.filter((c) => c.status === "IN_PROCESS")
      .length,
    totalConversations: conversations.total,
    completedConversations: conversations.data.filter(
      (i) => i.status === "completed",
    ).length,
  };
}

Validation Rules

string

required

Job title (1-200 characters)

string

Detailed job description (max 10,000 characters)

array

Array of required skills (max 50 items, each max 100 chars)

enum

One of: REMOTE, ONSITE, HYBRID

string

required

ISO 3166-1 alpha-2 country code (e.g., “US”, “GB”, “DE”)

string

ISO 4217 currency code (e.g., “USD”, “EUR”, “GBP”)

enum

One of: OPEN, CLOSED, UNDEFINED Note: In practice, use OPEN (accepting applications) or CLOSED (no longer hiring)

Error Scenarios

Errors answer with the flat body described in Error Handling: a statusCode, a message, a traceId, and — on a rejected request body — an errors array with one entry per rejected constraint.

Invalid Work Mode

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["Invalid work mode"],
  "traceId": "4b1f0c9d2e6a47f8b3c5d7e9a1b2c3d4"
}

workMode is one of ONSITE, REMOTE, HYBRID or UNDEFINED.

Job Not Found

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

Every by-id route (GET, PATCH, DELETE) answers this for an id that exists nowhere and for an id that belongs to another company — same status, same body. The two are deliberately indistinguishable, so a 404 never confirms that an id exists somewhere else. Do not branch on it to detect a permission problem; treat it as “this job is not available to this key”.

Best Practices

Use Draft Status

Create jobs as drafts while preparing content

Consistent Skills

Maintain a standardized skill taxonomy

Include Salary

Transparency improves who applies

Update Regularly

Keep job descriptions current and accurate

Next Steps

Contacts

Add contacts to your jobs

Conversations

Call the contacts on a job

API Reference

View complete Jobs API reference

Best Practices

Production integration patterns

​Overview

​Resource Structure

​Required Scopes

​Creating Jobs

​Basic Job Creation

​Create Job from URL

​Comprehensive Job Creation

​Listing Jobs

​List All Jobs

​Filter by Status

​Search Jobs

​Updating Jobs

​Partial Update

​Change Job Status

​Job Status Management

​Available Statuses

​Status Workflow

​Location and Work Mode

​Work Modes

​Location Structure

​Examples

​Salary Information

​Salary Structure

​Examples

​Skills Management

​Best Practices

​Deleting Jobs

​Soft Delete

​Before Deleting

​Common Patterns

​Bulk Job Creation

​Job Synchronization

​Job Analytics

​Validation Rules

​Error Scenarios

​Best Practices

Use Draft Status

Consistent Skills

Include Salary

Update Regularly

​Next Steps

Contacts

Conversations

API Reference

Best Practices

Overview

Resource Structure

Required Scopes

Creating Jobs

Basic Job Creation

Create Job from URL

Comprehensive Job Creation

Listing Jobs

List All Jobs

Filter by Status

Search Jobs

Updating Jobs

Partial Update

Change Job Status

Job Status Management

Available Statuses

Status Workflow

Location and Work Mode

Work Modes

Location Structure

Examples

Salary Information

Salary Structure

Examples

Skills Management

Best Practices

Deleting Jobs

Soft Delete

Before Deleting

Common Patterns

Bulk Job Creation

Job Synchronization

Job Analytics

Validation Rules

Error Scenarios

Best Practices

Next Steps