talentkiwi
IntegrationsApi reference

Submit a file for parsing (sync or async)

POST
/v1/parse/

Parse candidate documents (CVs, resumes, cover letters) and extract structured data.

Processing Modes:

  • Asynchronous (default): Submit job and poll for results using the provided status URL
  • Synchronous: Get immediate results (suitable for smaller files)

Supported Formats:

  • PDF files (.pdf)
  • Microsoft Word documents (.doc, .docx)
  • Image files (.jpg, .jpeg, .png)
  • Plain text files (.txt)

File Requirements:

  • Maximum total pages: 50 pages across all files
  • Files are automatically converted to PDF for processing

Language Support: Currently supported languages include German, English. More languages can be requested.

Authorization

API Key Authentication
X-API-KEY<token>
Enter your secret API key to authorise requests.

You can obtain your key by contacting us: gian@dionitech.com

**Example**: `sk_live_12345abcde...`

In: header

Query Parameters

run_async?Run Async

Processing mode: Set to false for synchronous processing (immediate results). Use true for asynchronous processing (polling required).

Defaulttrue

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/v1/parse/?run_async=true" \  -F cv="string"
{
  "data": {
    "personal_info": {
      "full_name": "Matteo Guscetti",
      "email": "matteo.guscetti@yahoo.com",
      "nationality": "Schweiz",
      "gender": "Männlich",
      "civil_status": "",
      "car_license": false,
      "birth_date": "1996-12-16",
      "mobile_phone": "+41797251712",
      "home_phone": "",
      "street_and_number": "",
      "city": "",
      "state": "",
      "country": "",
      "postal_code": "",
      "linkedin": "",
      "availability": ""
    },
    "professional_summary": "Erfahrener Data Scientist mit 2+ Jahren fundierter Expertise in der Entwicklung und Implementierung fortschrittlicher ML-Modelle, einschliesslich Reinforcement Learning und CNNs. Nachweisliche Erfolgsbilanz bei der Steigerung der Prognosegenauigkeit auf über 90% mittels XGBoost und der Leitung technischer Projekte. Kompetent in Python, R und SQL.",
    "personal_impression": "Matteo Guscetti zeigte sich als selbstbewusster, ausgesprochen kommunikativer Kandidat mit hoher Teamfähigkeit. Seine offene, besonnene Art zeugt von exzellenter kultureller Passung und Lernbereitschaft.",
    "experience": [
      {
        "id": "exp_1",
        "company": "Siemens",
        "position": "Data Scientist",
        "employment_type": "Praktikum",
        "start_date": "01.2022",
        "end_date": "07.2022",
        "city": "Zürich",
        "state": "Zürich",
        "country": "Schweiz",
        "postal_code": "",
        "description_1to1": "Entwicklung eines Reinforcement-Learning-Algorithmus zum Ausgleich von Stromnetzen mit hohem Anteil erneuerbarer Energien. Arbeitete mit automatisierten Test-Pipelines (pytest) und Toolkits zur Abhängigkeitsverwaltung (poetry)",
        "reason_for_change": ""
      }
    ],
    "education": [
      {
        "id": "edu_1",
        "institution": "Eidgenössische Technische Hochschule (ETH) Zürich",
        "institution_type": "Universität",
        "city": "Zürich",
        "state": "Zürich",
        "country": "Schweiz",
        "postal_code": "",
        "degree": "Master in Datenwissenschaft",
        "degree_level": "Master",
        "field_of_study": "Datenwissenschaft",
        "start_date": "02.2020",
        "end_date": "07.2022",
        "concluded_successfully": true,
        "is_further_education": true,
        "gpa": "5.51/6",
        "description_1to1": "Austauschsemester am Imperial College London im Herbst 2020."
      }
    ],
    "skills": {
      "fields_of_experitse": [
        "Data Science",
        "Machine Learning",
        "Business Development"
      ],
      "hard_skills": [
        "Reinforcement Learning",
        "Quantitative Analyse",
        "Startup Bewertung"
      ],
      "it_skills": [
        "Python",
        "PyTorch",
        "R",
        "SQL",
        "Git",
        "CNN",
        "XGBoost"
      ],
      "soft_skills": [
        "Teamführung",
        "Kommunikation",
        "Problemlösung"
      ]
    },
    "languages": [
      {
        "language": "Italienisch",
        "standard_proficiency": "C2",
        "proficiency": "Muttersprache"
      },
      {
        "language": "Englisch",
        "standard_proficiency": "B2",
        "proficiency": "gut"
      }
    ],
    "hobbies_interests": [
      "Reisen",
      "Fotografieren",
      "Wandern"
    ]
  },
  "status_code": 200,
  "execution_time": 2.34
}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status_url": "https://api.talentkiwi.tech/v1/parse/550e8400-e29b-41d4-a716-446655440000/status",
  "result_url": "https://api.talentkiwi.tech/v1/parse/550e8400-e29b-41d4-a716-446655440000/results"
}
{
  "detail": "string"
}
Empty
{
  "detail": "string"
}
Empty
{
  "detail": "string"
}

Custom Developments

Build a custom integration between talentkiwi and your ATS or internal system.

Create PDF project from ATS applicants POST

Receive an ATS ``create-pdf`` request, resolve/provision the consultant as a TalentKiwi user, create a project with the requested candidates, kick off background ATS imports, and return a ``redirectUrl`` pointing at the new project. Authentication is via the ``X-Shared-Secret`` header — the same SHA-256 hash lookup used for regular API keys. Steps: 1. Resolve the organisation from the API key. 2. Fetch org-level HR4YOU credentials from ``DomainResourceMapping``. 3. Look up the consultant's e-mail via the HR4YOU ``/consultants/{userId}`` endpoint. 4. Resolve or auto-provision the TalentKiwi user. 5. Create a new project (default open project type). 6. Optionally attach a job post (when ``projectId`` is provided). 7. Create one candidate per ``applicantId``, tag with ATS info. 8. Enqueue a background import per candidate. 9. Return the redirect URL.