peviitor API

Platformă de descoperire a joburilor — documentație API publică

https://api.peviitor.ro

Această pagină expune endpoint-uri publice ale API-ului peviitor.ro, o platformă de descoperire a joburilor. Suntem în proces de revizuire și extindere a API-ului, iar documentația se va îmbunătăți treptat.

Endpoint-uri disponibile în prezent

Endpoint-urile de mai jos sunt disponibile în acest moment și pot fi folosite pentru testare și explorare. API-ul este în curs de standardizare, iar pentru fiecare funcționalitate vom publica treptat endpoint-uri noi, împreună cu o documentație mai detaliată.

GET /v1/random/ Get a random job listing ▶

Returns a single random job from the Solr job index. Useful for discovery widgets, "job of the day" features, or testing integrations.

How it works

Queries Solr for the total number of indexed jobs
Picks a random offset between 0 and total count
Fetches exactly one document at that offset
Returns the job mapped to the peviitor Job Model Schema

Try it

curl

curl -X GET "https://api.peviitor.ro/v1/random/" \
  -H "Accept: application/json"

Response fields

Field	Type	Description
title	string	Exact job position title
company	string	Hiring company name (uppercase)
location	string[]	Array of cities or addresses
workmode	string	`remote`, `on-site`, or `hybrid`
url	string	Full URL to the job detail page (unique key)
salary	string	Salary interval with currency, e.g. `5000-8000 RON`
tags	string[]	Skill tags (lowercase, max 20)
cif	string	CIF/CUI of the company
date	string	ISO8601 UTC timestamp of indexing
status	string	`scraped`, `tested`, `published`, or `verified`

200 — Success

{
  "title": "Inginer IT",
  "company": "COMPANY SRL",
  "location": ["Bucure\u0219ti", "Cluj-Napoca"],
  "workmode": "remote",
  "url": "https://example.com/job/123",
  "salary": "5000-8000 RON",
  "tags": ["python", "java"],
  "cif": "12345678",
  "date": "2026-06-15T10:00:00Z",
  "status": "published"
}

404 — No Jobs Found

{
  "error": "No jobs found"
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

Requirements — Random

Item	Details
Method	`GET` only
Auth	None (public endpoint)
Params	None
Content-Type	`application/json`

Status codes

200A random job was found and returned successfully
404No jobs are currently indexed in the Solr core
503Solr core is unavailable or environment not configured

GET /v1/total/ Get total jobs and companies count ▶

Returns the total number of job listings and companies currently indexed in the Solr cores. Useful for dashboard counters, statistics widgets, or monitoring integrations.

How it works

Queries the job Solr core for the total number of indexed jobs
Queries the company Solr core for the total number of indexed companies
Returns both counts in a single response object

Try it

curl

curl -X GET "https://api.peviitor.ro/v1/total/" \
  -H "Accept: application/json"

Response fields

Field	Type	Description
total	object	Container object with count fields
total.jobs	number	Total number of job listings currently indexed
total.companies	number	Total number of companies currently indexed

200 — Success

{
  "total": {
    "jobs": 18452,
    "companies": 934
  }
}

405 — Method Not Allowed

{
  "error": "Only GET method allowed"
}

503 — Service Unavailable

Triggered when Solr is unreachable, returns an invalid response, or the environment is not configured. The details field contains the underlying error message for debugging.

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

{
  "error": "Job core unavailable",
  "details": "FETCH FAILED: http://... | Connection timed out"
}

{
  "error": "Job core unavailable",
  "details": "Invalid JSON response"
}

Requirements — Total

Item	Details
Method	`GET` only
Auth	None (public endpoint)
Params	None
Content-Type	`application/json`

Status codes

200Counts for jobs and companies returned successfully
405Request method is not GET
503Solr core is unreachable, returned invalid JSON, or environment is not configured

DELETE /v1/cleanjobs/ Delete job records for a company ▶

Permanently deletes every job document matching the given company from the job Solr core. Designed for company website owners who want to remove their listings from the peviitor platform.

How it works

Identify the company by company name, cif, or brand
Compute X-Api-Key as MD5 hash based on the provided identifiers
Send a DELETE request with confirmation body
All matching jobs are permanently removed from the index

Authentication

You must provide an X-Api-Key header computed as md5() of the identifiers you send. The key is generated from the same fields in the request body:

Body fields	X-Api-Key formula
`company` + `cif`	`md5(company + cif)` (recommended)
`company` only	`md5(company)`
`brand` only	`md5(brand)`

Request body

{
  "company": "NUME SRL",
  "cif": "12345678",
  "confirmation": "CLEAN_COMPANY_JOBS"
}

At least one of company, cif, or brand is required. The confirmation field must be exactly "CLEAN_COMPANY_JOBS".

Try it

curl

COMPANY="NUME SRL"
CIF="12345678"
KEY=$(echo -n "${COMPANY}${CIF}" | md5sum | cut -d' ' -f1)

curl -X DELETE "https://api.peviitor.ro/v1/cleanjobs/" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "'"$COMPANY"'",
    "cif": "'"$CIF"'",
    "confirmation": "CLEAN_COMPANY_JOBS"
  }'

