canonical: https://jentic.com/apis/hrflow.ai/hrflow

# HrFlow.ai API

Jentic publishes the only available OpenAPI specification for HrFlow.ai API, keeping it validated and agent-ready. The HrFlow.ai API is an AI-powered HR data platform - index profiles and jobs, parse resumes from text or files, tag and vectorize content, geocode locations, run OCR, and rate profile-job fit. It exposes 28 endpoints spanning storage (sources, boards) and inference (parsing, tagging, embedding, rating). Useful for applicant scoring, automated resume ingestion, and AI agents that augment a human-driven ATS.

## For AI agents

Index, parse, tag, and match candidate profiles and jobs with AI inference endpoints on the HrFlow.ai HR platform.

## Scope

Does not handle payroll, employee onboarding, or interview scheduling - use for HR data parsing, indexing, tagging, embedding, and matching only.

## Capabilities

- Parse resumes from PDF, DOCX, or raw text into structured candidate profiles
- Index profiles and jobs into a HrFlow source or board for retrieval
- Generate text embeddings for semantic candidate-job matching
- Tag arbitrary text with HR taxonomies (skills, seniority, function)
- Score profile-to-job fit with the rating endpoint
- Geocode candidate or job locations into structured coordinates
- Run OCR on scanned documents to extract text before parsing

## Use cases

### Automated Resume Intake

Ingest resumes from email or career portals automatically. The agent calls POST `/profile/parsing/file` with the uploaded resume, then POST `/profile/indexing` to persist the structured profile in a HrFlow source. Replaces manual recruiter data entry and feeds downstream matching.

Example prompt: Parse the uploaded resume.pdf via POST `/profile/parsing/file` and index the resulting profile into source_key 'inbound-careers'.

### Candidate-to-Job Matching

Score every active candidate against open jobs to surface a shortlist. The agent calls POST /rating with the profile and job references and returns ranked matches. For semantic discovery without explicit ratings, use POST `/vectorizing/text` to generate embeddings and run nearest-neighbour search against indexed profiles.

Example prompt: Call POST /rating with profile_key=p_123 and job_key=j_456 and return the resulting fit score and explanation.

### Job Description Enrichment

Enrich job descriptions with structured tags before posting. The agent calls POST `/tagging/text` to extract skills, seniority, and function labels, and POST `/imaging/text` to generate a job illustration. Improves search discoverability on career sites.

Example prompt: Tag a job description via POST `/tagging/text` and attach the returned skill list to the indexed job record.

### Resume OCR Pipeline

Process scanned PDF resumes by running them through OCR before parsing. The agent calls POST `/ocr/text` to extract raw text from images, then POST `/parsing/text` on the result, then POST `/profile/indexing` to persist the candidate. Captures candidates from old scanned formats that PDF parsers fail on.

Example prompt: Run OCR on a scanned resume image, parse the resulting text into a profile, and index the profile into source_key 'scanned-archive'.

### AI Recruiting Agent via Jentic

Expose HrFlow.ai's parsing, tagging, embedding, and matching endpoints to an AI recruiter agent through Jentic. The agent searches by intent, Jentic returns the right inference endpoint, and execution happens with the API key kept in your Jentic One instance.

Example prompt: Search Jentic for 'parse resume', load the POST `/profile/parsing/file` schema, and execute against the candidate's uploaded PDF.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/profile/parsing/file` | Parse a resume PDF or DOCX into a profile |
| POST | `/profile/indexing` | Index a candidate profile into a source |
| POST | `/job/indexing` | Index a job into a board |
| POST | `/tagging/text` | Tag text with HR taxonomy labels |
| POST | `/vectorizing/text` | Generate text embeddings |
| POST | `/rating` | Score a profile against a job |
| POST | `/ocr/text` | Extract text from a scanned image |

## Key resources

- **Profiles** — Candidate profile indexing, retrieval, archiving, and parsing.
- **Jobs** — Job indexing, retrieval, and archiving against a board.
- **Sources** — Containers that hold groups of candidate profiles.
- **Boards** — Containers that hold groups of jobs.
- **Text Processing** — Parsing, tagging, OCR, vectorizing, geocoding, synonyms, and rating endpoints.
- **Workflows** — Discover configured workflows and integration runs.
- **Authentication** — Verify the API key and email-auth combination is valid.

## Why Jentic

- **Setup:** Wiring HrFlow.ai by hand means sending both its X-API-KEY and X-USER-EMAIL headers on every request, keeping the api.hrflow.ai/v1 host straight across parsing and inference endpoints, and handling errors yourself. Through Jentic you install once, import the HrFlow.ai API from the API Directory, store both credentials once, and your agent calls it.
- **Permission scoping:** HrFlow.ai takes its targets in the request body, so scope your agent to the operations it needs, such as parsing a resume file or tagging text. You choose which calls are in the allowed set, so indexing or rating operations are excluded unless you add them.
- **Credential handling:** Your HrFlow.ai X-API-KEY and X-USER-EMAIL values are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'parse a resume PDF' or 'vectorize this text', and Jentic returns the matching HrFlow.ai operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Homerun Public API** — ATS that holds the canonical job application records HrFlow can score and parse for.
- **Greenhouse Harvest API** — Enterprise ATS where HrFlow's parsing and matching can augment recruiter workflows.
- **Workable API** — SMB ATS with native sourcing primitives that HrFlow inference can enhance.

## FAQ

### Why is there no official OpenAPI spec for HrFlow.ai API?

HrFlow.ai does not publish a maintained public OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call HrFlow.ai API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the HrFlow.ai API use?

The API uses two header credentials: an API key (X-API-Key) and a user email (X-USER-EMAIL). Both are required on every call. Jentic stores them encrypted in your Jentic One instance and injects both headers at execution time.

### Can I parse a resume PDF with the HrFlow.ai API?

Yes. POST `/profile/parsing/file` accepts a multipart upload of a resume in PDF or DOCX and returns a structured candidate profile. For raw text input, use POST `/parsing/text` instead. Combine with POST `/profile/indexing` to persist the result.

### What are the rate limits for the HrFlow.ai API?

HrFlow.ai applies per-account rate limits that scale with plan tier. Inference endpoints (parsing, OCR, vectorizing) are heavier than indexing and storage calls - back off on 429 responses and batch where the endpoint supports it.

### How do I score a candidate against a job with the HrFlow.ai API through Jentic?

Run pip install jentic, search for 'rate profile against job', load the POST /rating schema, and execute with the profile and job keys. Jentic returns the structured rating response with the API key handled in the vault.

### Can I generate embeddings for semantic candidate search with the HrFlow.ai API?

Yes. POST `/vectorizing/text` returns an embedding vector for any text input. Pair it with profiles indexed via POST `/profile/indexing` and run nearest-neighbour search externally to surface semantically similar candidates.

### Can I limit what my agent is allowed to do with the HrFlow.ai API?

Yes. Because you run Jentic One yourself, your own rules decide which HrFlow.ai operations and credentials your agent may use, and it can call only the ones you add to its allowed set. If a recruiting agent only needs to read and structure resumes, you can grant POST `/profile/parsing/file` and POST `/tagging/text` while leaving write operations like POST `/profile/indexing` and POST /rating out. Since HrFlow.ai takes its targets in the request body, this operation-level allow list is what controls exactly what the agent can reach.