Développeurs · API Candidats v1

API d'import de candidats

Comment un logiciel tiers se connecte à SAM ULTIMATE pour y créer des candidats et joindre leurs documents : authentification, enchaînement des appels et structures de données échangées.

Version 1.0.0 · OpenAPI 3.1 · base /external/candidate/v1Spécification OpenAPI (JSON)

Objet

Ce document décrit comment un logiciel tiers se connecte à SAM ULTIMATE pour y importer des candidats et leurs documents. Il présente l'authentification, l'enchaînement des appels et les structures de données échangées.

Les adresses des serveurs (authentification et API), ainsi que vos identifiants de connexion, vous sont communiqués séparément par Interiware.

Cas d'utilisation métiers

Trois façons concrètes d'alimenter votre vivier sans ressaisie. Dans chaque cas, le candidat et son CV arrivent dans SAM ULTIMATE en quelques secondes, et le CV est analysé par l'intelligence artificielle lorsque l'option d'analyse de CV est active.

Cas 1

Le candidat postule depuis votre site carrière

Votre site web propose un formulaire de candidature spontanée ou une réponse à une annonce, avec dépôt du CV.

Le candidat remplit le formulaire et dépose son CV sur votre site.
Votre site crée la fiche candidat : identité, coordonnées, profession choisie dans la liste des professions.
POST /external/candidate/v1
Il joint le CV dans la catégorie CV.
POST /external/candidate/v1/{id}/documents
SAM ULTIMATE analyse le CV et crée le profil : résumé, compétences, expériences, formations, langues avec niveau, permis.
Le matching exploite toutes les informations du CV : le candidat remonte sur les commandes ouvertes avec un score de pertinence.
Depuis la fiche, le conseiller compose le dossier de candidature - fiche descriptive sur le modèle de l'agence, pièces cochées, note - et l'envoie en quelques clics aux clients suggérés par profession.

Cas 2

Vous sélectionnez un profil depuis votre ATS ou votre intranet

Vous sourcez dans un outil tiers : ATS, intranet groupe, base de talents partagée. Seuls les profils retenus doivent rejoindre SAM ULTIMATE.

Un recruteur repère un profil dans votre outil et clique sur « Envoyer vers SAM ULTIMATE ».
Votre connecteur crée le candidat dans la gestion visée, rattaché à l'agence et au conseiller (agenceId, advisorId).
POST /external/candidate/v1
Il transmet le CV et, s'il y a lieu, les diplômes ou certificats, chacun dans sa catégorie.
POST /external/candidate/v1/{id}/documents
Le CV rejoint la CV-thèque et est analysé ; le profil structuré entre aussitôt dans le matching, qui utilise toutes les informations du CV.
En quelques clics, le dossier candidat part vers tous les clients potentiellement intéressés. Le conseiller enchaîne ensuite : mission, contrat, heures, salaire.

Cas 3

Inscription sur un salon ou lors d'une journée de recrutement

Sur un stand, une tablette ou un QR code remplace la pile de CV papier et le tableur du lendemain.

Le candidat s'inscrit sur la tablette ou scanne le QR code du stand : nom, téléphone, profession, photo de son CV.
L'application crée le candidat en direct, avec une note d'import identifiant le salon (webimpnote).
POST /external/candidate/v1
La photo ou le PDF du CV est joint ; la reconnaissance de texte prend le relais pour un scan papier.
POST /external/candidate/v1/{id}/documents
Dès le retour à l'agence, tous les profils du salon sont dans le vivier, analysés, filtrables par la note d'import et déjà proposables aux clients en quelques clics.

Authentification

L'API utilise le standard OpenID Connect (OAuth 2.0), avec le flux client credentials : votre logiciel échange ses identifiants contre un jeton d'accès, puis présente ce jeton à chaque appel.

A. Obtenir un jeton d'accès

Envoyez une requête POST vers l'endpoint de jeton du serveur d'authentification, au format application/x-www-form-urlencoded :

