Intégration

Pools de candidats

Chaque appel à POST /v1/match/run spécifie d'où viennent les candidats à évaluer — c'est le pool. Trois modes couvrent tous les scénarios d'intégration sans forcer le partenaire à changer sa propre architecture.

pool: storedCandidats stockés

Candidats préalablement poussés via POST /v1/profiles. Karaba les stocke et les indexe en amont — le matching est immédiat.

Idéal pour : Plateformes qui délèguent entièrement leur base à Karaba

Contrainte : Nécessite un import préalable des candidats

pool: inlineCandidats inline

Candidats envoyés directement dans la requête. Aucune donnée n'est conservée — Karaba score et retourne les résultats, c'est tout.

Idéal pour : Entreprises avec contraintes RGPD, ou qui veulent garder le contrôle total de leur data

Contrainte : Le partenaire envoie ses candidats à chaque appel

pool: providerIndex partenaire

Karaba maintient un index IA léger (skills, seniority, pays) d'un partenaire enregistré. Aucune donnée sensible stockée. Sync via webhook.

Idéal pour : Partenaires stratégiques avec de gros volumes (GoAfrica, jobboards)

Contrainte : Nécessite un enregistrement + bootstrap initial

POST/v1/match/runscope: match:read

Endpoint unifié — la structure du pool détermine le comportement. La réponse est identique dans les 3 cas.

CHAMPS COMMUNS

job.titlestringRequis

job.descriptionstringOptionnel

job.skills_requiredstring[]Recommandé

job.experience_minintOptionnel

job.experience_maxintOptionnel

job.locationstringOptionnel

pool.type"stored" | "inline" | "provider"Requis

limitintDéfaut : 10, max : 200

CHAMPS SPÉCIFIQUES PAR POOL

inline.candidates[].external_idstringRequis

inline.candidates[].skillsstring[]Recommandé

inline.candidates[].experience_yearsintOptionnel

inline.candidates[].locationstringOptionnel

inline.candidates[].full_namestringOptionnel

provider.provider_idstringRequis

Réponse (identique pour les 3 pools)

{
  "match_id": "inline_a3f9c12b8e4d",
  "pool_type": "inline",
  "total_results": 2,
  "results": [
    {
      "external_id": "cand_001",
      "match_score": 91.5,
      "trust_score": null,
      "full_name": null,
      "location": "Lomé, Togo",
      "experience_years": 5,
      "skills": ["flutter", "dart", "firebase"]
    },
    {
      "external_id": "cand_003",
      "match_score": 47.0,
      "trust_score": null,
      "location": "Dakar, Sénégal",
      "experience_years": 2,
      "skills": ["flutter", "kotlin"]
    }
  ],
  "cached": false
}

pool: stored — Candidats pré-indexés

Poussez vos candidats une fois via POST /v1/profiles, puis matchez sans rienrépéter. Karaba les indexe et les maintient prêts.

curl -X POST https://platform.api.staging.karaba.africa/v1/match/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job": {
      "title": "Senior Flutter Developer",
      "skills_required": ["flutter", "firebase"],
      "experience_min": 3,
      "location": "Lomé, Togo"
    },
    "pool": { "type": "stored" },
    "limit": 10
  }'

pool: inline — Stateless, zéro stockage

Envoyez vos candidats directement dans chaque requête. Karaba score et retourne — rien n'est conservé. Idéal pour les entreprises qui gardent leurs données dans leur propre système.

Garantie de confidentialité : les données candidates envoyées en inline ne sont jamais persistées en base de données. Elles sont traitées en mémoire le temps de la requête et supprimées immédiatement après.

curl -X POST https://platform.api.staging.karaba.africa/v1/match/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job": {
      "title": "Senior Flutter Developer",
      "skills_required": ["flutter", "firebase"],
      "experience_min": 3
    },
    "pool": {
      "type": "inline",
      "candidates": [
        { "external_id": "cand_001", "skills": ["flutter", "dart", "firebase"], "experience_years": 5, "location": "Lomé, Togo" },
        { "external_id": "cand_002", "skills": ["react", "typescript"], "experience_years": 4, "location": "Accra, Ghana" },
        { "external_id": "cand_003", "skills": ["flutter", "kotlin"], "experience_years": 2, "location": "Dakar, Sénégal" }
      ]
    },
    "limit": 10
  }'

pool: provider — Index partenaire stratégique

Pour les partenaires avec de gros volumes. Karaba maintient un index IA léger — uniquement skills, seniority et pays — synchronisé via webhooks. Le matching opère sur cet index local : ultra-rapide, sans appel externe à chaque requête.

Flux d'intégration en 3 étapes :

POST /v1/providers — enregistrer le provider (une seule fois)
POST /v1/providers/{id}/sync — bootstrap initial de l'index (envoi batch)
POST /v1/providers/{id}/webhook — mises à jour temps réel (candidate.updated / deleted)

# Étape 1 : enregistrer le provider (une seule fois)
curl -X POST https://platform.api.staging.karaba.africa/v1/providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "provider_id": "goafrica", "name": "Go Africa Online" }'

# Étape 2 : indexer les candidats (bootstrap initial)
# whatsapp_number est optionnel — requis uniquement pour la diffusion
curl -X POST https://platform.api.staging.karaba.africa/v1/providers/goafrica/sync \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      { "external_id": "gao_001", "skills": ["flutter", "dart"], "seniority": "senior", "country": "TG", "whatsapp_number": "+22891000001" },
      { "external_id": "gao_002", "skills": ["react", "node"],   "seniority": "mid",    "country": "GH", "whatsapp_number": "+23300000002" }
    ]
  }'

Choisir le bon pool

Critère	stored	inline	provider
Données conservées chez Karaba	✓ Profil complet	✗ Non	◑ Index léger (skills + seniority + pays)
Numéro WhatsApp stocké	✓ Oui (whatsapp_number)	✗ Non	◑ Optionnel (whatsapp_number)
CV / liens documents	✓ cv_pdf_url / cv_csv_url	✗ Non	✗ Non
Setup requis	Import /v1/profiles	Aucun	Register + sync initial
Idéal pour	Délégation totale	Contraintes RGPD / contrôle data	Gros volumes, partenaires API
Vitesse de matching	Rapide	Dépend du nb de candidats envoyés	Ultra-rapide (index local)
Trust Score disponible	✓ Oui	Partiel (sans CV)	✗ Non
Diffusion WhatsApp	✓ Oui	✗ Non (numéros non stockés)	✓ Si whatsapp_number fourni au sync