Response fields

Field	Type	Description
message	string	Success confirmation message
jobCount	number	Number of jobs deleted
company	string	Company name (if provided)
cif	string	Company CIF (if provided)
brand	string	Company brand (if provided)

200 — Success

{
  "message": "Jobs deleted successfully",
  "jobCount": 42,
  "company": "NUME SRL",
  "cif": "12345678"
}

401 — Unauthorized

{
  "error": "Unauthorized - invalid X-Api-Key"
}

404 — No Jobs Found

{
  "error": "No jobs found",
  "message": "No jobs found matching the given criteria"
}

405 — Method Not Allowed

{
  "error": "Only DELETE method allowed"
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

Requirements — Cleanjobs

Item	Details
Method	`DELETE` only
Auth	`X-Api-Key: md5(company + cif)` (or `md5(company)` / `md5(brand)`)
Params	Body: `{"company"?: "...", "cif"?: "...", "brand"?: "...", "confirmation": "CLEAN_COMPANY_JOBS"}`
Content-Type	`application/json`

Status codes

200Jobs were deleted successfully
401Invalid or missing X-Api-Key header
404No jobs found matching the given criteria
405Only DELETE method is allowed
503Solr core is unavailable or environment not configured

GET /v1/firme/company/ Search companies by CIF or name ▶

Searches the Solr company core using edismax and returns matching company documents. You can search by exact CIF (8-digit number) or by company name (full-text search).

How it works

Provide either cif (exact match) or name (full-text search) as a query parameter
The endpoint builds an edismax query and sends it to the Solr company core
Returns matching documents with fields: id, company, brand, group, status, location, website, career, lastScraped, scraperFile

Query parameters

Param	Type	Description
cif	string	8-digit CIF/CUI (exact match). Non-digit characters are stripped.
name	string	Company name for full-text search via edismax
rows	number	Max results to return (default: 10, max: 50)
start	number	Offset for pagination (default: 0)

At least one of cif or name is required.

Try it

curl

curl -X GET "https://api.peviitor.ro/v1/firme/company/?cif=24415960" \
  -H "Accept: application/json"

curl -X GET "https://api.peviitor.ro/v1/firme/company/?name=Google&rows=5" \
  -H "Accept: application/json"

Response fields

Field	Type	Description
success	boolean	Always `true` on success
total	number	Total number of matching documents in Solr
count	number	Number of documents returned in this response
data	object[]	Array of company documents
data[].id	string	CIF/CUI (8 digits)
data[].company	string	Company legal name
data[].brand	string	Brand name (if set)
data[].group	string	Company group (if set)
data[].status	string	`activ`, `suspendat`, `inactiv`, or `radiat`
data[].location	string[]	Array of locations
data[].website	string[]	Array of website URLs
data[].career	string[]	Array of career page URLs
data[].lastScraped	string	ISO8601 timestamp of last scrape
data[].scraperFile	string	Scraper file name

200 — Success

{
  "success": true,
  "total": 1,
  "count": 1,
  "data": [{
    "id": "24415960",
    "company": "GOOGLE ROMANIA SRL",
    "brand": "Google",
    "status": "activ",
    "location": ["București"],
    "website": ["https://google.ro"],
    "career": ["https://careers.google.com"]
  }]
}

400 — Bad Request

{
  "error": "Missing query parameter: cif or name"
}

503 — Service Unavailable

{
  "error": "Company search unavailable",
  "details": "SOLR_SERVER not set"
}

Requirements — Company Search

Item	Details
Method	`GET` only
Auth	None (public endpoint)
Params	Query: `cif` (string) or `name` (string), optional `rows` (int, max 50), `start` (int)
Content-Type	`application/json`

Status codes

200Companies found and returned successfully
400Missing required query parameter (cif or name)
405Only GET method is allowed
503Solr core is unavailable or environment not configured

PUT /v1/firme/company/add/ Add or update a company in the Solr index ▶

Upserts a company document into the Solr company core. If a document with the same CIF (id) already exists, it is replaced. Designed for scrapers and company integrations to keep the company index up to date.

How it works

Validates required fields (id as 8-digit CIF, company name)
Sanitizes string fields with htmlspecialchars to prevent XSS
Normalizes array fields (location, website, career) — accepts string or array
Validates URLs in website and career fields
Sends the document to Solr with commitWithin=1000 and overwrite=true

Authentication

This endpoint uses Solr Basic Auth via environment variables SOLR_USER and SOLR_PASS configured in api.env. No client-side authentication is required.

Request body (JSON)

Field	Type	Required	Description
id	string	Yes	8-digit CIF/CUI (e.g. `"24415960"`)
company	string	Yes	Company legal name
brand	string	No	Brand / trade name
group	string	No	Company group / parent
status	string	No	One of: `activ`, `suspendat`, `inactiv`, `radiat`
location	string\|string[]	No	City or array of cities
website	string\|string[]	No	Website URL(s) — must be valid URLs
career	string\|string[]	No	Career page URL(s) — must be valid URLs
lastScraped	string	No	ISO8601 timestamp of last scrape
scraperFile	string	No	Name of the scraper file

Try it

curl

curl -X PUT "https://api.peviitor.ro/v1/firme/company/add/" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "24415960",
    "company": "GOOGLE ROMANIA SRL",
    "brand": "Google",
    "status": "activ",
    "location": ["București"],
    "website": ["https://google.ro"],
    "career": ["https://careers.google.com"]
  }'

