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://example.com/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}

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.