API partenaire

L'API partenaire permet à un outil tiers d'alimenter les projets de recrutement d'un client Marvin : lister ses projets ouverts et les étapes de son process, puis y créer des candidats — avec leur CV, en un seul appel idempotent.

Base URL : https://api.marvins.ai
Format : JSON (Content-Type: application/json)
Authentification : header X-Marvin-Public-Key (voir Authentification)

Lister les projets

GET /v1/partner/projects

Renvoie les projets de recrutement ouverts du client et les étapes du process — à présenter dans vos sélecteurs « projet » et « étape ».

Réponse 200

{
  "stages": [
    { "key": "sourced", "label": "Sourcé" },
    { "key": "hired", "label": "Embauché" }
  ],
  "projects": [
    { "projectId": "8f3c…", "title": "Senior Frontend Engineer", "companyName": "Acme Corp" }
  ]
}

curl https://api.marvins.ai/v1/partner/projects \
  -H "X-Marvin-Public-Key: pk_live_…"

Créer un candidat

POST /v1/partner/candidates

Crée (ou réutilise) le candidat et le rattache au projet ciblé à l'étape choisie.

Corps de la requête — application/json, ou multipart/form-data pour joindre le CV.

Champ	Type	Requis	Description
`firstName`	string	oui	Prénom
`lastName`	string	oui	Nom
`email`	string	non *	Email (si disponible)
`phone`	string	non	Téléphone (format E.164)
`linkedinUrl`	string	non *	URL du profil LinkedIn — clé de déduplication
`projectId`	uuid	oui	Projet cible (cf. `GET /v1/partner/projects`)
`stage`	string	non	Étape du process ; défaut = 1ʳᵉ étape du client
`externalId`	string	non	Votre identifiant interne — clé d'idempotence des rejeux
`cv`	file	non	CV du candidat (PDF, Word ou image, 10 Mo max) — multipart

email OU linkedinUrl est requis. Un profil LinkedIn sans email est accepté : la déduplication se fait alors sur le profil LinkedIn.

Joindre le CV

Envoyez la requête en multipart/form-data avec le fichier dans le champ cv (le nom resume est également accepté). Le CV est rattaché aux documents de la fiche candidat et remplit automatiquement le profil (expériences, compétences, coordonnées) — sans jamais écraser une information déjà saisie par le recruteur.

Un fichier envoyé sous un autre nom de champ est refusé en 400 plutôt qu'ignoré : un CV perdu en silence est invisible des deux côtés.

curl -X POST https://api.marvins.ai/v1/partner/candidates \
  -H "X-Marvin-Public-Key: pk_live_…" \
  -F "firstName=Linda" \
  -F "lastName=Kedin" \
  -F "linkedinUrl=https://www.linkedin.com/in/linda-kedin" \
  -F "projectId=8f3c…" \
  -F "externalId=votre-id-interne-42" \
  -F "cv=@/chemin/vers/cv.pdf"

Réponses

201 — candidat créé ou rattaché : { "personId", "processId", "created", "deduped": false, "documentId" }
200 + "deduped": true — un envoi antérieur avec le même externalId existait : aucune création, on renvoie les identifiants existants. Un CV joint à ce rejeu est rattaché s'il manquait (vous pouvez donc pousser le profil d'abord, le CV ensuite).
created: false — profil existant réutilisé (dédup LinkedIn). Le CV est tout de même rattaché à la fiche.
documentId — identifiant du CV rattaché à la fiche, null si aucun fichier n'a été envoyé.

Un même CV n'est jamais versé deux fois sur une fiche. Re-synchroniser un profil avec le même fichier renvoie le documentId existant, sans créer de doublon. Un fichier différent est ajouté normalement.

curl -X POST https://api.marvins.ai/v1/partner/candidates \
  -H "X-Marvin-Public-Key: pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Linda",
    "lastName": "Kedin",
    "linkedinUrl": "https://www.linkedin.com/in/linda-kedin",
    "projectId": "8f3c…",
    "stage": "sourced",
    "externalId": "votre-id-interne-42"
  }'

Codes d'erreur

Statut	Cas
`400`	Corps invalide (ni email ni linkedinUrl, étape inconnue)
`400`	Fichier dans un champ inattendu, ou format non supporté
`401`	Clé absente, malformée, inconnue ou révoquée
`403`	Scope requis manquant
`404`	`projectId` inexistant pour ce client
`413`	CV au-delà de 10 Mo
`429`	Débit dépassé

Bonnes pratiques

Envoyez toujours un externalId stable (votre identifiant interne) pour que les rejeux ne créent pas de doublon.
Récupérez projectId et stage via GET /v1/partner/projects plutôt que de les coder en dur — ils sont propres à chaque client.
Joignez le CV quand vous l'avez : sans lui, le recruteur doit retourner le chercher dans votre outil, et l'intérêt de la synchronisation disparaît.

Pour la liste exhaustive des champs et schémas, consultez la Référence API.