Entwickler · Kandidaten-API v1

API für den Kandidatenimport

Wie sich eine Drittsoftware mit SAM ULTIMATE verbindet, um Kandidaten anzulegen und ihre Dokumente abzulegen: Authentifizierung, Abfolge der Aufrufe und ausgetauschte Datenstrukturen.

Version 1.0.0 · OpenAPI 3.1 · Basis /external/candidate/v1OpenAPI-Spezifikation (JSON)

Zweck

Dieses Dokument beschreibt, wie sich eine Drittsoftware mit SAM ULTIMATE verbindet, um Kandidaten und ihre Dokumente zu importieren. Es stellt die Authentifizierung, die Abfolge der Aufrufe und die ausgetauschten Datenstrukturen vor.

Die Serveradressen (Authentifizierung und API) sowie Ihre Zugangsdaten werden Ihnen von Interiware separat mitgeteilt.

Anwendungsfälle aus der Praxis

Drei konkrete Wege, Ihren Kandidatenpool ohne Neuerfassung zu speisen. In jedem Fall landen Kandidat und Lebenslauf in Sekunden in SAM ULTIMATE, und der Lebenslauf wird von der künstlichen Intelligenz analysiert, wenn die Option CV-Analyse aktiv ist.

Fall 1

Die Kandidatin bewirbt sich über Ihre Karriereseite

Ihre Website bietet eine Spontanbewerbung oder die Antwort auf ein Inserat an, mit Upload des Lebenslaufs.

Die Kandidatin füllt das Formular aus und lädt ihren Lebenslauf auf Ihrer Website hoch.
Ihre Website legt das Kandidatendossier an: Identität, Kontaktdaten, Beruf aus der Berufsliste.
POST /external/candidate/v1
Sie hängt den Lebenslauf in der Kategorie CV an.
POST /external/candidate/v1/{id}/documents
SAM ULTIMATE analysiert den Lebenslauf und erstellt das Profil: Zusammenfassung, Kompetenzen, Erfahrungen, Ausbildungen, Sprachen mit Niveau, Fahrausweise.
Das Matching nutzt alle Informationen des Lebenslaufs: Die Kandidatin erscheint bei den offenen Aufträgen mit einem Relevanzscore.
Aus dem Dossier heraus stellt der Berater das Bewerbungsdossier zusammen - Profilblatt auf der Agenturvorlage, angehakte Beilagen, Notiz - und sendet es mit wenigen Klicks an die nach Beruf vorgeschlagenen Kunden.

Fall 2

Sie wählen ein Profil aus Ihrem ATS oder Intranet aus

Sie sourcen in einem Drittwerkzeug: ATS, Konzern-Intranet, geteilte Talentdatenbank. Nur die ausgewählten Profile sollen nach SAM ULTIMATE gelangen.

Ein Recruiter entdeckt ein Profil in Ihrem Werkzeug und klickt auf « An SAM ULTIMATE senden ».
Ihr Konnektor legt den Kandidaten in der Zielverwaltung an, zugeordnet zu Niederlassung und Berater (agenceId, advisorId).
POST /external/candidate/v1
Er übermittelt den Lebenslauf und gegebenenfalls Diplome oder Zertifikate, jedes in seiner Kategorie.
POST /external/candidate/v1/{id}/documents
Der Lebenslauf landet in der CV-Datenbank und wird analysiert; das strukturierte Profil fliesst sofort ins Matching ein, das alle Informationen des Lebenslaufs nutzt.
Mit wenigen Klicks geht das Kandidatendossier an alle potenziell interessierten Kunden. Danach macht der Berater weiter: Einsatz, Vertrag, Stunden, Lohn.

Fall 3

Registrierung an einer Messe oder einem Recruiting-Tag

Am Stand ersetzt ein Tablet oder ein QR-Code den Stapel Papierlebensläufe und die Tabelle vom nächsten Tag.

Der Kandidat registriert sich am Tablet oder scannt den QR-Code des Stands: Name, Telefon, Beruf, Foto seines Lebenslaufs.
Die Anwendung legt den Kandidaten sofort an, mit einer Importnotiz zur Messe (webimpnote).
POST /external/candidate/v1
Foto oder PDF des Lebenslaufs wird angehängt; bei einem Papierscan übernimmt die Texterkennung.
POST /external/candidate/v1/{id}/documents
Zurück in der Agentur sind alle Profile der Messe im Pool, analysiert, über die Importnotiz filterbar und mit wenigen Klicks den Kunden vorschlagbar.

Authentifizierung

Die API verwendet den Standard OpenID Connect (OAuth 2.0) mit dem Client-Credentials-Flow: Ihre Software tauscht ihre Zugangsdaten gegen ein Zugriffstoken und gibt dieses Token bei jedem Aufruf mit.

