Lisez vos recrues et vos missions depuis vos propres outils. Une clé, deux points d'entrée, et des webhooks qui vous préviennent quand quelque chose bouge.
https://app.sowellapp.fr/api ; si votre espace a son propre sous-domaine, utilisez-le.valid confirme que tout est en place.curl -H "Authorization: Bearer VOTRE_CLE" \
https://app.sowellapp.fr/api/v1/verifyChaque appel porte l'en-tête Authorization: Bearer <clé>. La clé appartient à un espace et ne donne accès qu'à lui : elle ne peut pas lire les données d'un autre client, même en visant une autre adresse.
Les listes renvoient au plus 50 éléments par défaut et 200 au maximum (limit). Quand une suite existe, la réponse porte un next_cursor : passez-le en cursor pour la page suivante. Quand il vaut null, vous avez tout lu.
# première page
curl -H "Authorization: Bearer VOTRE_CLE" \
"https://app.sowellapp.fr/api/v1/candidates?limit=50"
# page suivante, avec le curseur renvoyé
curl -H "Authorization: Bearer VOTRE_CLE" \
"https://app.sowellapp.fr/api/v1/candidates?limit=50&cursor=665f1c2a9b1e4a0012ab34cd"Le curseur est préféré au décalage parce qu'un décalage devient instable dès qu'une donnée est créée pendant votre parcours : des éléments seraient sautés ou lus deux fois.
Toutes les dates sortent au format ISO 8601. Une date absente vaut null, jamais une chaîne vide.
| Code | Sens | Cas |
|---|---|---|
400 | Requête invalide | Curseur mal formé, ou paramètre hors bornes. |
401 | Non authentifié | En-tête absent, clé inconnue ou révoquée. |
404 | Module absent | L'espace n'a pas le module concerné par la route. |
429 | Trop de requêtes | Limite de débit atteinte. Réessayez après la fenêtre. |
L'API est en lecture seule. Aucune clé ne permet d'écrire, de modifier ni de supprimer quoi que ce soit.
/api/v1/candidatesLes personnes suivies dans votre espace, hors archivées.
| Paramètre | Défaut | Rôle |
|---|---|---|
limit | 50 | Nombre d'éléments, 200 au maximum. |
cursor | — | Curseur renvoyé par l'appel précédent. |
| Champ | Description |
|---|---|
id | Identifiant Sowell |
nom | Nom complet |
email | Adresse e-mail |
poste | Intitulé du poste |
service | Service de rattachement |
site | Site ou établissement |
statut | Statut courant |
date_arrivee | Date d'arrivée, au format ISO |
source | Outil d'origine (ATS, outil de gestion, ou « manual ») |
identites | Identifiants de la personne dans chaque outil branché |
/api/v1/missionsLes missions de votre espace. Réservée aux espaces dotés du module Missions.
| Paramètre | Défaut | Rôle |
|---|---|---|
limit | 50 | Nombre d'éléments, 200 au maximum. |
cursor | — | Curseur renvoyé par l'appel précédent. |
| Champ | Description |
|---|---|
id | Identifiant Sowell |
candidate_id | Identifiant de la personne placée |
client_final | Client chez qui la personne est placée |
poste | Intitulé du poste |
date_debut | Début de mission, au format ISO |
date_fin | Fin de mission, au format ISO, vide si indéterminée |
statut | Statut courant |
manager_client_nom | Interlocuteur côté client |
business_manager | Responsable commercial du placement |
source | Outil d'origine (ATS, outil de gestion, ou « manual ») |
external_id | Identifiant de la mission dans l'outil d'origine |
/api/v1/verifyVérifie qu'une clé est valide. À appeler une fois pour contrôler votre configuration.
Plutôt que d'appeler l'API en boucle, déclarez une adresse dans vos Réglages et Sowell vous y envoie les événements en temps réel. C'est ce qui rend Zapier, Make ou n8n réellement utilisables.
| Événement | Nom | Déclenchement |
|---|---|---|
recrue.creee | Recrue créée | Une recrue vient d'être ajoutée (manuellement ou via la synchronisation ATS). |
recrue.mise_a_jour | Recrue mise à jour | Les informations d'une recrue ont changé (statut, poste, date d'arrivée…). |
etape.completee | Étape complétée | Une étape du parcours d'intégration vient d'être cochée. |
retard.detecte | Retard détecté | Une étape d'intégration a dépassé son échéance. |
satisfaction.recue | Satisfaction reçue | Une recrue vient de répondre à l'enquête de satisfaction. |
ping | Test (ping) | Événement de test, envoyé depuis la console pour vérifier votre endpoint. |
Chaque envoi porte un en-tête de signature au schéma t=<horodatage>,v1=<HMAC-SHA256>, calculé sur l'horodatage et le corps avec le secret de votre webhook. Vérifiez-la avant de traiter un message : c'est ce qui prouve qu'il vient bien de Sowell, et l'horodatage protège du rejeu.
Une livraison en échec est retentée 4 fois, avec des attentes croissantes de 0, 2, 10, 30 secondes, puis abandonnée. Chaque tentative est journalisée, les 200 dernières livraisons de chaque webhook restent consultables, et vous pouvez rejouer une livraison depuis les Réglages. Le délai d'attente d'une requête est de 8 secondes.
| Route | Requêtes | Fenêtre |
|---|---|---|
/api/v1/candidates | 120 | 60 s |
/api/v1/missions | 120 | 60 s |
Au-delà, l'API répond 429. Ces limites protègent votre espace : une clé qui fuiterait ne permettrait pas d'en aspirer le contenu en quelques secondes.