Skip to main content
POST
/
jobs
/
url
Create job from URL
curl --request POST \
  --url https://api.instaview.sk/jobs/url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobUrl": "https://example.com/careers/senior-developer",
  "createJob": true
}
'
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "companyId": "987e6543-e21b-12d3-a456-426614174000",
    "title": "Senior TypeScript Developer",
    "status": "OPEN",
    "createdAt": "2024-11-16T10:30:00Z",
    "updatedAt": "2024-11-16T10:30:00Z",
    "description": "We are looking for an experienced TypeScript developer...",
    "jobUrl": "https://company.com/careers/senior-typescript-dev",
    "benefits": "Health insurance, remote work, flexible hours",
    "requiredSkills": [
      "TypeScript",
      "React",
      "Node.js"
    ],
    "niceToHaveSkills": [
      "Docker",
      "AWS"
    ],
    "languageRequirements": [
      {
        "language": "EN",
        "proficiency": "B2"
      },
      {
        "language": "SK",
        "proficiency": "C1"
      }
    ],
    "education": [
      "BACHELORS"
    ],
    "experience": "SENIOR",
    "contractType": "FULL_TIME",
    "location": {
      "workMode": "REMOTE",
      "street": "Hlavná 123",
      "city": "Bratislava",
      "postalCode": "81101",
      "countryCode": "SK"
    },
    "salary": {
      "min": 50000,
      "max": 80000,
      "currency": "USD",
      "period": "YEARLY"
    },
    "metadata": {
      "externalJobId": "JOB-12345",
      "department": "Engineering"
    }
  },
  "sourceUrl": "https://example.com/careers/senior-developer"
}
Extracts structured data from a job posting URL and optionally creates a job entity. The endpoint extracts job details (title, description, skills, salary, location, etc.) and by default creates a job in a single operation. Set createJob to false to only extract data without persisting.

​
Overview

This endpoint is ideal for quickly importing job postings from external sources without manually entering all the fields. You can also use it in extraction-only mode to preview the extracted data before deciding to create a job.

​
Use Cases

  • Quick Job Import: Import job postings from job boards or career pages with a single URL
  • Job Aggregation: Aggregate jobs from multiple sources programmatically
  • Data Preview: Extract and review job data before creating a job by setting createJob to false

​
How It Works

  1. Scraping: The provided URL is fetched and the HTML content is cleaned
  2. Extraction: Structured job data is extracted (title, description, skills, salary, location, etc.)
  3. Job Creation: A job entity is created with the extracted data (skipped when createJob is false)

​
Request

{
  "jobUrl": "https://example.com/careers/senior-developer"
}

​
Extraction Only (without creating a job)

{
  "jobUrl": "https://example.com/careers/senior-developer",
  "createJob": false
}
When createJob is false, the endpoint returns 200 OK (instead of 201 Created) and the response data field contains a preview of the job with all extracted fields populated — the same structure as a created job, but id, createdAt, and updatedAt will be empty strings since no entity was persisted. This lets you inspect the extraction results before deciding to create.

​
Rate Limiting

This endpoint has a stricter rate limit of 5 requests per minute.

​
Error Handling

If the URL cannot be scraped or no job data can be extracted:
{
  "statusCode": 400,
  "message": "Failed to extract job data from the provided URL"
}
If a valid job title (min 5 characters) cannot be determined from the URL:
{
  "statusCode": 400,
  "message": "Could not extract a valid job title from the URL. A job title of at least 5 characters is required."
}

{
  "statusCode": 400,
  "message": "Please provide a valid URL"
}

Create Job

Create a job manually with full control over all fields

Jobs Resource Guide

Comprehensive guide to job management

List Jobs

View all your job postings

Rate Limiting

Understand API rate limits

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
​
jobUrl
string<uri>
required

URL of the job posting to extract data from and create a job

Maximum string length: 2048
Example:

"https://example.com/careers/senior-developer"

​
createJob
boolean | null
default:true

Whether to create a job entity from the extracted data. When false, only extracts and returns the data without persisting a job.

Example:

true

Response

Extracted data returned (parse-only, createJob=false). Preview fields id, createdAt, and updatedAt will be empty strings.

​
data
object
required

Job data. When createJob is true (default), this is the persisted job entity. When createJob is false, this is a preview with the same shape but id, createdAt, and updatedAt are empty strings.

​
sourceUrl
string
required

Source URL that was parsed

Example:

"https://example.com/careers/senior-developer"