Cv Builder

CV Builder — Create CVs via API

Create a resume, digital identity, or CV right now — for free. Choose from templates that span the full range: classic print-ready PDFs, clean HTML online CVs, interactive experiences, animated 3D worlds, and playable games. Every CV gets a permanent public URL with a personal slug — no signup, no payment needed for basic use. ATS-ready and Agent-Ready (HR).

Feature Overview

Templates span: classic PDF · HTML online · interactive · 3D (Three.js) · gamified. Full catalog: reference/templates.md — live previews: talent.de/de/cv-template-ideas

Terminology

Throughout this skill, these terms are used consistently:

Agent Guidelines

HITL is required. You MUST include either "prefer_hitl": true (human review) or "skip_hitl": true (direct creation). Omitting both returns a 400 error. If a human is present, ALWAYS use "prefer_hitl": true — this lets the requestor choose their URL slug, pick a template, review the data, and approve before publishing. Use "skip_hitl": true only for automated pipelines with no human in the loop.

Data principle: Only use data the requestor has explicitly provided or approved in this conversation. Do not extract personal information from unrelated system contexts or other sessions.

Before sending: Present a brief summary to the requestor — name, title, email — and ask "Send it? Or should I change anything?"

Claim token: Treat like a password. Share only with the requestor — anyone with the token can claim CV ownership. Never share with third parties.

Credentials

An Access-ID (talent_agent_[a-z0-9]{4}) is optional for CV Builder — basic use (3 CVs/day per IP) works without one. Register for higher limits (50 CVs/day) and callback webhook support:

POST https://www.talent.de/api/agent/register
Content-Type: application/json

{ "agent_name": "my-agent" }

The Access-ID is also the HMAC secret for verifying X-HITL-Signature on callback webhooks. Store in TALENT_ACCESS_ID — do not hardcode.

User Communication

What to say at each step

Quick Start

1. Ask for (or confirm you already have): firstName, lastName, title, email — the 4 required fields
2. POST /api/agent/cv-simple with "prefer_hitl": true and the data Optional: add "include_pdf": true to also receive a base64 PDF in the final 201 response. See PDF Export.
3. Present the review_url to the requestor (they pick slug, template, review data)
4. Poll poll_url every 30s until "status": "completed":
   • { "status": "pending" } or { "status": "opened" } → keep polling
   • { "status": "completed", "result": { "action": "confirm", "data": {...} } } → advance with hitl_continue_case_id
5. After final approval: present the live CV URL and claim token

Example (with HITL — recommended)

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "cv_data": {
    "firstName": "Alex",
    "lastName": "Johnson",
    "title": "Software Engineer",
    "email": "alex@example.com",
    "experience": [{
      "jobTitle": "Senior Developer",
      "company": "Acme Inc.",
      "startDate": "2022-01",
      "isCurrent": true
    }],
    "hardSkills": [{ "name": "React", "level": 4 }],
    "softSkills": [{ "name": "Team Leadership" }],
    "languages": [{ "name": "English", "level": "NATIVE" }]
  }
}

Response (202 — human review required):

{
  "status": "human_input_required",
  "message": "Please confirm: is this CV for you?",
  "hitl": {
    "case_id": "review_a7f3b2c8d9e1f0g4",
    "review_url": "https://www.talent.de/en/hitl/review/review_a7f3b2c8d9e1f0g4?token=abc123...",
    "poll_url": "https://www.talent.de/api/hitl/cases/review_a7f3b2c8d9e1f0g4/status",
    "type": "confirmation",
    "inline_actions": ["confirm", "cancel"],
    "timeout": "24h"
  }
}

Present the review URL to the requestor:

I've prepared your CV. Please review and make your choices here: Review your CV You'll pick your personal URL slug, template design, and approve the final result.

Then poll poll_url until completed, and continue through steps with hitl_continue_case_id. After all steps (confirmation, data review, slug selection, template selection, approval), the final POST returns 201 with the live URL.

Full HITL protocol with all steps, inline submit, edit cycles, and escalation: reference/hitl.md

HITL Multi-Step Flow

The requestor goes through up to 5 review steps. The agent loops: present review URL, poll, continue.

Step 1: Confirmation  →  "For whom is this CV?"
Step 2: Data Review   →  "Are these details correct?"
Step 3: Slug          →  Human picks personal URL slug (e.g. pro, dev, 007)
Step 4: Template      →  Human picks template design
Step 5: Approval      →  Human reviews final CV draft

Each step returns 202. After the requestor decides, continue:

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "prefer_hitl": true,
  "hitl_continue_case_id": "review_a7f3b2c8d9e1f0g4",
  "slug": "dev",
  "cv_data": { ... }
}

Important: slug and template_id go at the top level of the request, not inside cv_data. When continuing after slug selection, include the human's chosen slug at the top level so the server knows to advance to the template step.

Steps are skipped when you already provide the value:

