> ## 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.
# Create Job from URL
> Scrapes the provided job posting URL and extracts structured data. By default, creates a job entity from the extracted data. Set createJob to false to only extract data without persisting a job.
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
```json theme={null}
{
"jobUrl": "https://example.com/careers/senior-developer"
}
```
### Extraction Only (without creating a job)
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"statusCode": 400,
"message": "Could not extract a valid job title from the URL. A job title of at least 5 characters is required."
}
```
```json theme={null}
{
"statusCode": 400,
"message": "Please provide a valid URL"
}
```
## Related Resources
Create a job manually with full control over all fields
Comprehensive guide to job management
View all your job postings
Understand API rate limits
## OpenAPI
````yaml POST /jobs/url
openapi: 3.0.0
info:
title: InstaView API
description: |-
InstaView API Documentation
## Authentication
All endpoints require API key authentication using Bearer token:
```
Authorization: Bearer sk_your_api_key_here
```
## API Key Management
The API Key module provides comprehensive key management for:
- **Direct Client Keys**: Company-scoped keys for your applications
- **ATS Partner Keys**: Resource-scoped keys for ATS integrations
### Key Features
- HMAC-SHA256 hashing for API key storage
- Configurable rate limiting
- Comprehensive audit logging
- Company-level isolation
- Resource scoping for ATS partners
version: 1.0.0
contact: {}
servers:
- url: https://api.instaview.sk
description: Production API Gateway
security: []
tags: []
paths:
/jobs/url:
post:
tags:
- Jobs
summary: Create job from URL
description: >-
Scrapes the provided job posting URL and extracts structured data. By
default, creates a job entity from the extracted data. Set createJob to
false to only extract data without persisting a job.
operationId: PublicJobsController_createJobFromUrl_v1
parameters:
- name: companyId
required: false
in: query
description: >-
Required for ATS API keys to specify which company to access.
Ignored for standard company API keys.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateJobFromUrlDto'
responses:
'200':
description: >-
Extracted data returned (parse-only, createJob=false). Preview
fields `id`, `createdAt`, and `updatedAt` will be empty strings.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateJobFromUrlResponseDto'
'201':
description: Job created from extracted URL data
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateJobFromUrlResponseDto'
security:
- bearer: []
components:
schemas:
PublicCreateJobFromUrlDto:
type: object
properties:
jobUrl:
type: string
description: URL of the job posting to extract data from and create a job
example: https://example.com/careers/senior-developer
maxLength: 2048
format: uri
createJob:
type: boolean
nullable: true
description: >-
Whether to create a job entity from the extracted data. When false,
only extracts and returns the data without persisting a job.
example: true
default: true
required:
- jobUrl
PublicCreateJobFromUrlResponseDto:
type: object
properties:
data:
description: >-
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.
allOf:
- $ref: '#/components/schemas/PublicJobDto'
sourceUrl:
type: string
description: Source URL that was parsed
example: https://example.com/careers/senior-developer
required:
- data
- sourceUrl
PublicJobDto:
type: object
properties:
id:
type: string
description: Job ID
example: 123e4567-e89b-12d3-a456-426614174000
companyId:
type: string
description: Company ID
example: 987e6543-e21b-12d3-a456-426614174000
title:
type: string
description: Job title
example: Senior TypeScript Developer
description:
type: string
description: Job description
example: We are looking for an experienced TypeScript developer...
nullable: true
status:
type: string
description: Job status
enum:
- UNDEFINED
- OPEN
- CLOSED
example: OPEN
jobUrl:
type: string
description: Job URL
example: https://company.com/careers/senior-typescript-dev
benefits:
type: string
description: Benefits
example: Health insurance, remote work, flexible hours
requiredSkills:
description: Required skills
example:
- TypeScript
- React
- Node.js
type: array
items:
type: string
niceToHaveSkills:
description: Nice-to-have skills
example:
- Docker
- AWS
type: array
items:
type: string
languageRequirements:
description: Language requirements with proficiency levels
example:
- language: EN
proficiency: B2
- language: SK
proficiency: C1
type: array
items:
$ref: '#/components/schemas/PublicLanguageRequirementDto'
education:
description: Education requirements
example:
- BACHELORS
type: array
items:
type: string
experience:
type: string
description: Experience level
example: SENIOR
contractType:
type: string
description: Contract type
example: FULL_TIME
location:
description: Location information
allOf:
- $ref: '#/components/schemas/PublicJobLocationDto'
salary:
description: Salary range
example:
min: 50000
max: 80000
currency: USD
period: YEARLY
allOf:
- $ref: '#/components/schemas/PublicSalaryRangeDto'
metadata:
type: object
description: Custom metadata
example:
externalJobId: JOB-12345
department: Engineering
createdAt:
type: string
description: Created timestamp
example: '2024-11-16T10:30:00Z'
updatedAt:
type: string
description: Updated timestamp
example: '2024-11-16T10:30:00Z'
required:
- id
- companyId
- title
- status
- createdAt
- updatedAt
PublicLanguageRequirementDto:
type: object
properties:
language:
type: string
description: Language
enum:
- UNDEFINED
- EN
- JA
- ZH
- DE
- HI
- FR
- KO
- PT
- IT
- ES
- ID
- NL
- TR
- FIL
- PL
- SV
- BG
- RO
- AR
- CS
- EL
- FI
- HR
- MS
- SK
- DA
- TA
- UK
- RU
- HU
- 'NO'
- VI
example: EN
proficiency:
type: string
description: Proficiency level (CEFR)
enum:
- UNDEFINED
- A1
- A2
- B1
- B2
- C1
- C2
example: B2
required:
- language
- proficiency
PublicJobLocationDto:
type: object
properties:
workMode:
type: string
description: Work mode
enum:
- UNDEFINED
- ONSITE
- REMOTE
- HYBRID
example: REMOTE
street:
type: string
description: Street address
example: Hlavná 123
minLength: 2
maxLength: 200
city:
type: string
description: City
example: Bratislava
minLength: 2
maxLength: 100
postalCode:
type: string
description: Postal code
example: '81101'
minLength: 2
maxLength: 20
countryCode:
type: string
description: Country code (ISO 3166-1 alpha-2)
enum:
- XX
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BA
- BW
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- US
- UM
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
example: SK
PublicSalaryRangeDto:
type: object
properties:
min:
type: number
description: Minimum salary (must be greater than or equal to 0)
example: 50000
minimum: 0
max:
type: number
description: Maximum salary (must be greater than or equal to 0)
example: 80000
minimum: 0
currency:
type: string
description: Currency (ISO 4217 alpha-3)
pattern: ^[A-Z]{3}$
example: USD
period:
type: string
description: Salary period
enum:
- UNDEFINED
- HOURLY
- DAILY
- MONTHLY
- YEARLY
example: YEARLY
securitySchemes:
bearer:
type: http
scheme: bearer
description: API key for authentication using Bearer scheme
````