Response fields

Field	Type	Description
success	boolean	Always `true` on success
id	string	The CIF of the upserted company
message	string	Confirmation message

200 — Success

{
  "success": true,
  "id": "24415960",
  "message": "Company 'GOOGLE ROMANIA SRL' (24415960) upserted to company core"
}

400 — Bad Request

Returned when the request body is invalid or required fields are missing/invalid.

{
  "error": "Missing required fields: id, company",
  "code": 400
}

{
  "error": "Field 'id' must be an 8-digit CIF/CUI string (e.g. '24415960')",
  "code": 400
}

{
  "error": "Field 'status' must be one of: activ, suspendat, inactiv, radiat",
  "code": 400
}

{
  "error": "Invalid website URL: not-a-url"
}

405 — Method Not Allowed

{
  "error": "Only PUT method allowed"
}

503 — Service Unavailable

{
  "error": "Company core unavailable",
  "details": "FETCH FAILED: http://... | Connection timed out"
}

Requirements — Company Add

Item	Details
Method	`PUT` only
Auth	Solr Basic Auth (server-side, via `api.env`)
Params	Body: `{"id": "...", "company": "...", ...}`
Content-Type	`application/json`

Status codes

200Company was upserted successfully
400Invalid body, missing required fields, or validation failed
405Only PUT method is allowed
503Solr core is unavailable or environment not configured

POST /v1/scraper/jobs/upload/ Upload jobs from scrapers to Solr ▶

Accepts a JSON array of job listings and upserts them directly into the Solr job core. Designed for automated scrapers that need to upload jobs in bulk. Automatically fixes diacritics in city names and lowercases tags. Existing jobs (same url) are overwritten.

How it works

Receives a JSON array of job objects (or {"jobs": [...]})
Skips entries missing required fields (url, title, company)
Normalizes location (fixes diacritics, accepts string or array)
Lowercases tags and filters empty values
Sends to Solr with commitWithin=1000 and overwrite=true

