Vue d'ensemble de l'API
Introduction à l'API publique de Diamond Careers : périmètre, base URL, conventions REST et premiers pas pour connecter votre établissement à un ATS, un SIRH ou un outil RH externe.
L'API Diamond Careers permet à un établissement (maison partenaire) ou à un groupe de connecter sa plateforme Diamond à un système externe : ATS, SIRH, jobboards, outils RH internes. Elle expose strictement les ressources que vous gérez pour votre compte — pas la plateforme en interne.
Périmètre
Avec un jeton API valide, vous pouvez :
- consulter et mettre à jour la fiche de votre établissement,
- créer, modifier, supprimer vos offres d'emploi,
- consulter les candidatures reçues sur vos offres et faire évoluer leur statut,
- soumettre et gérer vos articles éditoriaux,
- gérer les membres gestionnaires de votre établissement,
- téléverser des médias (visuels d'offres, images d'articles) ou récupérer des fichiers privés (CV reçus),
- consulter les listes de référence (taxonomies) utilisées dans vos offres.
Pour les comptes groupe, s'ajoutent des vues agrégées sur les maisons rattachées (offres, candidatures, statistiques).
L'API ne donne pas accès :
- aux fiches d'autres établissements ou de talents non liés à vos offres,
- au catalogue public des Job Datings,
- aux outils internes Diamond (validation, modération, communication globale, etc.),
- aux données d'utilisateurs hors de votre périmètre.
Base URL
Toutes les routes documentées sont relatives à :
https://api.diamondcareers.fr/diamond/v1Exemple : l'endpoint /auth/me correspond à https://api.diamondcareers.fr/diamond/v1/auth/me.
Le sous-domaine api.diamondcareers.fr réécrit transparente vers https://diamondcareers.fr/wp-json/diamond/v1. Les deux formes sont équivalentes : utilisez le sous-domaine api. pour vos intégrations, plus stable et bloqué côté wp-admin.
Le seul endpoint hors namespace /diamond/v1 est l'émission du jeton d'authentification : POST /wp-json/jwt-auth/v1/token. Voir Authentification.
Format des requêtes et réponses
L'API parle JSON :
- en-tête
Content-Type: application/jsonsur les requêtes avec corps, - en-tête
Accept: application/jsonpour les réponses, - corps des
POST/PATCH/PUTen JSON valide.
Pour le téléversement de fichiers (CV, médias), utilisez multipart/form-data sur les endpoints /upload et /secure-upload.
Méthodes HTTP
Conventions REST classiques :
- GET — lire,
- POST — créer ou déclencher une action,
- PATCH — mettre à jour partiellement (recommandé),
- PUT — remplacer (rare),
- DELETE — supprimer.
Pagination, filtres, tri
Toutes les listes supportent :
per_page: nombre d'éléments par page (défaut 10, maximum 100),page: numéro de page (1 par défaut),orderby: champ de tri (date,modified,title,id),order:ascoudesc,s: recherche plein-texte,status: filtre par statut (selon la ressource).
Voir Pagination, filtres et tri.
Codes de réponse
| Code | Sens |
|---|---|
| 200 OK | Succès |
| 201 Created | Ressource créée |
| 204 No Content | Succès sans corps (souvent après DELETE) |
| 400 Bad Request | Requête mal formée |
| 401 Unauthorized | Jeton manquant ou invalide |
| 403 Forbidden | Hors de votre périmètre |
| 404 Not Found | Ressource introuvable |
| 409 Conflict | Conflit métier |
| 422 Unprocessable Entity | Données invalides |
| 429 Too Many Requests | Limite de débit atteinte |
| 5xx | Erreur serveur — réessayez avec un backoff |
Les corps d'erreur sont décrits dans Codes d'erreur.
Premiers pas
Contactez tech@diamondcareers.fr en précisant votre cas d'usage. Un compte technique est créé sur votre établissement (ou votre groupe) avec les permissions adaptées.
Appelez POST https://diamondcareers.fr/wp-json/jwt-auth/v1/token avec { username, password }. Voir Authentification.
Appelez GET /diamond/v1/auth/me (avec Authorization: Bearer <token>) pour confirmer que votre jeton fonctionne et voir le profil renvoyé (votre rôle, votre maison ou groupe rattaché).
Consultez la spécification OpenAPI ou les exemples cURL.
Spécification OpenAPI
L'intégralité de l'API est décrite dans une spécification OpenAPI 3.1 : /openapi.yaml. Vous pouvez l'utiliser pour :
- générer un client typé (TypeScript, Python, Go, Java, PHP…),
- l'importer dans Postman, Insomnia, Bruno, etc.,
- l'intégrer dans votre documentation interne.
Limites d'usage
L'API Diamond Careers est conçue pour des intégrations métier sérieuses. Elle n'est pas destinée à :
- du scraping de profils talents,
- des envois massifs de candidatures automatisées,
- du benchmark de salaires sans agrément.
Toute utilisation détectée comme abusive entraîne la suspension du jeton et, selon la gravité, la résiliation du contrat.
Support
Pour toute question d'intégration : tech@diamondcareers.fr. Précisez votre identifiant client, l'endpoint concerné, la requête + la réponse exactes (corps + en-têtes), l'horodatage du problème (UTC ou heure de Paris). Réponse sous 24 heures ouvrées.