POST {serveur d'authentification}/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

La réponse contient le jeton dans le champ access_token, ainsi que sa durée de validité en secondes (expires_in). Demandez un nouveau jeton lorsqu'il arrive à expiration.

B. En-têtes à envoyer à chaque appel

En-tête	Valeur
`Authorization`	Bearer {access_token}
`X-SUBTENANT-ID`	Identifiant de la gestion (agence) cible, communiqué par Interiware. Obligatoire sur tous les appels.

Parcours d'intégration

Nous recommandons l'enchaînement suivant :

Tester la connexion
Appelez GET /external/candidate/v1/ping. Une réponse 200 confirme que le jeton et l'en-tête X-SUBTENANT-ID sont acceptés.
Charger les valeurs de référence
Récupérez la liste des professions (GET /external/candidate/v1/occupations) et, si vous envoyez des documents, la liste des catégories (GET /external/candidate/v1/document-categories). Faites-le avant tout import : un candidat doit référencer au moins une profession existante.
Créer le candidat
POST /external/candidate/v1. La réponse renvoie le candidat créé ; conservez son id.
Joindre les documents
Pour chaque fichier, POST /external/candidate/v1/{id}/documents?category={code}, où {id} est l'identifiant du candidat et {code} une catégorie dont le parentType vaut EMPLOYEE. Un document déposé dans la catégorie CV est analysé comme un CV chargé directement dans SAM ULTIMATE, lorsque l'analyse de CV est activée pour votre gestion.

Endpoints

Les chemins ci-dessous sont relatifs à l'adresse de l'API qui vous a été communiquée. Cliquez sur un endpoint pour en voir le détail.

GET/external/candidate/v1/pingTest de connexion

Renvoie 200 si le jeton et l'en-tête X-SUBTENANT-ID sont acceptés.

Paramètres

Nom	Emplacement	Type	Description
`X-SUBTENANT-ID`*	en-tête	`string`	Sub-tenant identifier

Réponses

Code	Description	Contenu
`200`	OK	`/` · `string`

GET/external/candidate/v1/occupationsListe des professions

Référentiel des professions de la gestion. Un candidat doit référencer au moins une profession par son id. Privilégiez les professions actives.

Paramètres

Nom	Emplacement	Type	Description
`X-SUBTENANT-ID`*	en-tête	`string`	Sub-tenant identifier

Réponses

Code	Description	Contenu
`200`	OK	`/` · Occupation[]

POST/external/candidate/v1Créer un candidat

Crée une fiche candidat. La réponse renvoie le candidat créé, avec l'id attribué par SAM ULTIMATE à reporter dans les appels suivants.

Paramètres

Nom	Emplacement	Type	Description
`X-SUBTENANT-ID`*	en-tête	`string`	Sub-tenant identifier

Corps de la requête*`application/json`

Type : CandidateChamps obligatoires : firstName, gender, lastName, occupationIds

Réponses

Code	Description	Contenu
`200`	OK	`/` · Candidate

GET/external/candidate/v1/document-categoriesCatégories de documents

Les catégories sous lesquelles un document de candidat peut être classé. Pour un candidat, le parentType vaut EMPLOYEE.

Paramètres

Nom	Emplacement	Type	Description
`X-SUBTENANT-ID`*	en-tête	`string`	Sub-tenant identifier

Réponses

Code	Description	Contenu
`200`	OK	`/` · DocumentCategory[]

POST/external/candidate/v1/{id}/documentsJoindre un document à un candidat

Envoi multipart/form-data, champ file. Un document de catégorie CV est analysé comme un CV chargé directement dans SAM ULTIMATE, lorsque l'analyse de CV est activée.

Paramètres

Nom	Emplacement	Type	Description
`id`*	chemin	`string`	ID of the candidate
`category`*	query	`string`	Code of a category from /document-categories
`X-SUBTENANT-ID`*	en-tête	`string`	Sub-tenant identifier

Corps de la requête`multipart/form-data`

Champ	Type	Contraintes	Description
`file`*	`string (binary)`	fichier	File to upload

Réponses

Code	Description	Contenu
`200`	OK	`/` · Document

Un candidat est enregistré dans SAM ULTIMATE comme une fiche employé : les catégories renvoyées par /document-categories sont donc celles des documents d'employé (parentType = EMPLOYEE).

Modèles de données

Les longueurs indiquées sont des maximums. Les champs marqués d'un astérisque sont obligatoires.

CandidateobjectChamps obligatoires : firstName, gender, lastName, occupationIds

Champ	Type	Contraintes	Description
`id`	`string`		Identifiant attribué par SAM ULTIMATE (renvoyé à la création, à ne pas fournir).
`agenceId`	`string`		Agence de rattachement (identifiant communiqué par Interiware).
`advisorId`	`string`		Conseiller de rattachement (identifiant communiqué par Interiware).
`gender`*	`enum`		Civilité. `FEMALE` – Femme `MALE` – Homme
`firstName`*	`string`	60 caractères max.	Prénom.
`lastName`*	`string`	60 caractères max.	Nom.
`address`	`Address`		Adresse postale.
`phone`	`string`	20 caractères max.	Téléphone fixe.
`mobile`	`string`	20 caractères max.	Téléphone mobile.
`email`	`string`	50 caractères max., format : ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$\|^\s*$	Adresse e-mail valide.
`avsNumber`	`string`	16 caractères max.	Numéro AVS, format 756.XXXX.XXXX.XX.
`nationality`	`string`	3 caractères max.	Nationalité, code pays ISO (ex. CH).
`birthDate`	`string (date)`	date (AAAA-MM-JJ)	Date de naissance.
`birthPlace`	`string`	30 caractères max.	Lieu de naissance.
`workPermitType`	`enum`		Type de permis de travail. `SHORT_TERM_L` – Permis L – courte durée `ANNUAL_B` – Permis B – annuel `SETTLED_C` – Permis C – établissement `CROSS_BORDER_G` – Permis G – frontalier `ASYLUM_SEEKER_N` – Permis N – requérant d'asile `NEED_FOR_PROTECTION_S` – Permis S – personne à protéger `NOTIFICATION_PROCEDURE_FOR_SHORTTERM_WORK_90_DAYS` – Procédure d'annonce – 90 jours `NOTIFICATION_PROCEDURE_FOR_SHORTTERM_WORK_120_DAYS` – Procédure d'annonce – 120 jours `PROVISIONALLY_ADMITTED_FOREIGNERS_F` – Permis F – admission provisoire `RESIDENT_FOREIGN_NATIONAL_WITH_GAINFUL_EMPLOYMENT_CI` – Permis Ci – activité lucrative `OTHERS_NOT_SWISS` – Autres (non suisses)
`partnerNationality`	`string`	3 caractères max.	Nationalité du conjoint, code pays ISO.
`partnerWorksInCH`	`boolean`		Le conjoint travaille en Suisse.
`numberOfChildren`	`integer (int32)`	entier	Nombre d'enfants.
`primaryMotherTongue`	`string`		Langue maternelle principale (code langue communiqué par Interiware).
`secondaryMotherTongue`	`string`		Seconde langue maternelle (même référentiel).
`ownsCar`	`boolean`		Possède une voiture.
`ownsMotorbike`	`boolean`		Possède une moto.
`ownsBicycle`	`boolean`		Possède un vélo.
`hasCarLicense`	`boolean`		Permis voiture.
`hasMotorbikeLicense`	`boolean`		Permis moto.
`hasHeavyVehicleLicense`	`boolean`		Permis poids lourd.
`hasTrailerLicense`	`boolean`		Permis remorque.
`hasConstructionMachineLicense`	`boolean`		Permis machines de chantier.
`comment`	`string`		Commentaire libre.
`evaluationComment`	`string`		Commentaire d'évaluation.
`webimpnote`	`string`		Note d'import.
`occupationIds`*	`string[]`	au moins 1 élément	Identifiants de professions issus de /occupations.

AddressobjectAucun champ obligatoire

Champ	Type	Contraintes	Description
`line1`	`string`	50 caractères max.	Ligne d'adresse 1.
`line2`	`string`	50 caractères max.	Ligne d'adresse 2.
`line3`	`string`	50 caractères max.	Ligne d'adresse 3.
`postalCode`	`string`	8 caractères max.	Code postal (NPA).
`city`	`string`	30 caractères max.	Localité.
`country`	`string`	3 caractères max.	Pays, code ISO (ex. CH).

OccupationobjectAucun champ obligatoire

Champ	Type	Description
`id`	`string`	Identifiant à reporter dans occupationIds.
`nameFr`	`string`	Libellé en français.
`nameDe`	`string`	Libellé en allemand.
`active`	`boolean`	Profession active. Privilégiez les professions actives.
`suvaMapped`	`boolean`	Profession rattachée à la nomenclature SUVA.

DocumentCategoryobjectAucun champ obligatoire

Champ	Type	Description
`code`	`string`	Code à passer dans le paramètre category de l'envoi.
`parentType`	`enum`	Type d'entité concernée. Pour un candidat : EMPLOYEE. `EMPLOYEE` – Employé (candidat) `MISSION` `SALARIED_EMPLOYEE` `CLIENT` `DEBTOR` `BOOKING` `PERMANENT_ASSIGNMENT` `TEMPORARY_ASSIGNMENT` `CCT` `BANK_TRANSFER_ORDER` `WORK_REPORT`
`description`	`string`	Libellé de la catégorie.

DocumentobjectAucun champ obligatoire

Champ	Type	Contraintes	Description
`id`	`string`		Identifiant du document.
`lastModifiedBy`	`string`		Auteur de la dernière modification.
`dateTrack`	`string (date-time)`	date et heure (ISO 8601)	Date de dernière modification.
`deleted`	`boolean`		Document supprimé.
`entityType`	`enum`		Entité à laquelle le document est rattaché (EMPLOYEE pour un candidat). `EMPLOYEE` – Employé (candidat) `MISSION` `SALARIED_EMPLOYEE` `CLIENT` `DEBTOR` `BOOKING` `PERMANENT_ASSIGNMENT` `TEMPORARY_ASSIGNMENT` `CCT` `BANK_TRANSFER_ORDER` `WORK_REPORT`
`entityId`	`string`		Identifiant de cette entité (id du candidat).
`categoryCode`	`string`		Catégorie du document.
`description`	`string`		Description.
`fileName`	`string`		Nom du fichier.
`contentType`	`string`		Type MIME du fichier.
`documentId`	`string`		Identifiant du fichier stocké.

Exemple de création de candidat

Requête minimale réaliste : identité, coordonnées, adresse et au moins une profession.

POST /external/candidate/v1
Authorization: Bearer {access_token}
X-SUBTENANT-ID: {identifiant de la gestion}
Content-Type: application/json

{
  "gender": "FEMALE",
  "firstName": "Anna",
  "lastName": "Exemple",
  "email": "anna.exemple@example.com",
  "mobile": "+41 79 000 00 00",
  "birthDate": "1990-05-14",
  "nationality": "CH",
  "address": {
    "line1": "Rue de l'Exemple 1",
    "postalCode": "1000",
    "city": "Lausanne",
    "country": "CH"
  },
  "occupationIds": ["{id issu de /occupations}"]
}

Documentation interactive et support

L'interface Swagger de l'API Candidats reprend l'ensemble de ces informations et permet de tester les appels. Son adresse vous est communiquée avec vos identifiants.

Pour toute question technique, écrivez à support@interiware.com.

Télécharger la spécification OpenAPI (JSON)

API d'import de candidats

Objet

Cas d'utilisation métiers

Authentification

A. Obtenir un jeton d'accès

B. En-têtes à envoyer à chaque appel

Parcours d'intégration

Endpoints

Paramètres

Réponses

Paramètres

Réponses

Paramètres

Corps de la requête*application/json

Réponses

Paramètres

Réponses

Paramètres

Corps de la requêtemultipart/form-data

Réponses

Modèles de données

Exemple de création de candidat

Documentation interactive et support

Corps de la requête*`application/json`

Corps de la requête`multipart/form-data`