Authentication

This endpoint uses Solr Basic Auth via environment variables SOLR_USER and SOLR_PASS configured in api.env. No client-side authentication is required.

Request body (JSON)

Accepts either a plain array [{...}, ...] or an object {"jobs": [{...}, ...]}.

Field	Type	Required	Description
url	string	Yes	Full URL to the job detail page (unique key)
title	string	Yes	Exact job position title
company	string	Yes	Hiring company name
cif	string	No	CIF/CUI of the company
location	string\|string[]	No	City or array of cities (diacritics auto-fixed)
tags	string[]	No	Skill tags (auto-lowercased)
workmode	string	No	`remote`, `on-site`, or `hybrid`
date	string	No	ISO8601 UTC timestamp
status	string	No	`scraped`, `tested`, `published`, or `verified`

Try it

curl

curl -X POST "https://api.peviitor.ro/v1/scraper/jobs/upload/" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://example.com/job/123",
      "title": "Inginer IT",
      "company": "COMPANY SRL",
      "cif": "12345678",
      "location": ["București", "Cluj-Napoca"],
      "tags": ["javascript", "react"],
      "workmode": "remote",
      "date": "2026-07-24T10:00:00Z",
      "status": "scraped"
    }
  ]'

Response fields

Field	Type	Description
success	string	Confirmation message
count	number	Number of jobs sent to Solr

200 — Success

{
  "success": "Jobs successfully uploaded to Solr",
  "count": 29
}

400 — Bad Request

{
  "error": "Payload must be a non-empty JSON array of jobs",
  "code": 400
}

{
  "error": "No valid jobs found in payload (url, title, company required)",
  "code": 400
}

405 — Method Not Allowed

{
  "error": "Only POST method is allowed",
  "code": 405
}

415 — Unsupported Media Type

