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 — 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

Réponses

• 201 — candidat créé ou rattaché : { "personId", "processId", "created", "deduped": false }
• 200 + "deduped": true — un envoi antérieur avec le même externalId existait : aucune création, on renvoie les identifiants existants.
• created: false — profil existant réutilisé (dédup LinkedIn).

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

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.

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