A. Zugriffstoken beziehen

Senden Sie eine POST-Anfrage an den Token-Endpunkt des Authentifizierungsservers, im Format application/x-www-form-urlencoded:

POST {Authentifizierungsserver}/auth/realms/SAM/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_LOGIN&client_secret=YOUR_PASSWORD

Die Antwort enthält das Token im Feld access_token sowie seine Gültigkeitsdauer in Sekunden (expires_in). Fordern Sie ein neues Token an, wenn es abläuft.

B. Header bei jedem Aufruf

Header	Wert
`Authorization`	Bearer {access_token}
`X-SUBTENANT-ID`	Kennung der Zielverwaltung (Niederlassung), von Interiware mitgeteilt. Bei allen Aufrufen obligatorisch.

Integrationsablauf

Wir empfehlen folgende Abfolge:

Verbindung testen
Rufen Sie GET /external/candidate/v1/ping auf. Eine Antwort 200 bestätigt, dass Token und Header X-SUBTENANT-ID akzeptiert werden.
Referenzwerte laden
Holen Sie die Liste der Berufe (GET /external/candidate/v1/occupations) und, falls Sie Dokumente senden, die Liste der Kategorien (GET /external/candidate/v1/document-categories). Tun Sie das vor jedem Import: Ein Kandidat muss mindestens einen bestehenden Beruf referenzieren.
Kandidat anlegen
POST /external/candidate/v1. Die Antwort liefert den angelegten Kandidaten; bewahren Sie seine id auf.
Dokumente anhängen
Für jede Datei POST /external/candidate/v1/{id}/documents?category={code}, wobei {id} die Kennung des Kandidaten ist und {code} eine Kategorie mit parentType EMPLOYEE. Ein in der Kategorie CV abgelegtes Dokument wird wie ein direkt in SAM ULTIMATE geladener Lebenslauf analysiert, sofern die CV-Analyse für Ihre Verwaltung aktiviert ist.

Endpunkte

Die folgenden Pfade sind relativ zur Ihnen mitgeteilten API-Adresse. Klicken Sie auf einen Endpunkt, um die Details zu sehen.

GET/external/candidate/v1/pingVerbindungstest

Liefert 200, wenn Token und Header X-SUBTENANT-ID akzeptiert werden.

Parameter

Name	Ort	Typ	Beschreibung
`X-SUBTENANT-ID`*	Header	`string`	Sub-tenant identifier

Antworten

Code	Beschreibung	Inhalt
`200`	OK	`/` · `string`

GET/external/candidate/v1/occupationsListe der Berufe

Berufsverzeichnis der Verwaltung. Ein Kandidat muss mindestens einen Beruf über seine id referenzieren. Bevorzugen Sie aktive Berufe.

Parameter

Name	Ort	Typ	Beschreibung
`X-SUBTENANT-ID`*	Header	`string`	Sub-tenant identifier

Antworten

Code	Beschreibung	Inhalt
`200`	OK	`/` · Occupation[]

POST/external/candidate/v1Kandidat anlegen

Legt ein Kandidatendossier an. Die Antwort liefert den angelegten Kandidaten mit der von SAM ULTIMATE vergebenen id, die in den folgenden Aufrufen zu verwenden ist.

Parameter

Name	Ort	Typ	Beschreibung
`X-SUBTENANT-ID`*	Header	`string`	Sub-tenant identifier

Anfragekörper*`application/json`

Typ : CandidatePflichtfelder : firstName, gender, lastName, occupationIds

Antworten

Code	Beschreibung	Inhalt
`200`	OK	`/` · Candidate

GET/external/candidate/v1/document-categoriesDokumentkategorien

Die Kategorien, unter denen ein Kandidatendokument abgelegt werden kann. Für einen Kandidaten ist der parentType EMPLOYEE.

Parameter

Name	Ort	Typ	Beschreibung
`X-SUBTENANT-ID`*	Header	`string`	Sub-tenant identifier

Antworten

Code	Beschreibung	Inhalt
`200`	OK	`/` · DocumentCategory[]

POST/external/candidate/v1/{id}/documentsDokument an einen Kandidaten anhängen

Versand als multipart/form-data, Feld file. Ein Dokument der Kategorie CV wird wie ein direkt in SAM ULTIMATE geladener Lebenslauf analysiert, sofern die CV-Analyse aktiviert ist.

Parameter

Name	Ort	Typ	Beschreibung
`id`*	Pfad	`string`	ID of the candidate
`category`*	Query	`string`	Code of a category from /document-categories
`X-SUBTENANT-ID`*	Header	`string`	Sub-tenant identifier