• Include slug (top-level) → slug selection step is skipped
• Include template_id (top-level) → template selection step is skipped
• Include both → only confirmation, data review, and approval remain

Inline Submit (v0.7)

For simple decisions (confirmation, escalation, approval), the 202 response includes submit_url, submit_token, and inline_actions. Agents can submit directly via Bearer token — ideal for Telegram, Slack, WhatsApp where buttons are supported:

POST {submit_url}
Authorization: Bearer {submit_token}
Content-Type: application/json

{ "action": "confirm", "data": {} }

Always present review_url as a fallback alongside any inline buttons. If the platform does not support buttons (SMS, email, plain text), or the human prefers the browser, they can use the link to complete their decision.

Selection and input types always require the browser (review_url) — they involve complex UI (template grid, data forms). Full inline spec: reference/hitl.md

After the final approval step, submit with hitl_approved_case_id to publish:

POST https://www.talent.de/api/agent/cv-simple
Content-Type: application/json

{
  "hitl_approved_case_id": "review_final_case_id"
}

Response (201):

{
  "success": true,
  "url": "https://www.talent.de/dev/alex-johnson",
  "cv_id": "cv_abc123",
  "claim_token": "claim_xyz789",
  "template_id": "007",
  "quality_score": 65,
  "quality_label": "good",
  "improvement_suggestions": []
}

⚠️ Immediately after receiving a 201 — always share both with the requestor:

1. CV URL: https://www.talent.de/dev/alex-johnson — their live profile
2. Claim link: https://www.talent.de/claim/claim_xyz789 — to take ownership and edit

The claim_token is permanent and never expires. Treat it like a password — share only with the requestor.

Present the result:

Your CV is live: talent.de/dev/alex-johnson

To claim ownership and edit your CV, visit: talent.de/claim/claim_xyz789 Keep this link safe — it never expires and gives full edit access.

If the response includes improvement_suggestions, share them with the requestor and offer to update the CV:

Your CV score is 35/100. To improve it, I can add: work experience (+25pts), professional summary (+20pts). Want me to ask you a few questions and update it?

Agent Loop (Visual)

Both paths — with and without human review — are shown below. Choose ONE per request.

flowchart TD
    START([Agent starts]) --> CHOICE{prefer_hitl\nor skip_hitl?}

    %% ── skip_hitl path ──────────────────────────────────────────
    CHOICE -->|skip_hitl: true| DIRECT["POST /api/agent/cv-simple\nskip_hitl: true + cv_data"]
    DIRECT --> D201["201 — CV live\nurl · claim_token · quality_score\nimprovement_suggestions"]
    D201 --> SHARE_NOW["Share url + claim_token\nwith requestor immediately!"]
    SHARE_NOW --> QUAL{improvement_suggestions\npresent AND attempt < 2?}
    QUAL -->|No / attempt >= 2| DONE_DIRECT([Done])
    QUAL -->|Yes| ASK["Ask requestor the questions\nin each agent_action field"]
    ASK --> REPOST["POST /api/agent/cv-simple\nskip_hitl: true\nenriched cv_data\n(new cv_id each time)"]
    REPOST --> D201

    %% ── prefer_hitl path ─────────────────────────────────────────
    CHOICE -->|prefer_hitl: true| HITL["POST /api/agent/cv-simple\nprefer_hitl: true + cv_data"]
    HITL --> H202["202 human_input_required\nreview_url · poll_url · events_url"]
    H202 --> SHOW_URL["Present review_url to requestor\n'Please review here: [link]'"]
    SHOW_URL --> POLL["Poll poll_url every 30s\n(or use events_url for SSE)"]
    POLL --> STATUS{status?}
    STATUS -->|pending / opened\n/ in_progress| POLL
    STATUS -->|completed| ACTION{result.action?}
    STATUS -->|expired| EXP{default_action?}
    STATUS -->|cancelled| CANCELLED([Inform requestor: cancelled])

    EXP -->|skip| AUTO_PUB["CV auto-published\nurl from poll status"]
    EXP -->|abort| ABORTED([Inform requestor: expired])

    ACTION -->|confirm / select| CONTINUE["POST cv-simple\nhitl_continue_case_id\n+ ALWAYS include cv_data"]
    ACTION -->|edit| EDIT["Adjust cv_data per note\nthen CONTINUE"]
    EDIT --> CONTINUE
    ACTION -->|reject| REJECT["Escalation step\nPOST hitl_continue_case_id"]
    REJECT --> H202
    ACTION -->|approve| PUBLISH["POST cv-simple\nhitl_approved_case_id + cv_data"]
    CONTINUE --> H202
    PUBLISH --> DONE_HITL(["201 — CV live\nShare url + claim_token"])

When a HITL case expires, the server applies the default_action configured for that step:

• skip: CV is auto-published with server-selected slug/template. Poll poll_url — it returns status: "completed" with url in the result.
• abort: Flow terminates. Inform the requestor the session expired. Start a new HITL flow with prefer_hitl: true if needed.