{
  "error": "Content-Type must be application/json",
  "code": 415
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

Requirements — Scraper Jobs Upload

Item	Details
Method	`POST` only
Auth	Solr Basic Auth (server-side, via `api.env`)
Params	Body: `[{"url": "...", "title": "...", "company": "...", ...}]`
Content-Type	`application/json`

Status codes

200Jobs were uploaded to Solr successfully
400Empty payload, missing required fields, or invalid JSON
405Only POST method is allowed
415Content-Type is not application/json
503Solr core is unavailable or environment not configured

GET /v1/scraper/jobs/ Query jobs by company CIF ▶

Queries the Solr job core for all jobs matching a company CIF. Returns paginated results with standard job fields. Designed for scrapers that need to read existing jobs before re-scraping.

How it works

Validates the cif parameter (must be exactly 8 digits)
Escapes special Solr characters to prevent query injection
Queries the Solr job core with pagination support
Returns matching documents with standard job fields

Query parameters

Param	Type	Required	Description
cif	string	Yes	8-digit CIF/CUI (exact match)
rows	number	No	Max results (default: 100, max: 500)
start	number	No	Offset for pagination (default: 0)

Try it

curl

curl -X GET "https://api.peviitor.ro/v1/scraper/jobs/?cif=24415960" \
  -H "Accept: application/json"

curl -X GET "https://api.peviitor.ro/v1/scraper/jobs/?cif=24415960&rows=10&start=0" \
  -H "Accept: application/json"

Response fields

Field	Type	Description
success	boolean	Always `true` on success
total	number	Total number of matching jobs in Solr
count	number	Number of jobs returned in this response
data	object[]	Array of job documents

200 — Success

{
  "success": true,
  "total": 32,
  "count": 32,
  "data": [
    {
      "url": "https://example.com/job/123",
      "title": "Senior Developer",
      "company": "COMPANY SRL",
      "cif": "24415960",
      "location": ["București"],
      "tags": ["javascript"],
      "workmode": "remote",
      "date": "2026-07-26T10:00:00Z",
      "status": "scraped"
    }
  ]
}

400 — Bad Request

{
  "error": "Missing required query parameter: cif",
  "code": 400
}

{
  "error": "CIF must be exactly 8 digits",
  "code": 400
}

405 — Method Not Allowed

{
  "error": "Only GET method is allowed",
  "code": 405
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

Requirements — Scraper Jobs Query

Item	Details
Method	`GET` only
Auth	Solr Basic Auth (server-side, via `api.env`)
Params	Query: `cif` (string, required), optional `rows` (int, max 500), `start` (int)
Content-Type	`application/json`

Status codes

200Jobs found and returned successfully
400Missing or invalid CIF parameter
405Only GET method is allowed
503Solr core is unavailable or environment not configured

DELETE /v1/scraper/jobs/delete/ Delete jobs by CIF or URL ▶

Deletes jobs from the Solr job core by company CIF (all jobs) or by URL (single job). Designed for internal scraper use — when a company becomes inactive in ANAF or when expired job URLs are cleaned up.

How it works

Accepts a JSON body with cif or url
Counts matching documents before deletion
Returns 404 if no matching jobs found
Deletes all matching jobs with commit=true

Request body (JSON)

Field	Type	Required	Description
cif	string	Conditional	Delete all jobs for this 8-digit CIF
url	string	Conditional	Delete a single job by its URL

Exactly one of cif or url is required. Providing both returns an error.

Try it

curl

curl -X DELETE "https://api.peviitor.ro/v1/scraper/jobs/delete/" \
  -H "Content-Type: application/json" \
  -d '{"cif": "24415960"}'

curl -X DELETE "https://api.peviitor.ro/v1/scraper/jobs/delete/" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/job/123"}'

Response fields

Field	Type	Description
success	boolean	Always `true` on success
message	string	Confirmation message
count	number	Number of jobs deleted

200 — Success

{
  "success": true,
  "message": "Jobs deleted successfully",
  "count": 32
}

400 — Bad Request

{
  "error": "Request body must be a JSON object, not an array",
  "code": 400
}

{
  "error": "At least one of 'cif' or 'url' is required",
  "code": 400
}

{
  "error": "Provide only 'cif' or 'url', not both",
  "code": 400
}

{
  "error": "CIF must be exactly 8 digits",
  "code": 400
}

404 — No Jobs Found

{
  "error": "No jobs found",
  "message": "No jobs found matching cif:24415960",
  "count": 0
}

405 — Method Not Allowed

{
  "error": "Only DELETE method is allowed",
  "code": 405
}

415 — Unsupported Media Type

{
  "error": "Content-Type must be application/json",
  "code": 415
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

Requirements — Scraper Jobs Delete

Item	Details
Method	`DELETE` only
Auth	Solr Basic Auth (server-side, via `api.env`)
Params	Body: `{"cif": "..."}` or `{"url": "..."}`
Content-Type	`application/json`

Status codes

200Jobs were deleted successfully
400Missing required fields, invalid CIF, or invalid JSON
404No jobs found matching the criteria
405Only DELETE method is allowed
415Content-Type is not application/json
503Solr core is unavailable or environment not configured

Stare curentă a API-ului

Lucrăm la:

documentarea completă a API-ului pe baza unei specificații publice (de tip OpenAPI/Swagger)
introducerea unui mecanism de validare a domeniilor (prin înregistrări DNS TXT) pentru a lega cheile API de website-ul companiei
definirea unor endpoint-uri dedicate pentru gestionarea joburilor (creare, actualizare, închidere) într-un mod standardizat

Pe măsură ce noile endpoint-uri vor deveni disponibile, le vom publica aici împreună cu exemple de request/response și recomandări de integrare.

Cum vei putea integra website-ul tău (în curând)

Obiectivul nostru este să oferim un mod simplu și automat prin care website-urile de companii să trimită joburi către peviitor.ro prin API. Designul urmărit este:

cheile de API vor fi asociate unui domeniu de website (de exemplu, exemplu.com)
domeniul va putea fi dovedit printr-o înregistrare DNS TXT, astfel încât doar proprietarul domeniului să poată publica joburi în numele acelei companii
endpoint-uri dedicate pentru creare, actualizare și închidere joburi vor fi documentate public, cu exemple clare de integrare

Pe măsură ce aceste componente vor fi gata, le vom documenta pe această pagină.