Anfragekörper`multipart/form-data`

Feld	Typ	Einschränkungen	Beschreibung
`file`*	`string (binary)`	Datei	File to upload

Antworten

Code	Beschreibung	Inhalt
`200`	OK	`/` · Document

Ein Kandidat wird in SAM ULTIMATE als Mitarbeitendendossier gespeichert: Die von /document-categories gelieferten Kategorien sind daher jene der Mitarbeitendendokumente (parentType = EMPLOYEE).

Datenmodelle

Die angegebenen Längen sind Maximalwerte. Mit einem Stern markierte Felder sind Pflichtfelder.

CandidateobjectPflichtfelder : firstName, gender, lastName, occupationIds

Feld	Typ	Einschränkungen	Beschreibung
`id`	`string`		Von SAM ULTIMATE vergebene Kennung (bei der Erstellung zurückgegeben, nicht mitsenden).
`agenceId`	`string`		Zugehörige Niederlassung (von Interiware mitgeteilte Kennung).
`advisorId`	`string`		Zuständiger Berater (von Interiware mitgeteilte Kennung).
`gender`*	`enum`		Geschlecht. `FEMALE` – Frau `MALE` – Mann
`firstName`*	`string`	max. 60 Zeichen	Vorname.
`lastName`*	`string`	max. 60 Zeichen	Name.
`address`	`Address`		Postadresse.
`phone`	`string`	max. 20 Zeichen	Festnetz.
`mobile`	`string`	max. 20 Zeichen	Mobiltelefon.
`email`	`string`	max. 50 Zeichen, Format: ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$\|^\s*$	Gültige E-Mail-Adresse.
`avsNumber`	`string`	max. 16 Zeichen	AHV-Nummer, Format 756.XXXX.XXXX.XX.
`nationality`	`string`	max. 3 Zeichen	Nationalität, ISO-Ländercode (z. B. CH).
`birthDate`	`string (date)`	Datum (JJJJ-MM-TT)	Geburtsdatum.
`birthPlace`	`string`	max. 30 Zeichen	Geburtsort.
`workPermitType`	`enum`		Art der Arbeitsbewilligung. `SHORT_TERM_L` – Ausweis L – Kurzaufenthalt `ANNUAL_B` – Ausweis B – Aufenthalt `SETTLED_C` – Ausweis C – Niederlassung `CROSS_BORDER_G` – Ausweis G – Grenzgänger `ASYLUM_SEEKER_N` – Ausweis N – Asylsuchende `NEED_FOR_PROTECTION_S` – Ausweis S – Schutzbedürftige `NOTIFICATION_PROCEDURE_FOR_SHORTTERM_WORK_90_DAYS` – Meldeverfahren – 90 Tage `NOTIFICATION_PROCEDURE_FOR_SHORTTERM_WORK_120_DAYS` – Meldeverfahren – 120 Tage `PROVISIONALLY_ADMITTED_FOREIGNERS_F` – Ausweis F – vorläufig Aufgenommene `RESIDENT_FOREIGN_NATIONAL_WITH_GAINFUL_EMPLOYMENT_CI` – Ausweis Ci – Erwerbstätigkeit `OTHERS_NOT_SWISS` – Andere (nicht Schweizer)
`partnerNationality`	`string`	max. 3 Zeichen	Nationalität des Partners, ISO-Ländercode.
`partnerWorksInCH`	`boolean`		Der Partner arbeitet in der Schweiz.
`numberOfChildren`	`integer (int32)`	Ganzzahl	Anzahl Kinder.
`primaryMotherTongue`	`string`		Erste Muttersprache (von Interiware mitgeteilter Sprachcode).
`secondaryMotherTongue`	`string`		Zweite Muttersprache (gleiches Verzeichnis).
`ownsCar`	`boolean`		Besitzt ein Auto.
`ownsMotorbike`	`boolean`		Besitzt ein Motorrad.
`ownsBicycle`	`boolean`		Besitzt ein Fahrrad.
`hasCarLicense`	`boolean`		Führerausweis Auto.
`hasMotorbikeLicense`	`boolean`		Führerausweis Motorrad.
`hasHeavyVehicleLicense`	`boolean`		Führerausweis Lastwagen.
`hasTrailerLicense`	`boolean`		Führerausweis Anhänger.
`hasConstructionMachineLicense`	`boolean`		Führerausweis Baumaschinen.
`comment`	`string`		Freier Kommentar.
`evaluationComment`	`string`		Beurteilungskommentar.
`webimpnote`	`string`		Importnotiz.
`occupationIds`*	`string[]`	mindestens 1 Element	Berufskennungen aus /occupations.

AddressobjectKeine Pflichtfelder

Feld	Typ	Einschränkungen	Beschreibung
`line1`	`string`	max. 50 Zeichen	Adresszeile 1.
`line2`	`string`	max. 50 Zeichen	Adresszeile 2.
`line3`	`string`	max. 50 Zeichen	Adresszeile 3.
`postalCode`	`string`	max. 8 Zeichen	Postleitzahl.
`city`	`string`	max. 30 Zeichen	Ort.
`country`	`string`	max. 3 Zeichen	Land, ISO-Code (z. B. CH).

OccupationobjectKeine Pflichtfelder

Feld	Typ	Beschreibung
`id`	`string`	Kennung, die in occupationIds zu übernehmen ist.
`nameFr`	`string`	Bezeichnung auf Französisch.
`nameDe`	`string`	Bezeichnung auf Deutsch.
`active`	`boolean`	Aktiver Beruf. Bevorzugen Sie aktive Berufe.
`suvaMapped`	`boolean`	Beruf der SUVA-Nomenklatur zugeordnet.

DocumentCategoryobjectKeine Pflichtfelder

Feld	Typ	Beschreibung
`code`	`string`	Code, der im Parameter category des Uploads zu übergeben ist.
`parentType`	`enum`	Betroffener Entitätstyp. Für einen Kandidaten: EMPLOYEE. `EMPLOYEE` – Mitarbeitende (Kandidat) `MISSION` `SALARIED_EMPLOYEE` `CLIENT` `DEBTOR` `BOOKING` `PERMANENT_ASSIGNMENT` `TEMPORARY_ASSIGNMENT` `CCT` `BANK_TRANSFER_ORDER` `WORK_REPORT`
`description`	`string`	Bezeichnung der Kategorie.

DocumentobjectKeine Pflichtfelder

Feld	Typ	Einschränkungen	Beschreibung
`id`	`string`		Kennung des Dokuments.
`lastModifiedBy`	`string`		Urheber der letzten Änderung.
`dateTrack`	`string (date-time)`	Datum und Uhrzeit (ISO 8601)	Datum der letzten Änderung.
`deleted`	`boolean`		Dokument gelöscht.
`entityType`	`enum`		Entität, an die das Dokument angehängt ist (EMPLOYEE für einen Kandidaten). `EMPLOYEE` – Mitarbeitende (Kandidat) `MISSION` `SALARIED_EMPLOYEE` `CLIENT` `DEBTOR` `BOOKING` `PERMANENT_ASSIGNMENT` `TEMPORARY_ASSIGNMENT` `CCT` `BANK_TRANSFER_ORDER` `WORK_REPORT`
`entityId`	`string`		Kennung dieser Entität (id des Kandidaten).
`categoryCode`	`string`		Kategorie des Dokuments.
`description`	`string`		Beschreibung.
`fileName`	`string`		Dateiname.
`contentType`	`string`		MIME-Typ der Datei.
`documentId`	`string`		Kennung der gespeicherten Datei.

Beispiel: Kandidat anlegen

Realistische Minimalanfrage: Identität, Kontaktdaten, Adresse und mindestens ein Beruf.

POST /external/candidate/v1
Authorization: Bearer {access_token}
X-SUBTENANT-ID: {Verwaltungskennung}
Content-Type: application/json

{
  "gender": "FEMALE",
  "firstName": "Anna",
  "lastName": "Beispiel",
  "email": "anna.beispiel@example.com",
  "mobile": "+41 79 000 00 00",
  "birthDate": "1990-05-14",
  "nationality": "CH",
  "address": {
    "line1": "Beispielstrasse 1",
    "postalCode": "8000",
    "city": "Zürich",
    "country": "CH"
  },
  "occupationIds": ["{id aus /occupations}"]
}

Interaktive Dokumentation und Support

Die Swagger-Oberfläche der Kandidaten-API enthält alle diese Informationen und erlaubt das Testen der Aufrufe. Ihre Adresse wird Ihnen mit Ihren Zugangsdaten mitgeteilt.

Bei technischen Fragen schreiben Sie an support@interiware.com.

OpenAPI-Spezifikation herunterladen (JSON)

API für den Kandidatenimport

Zweck

Anwendungsfälle aus der Praxis

Authentifizierung

A. Zugriffstoken beziehen

B. Header bei jedem Aufruf

Integrationsablauf

Endpunkte

Parameter

Antworten

Parameter

Antworten

Parameter

Anfragekörper*application/json

Antworten

Parameter

Antworten

Parameter

Anfragekörpermultipart/form-data

Antworten

Datenmodelle

Beispiel: Kandidat anlegen

Interaktive Dokumentation und Support

Anfragekörper*`application/json`

Anfragekörper`multipart/form-data`