À la fin de ce guide, vous saurez ajouter par programmation de nouveaux utilisateurs à l’annuaire de n’importe quel portail Formaloo, sans passer manuellement par le tableau de bord. Vous enverrez une seule requête API par utilisateur, et chacun apparaîtra comme un utilisateur actif du portail, prêt à se connecter par OTP. C’est l’approche recommandée pour tout flux d’intégration backend ou automatisé.
Quand l’utiliser
Vous intégrez régulièrement de nouveaux utilisateurs à votre portail et souhaitez automatiser le processus
Vous développez une intégration backend qui provisionne des utilisateurs depuis votre propre système
Vous avez déjà configuré un portail avec un annuaire d’utilisateurs et devez ajouter des utilisateurs à grande échelle
Vous souhaitez pré-autoriser certains utilisateurs à accéder au portail sans inscription ouverte
💡 Vous découvrez les portails ou les annuaires d’utilisateurs ? Commencez par ici :
Fonctionnement
Dans Formaloo, l’annuaire d’utilisateurs de chaque portail est en réalité un formulaire. Chaque utilisateur de l’annuaire correspond simplement à une soumission de formulaire, c’est-à-dire une ligne. Vous pouvez donc ajouter des utilisateurs par programmation avec la même API de lignes de formulaire que celle utilisée pour soumettre n’importe quel autre formulaire.
Aucun endpoint spécifique n’est nécessaire. Vous envoyez (POST) une nouvelle ligne vers le slug du formulaire de votre annuaire, et un nouvel utilisateur du portail est créé.
Étape 1 : obtenez vos identifiants API
Connectez-vous à votre tableau de bord Formaloo
Cliquez sur votre icône de profil en haut à droite
Accédez à API Keys
Copiez votre API Key et votre API Secret : vous aurez besoin des deux
⚠️ Gardez votre API Secret confidentiel. Il sert à générer des jetons d’autorisation de courte durée et ne doit jamais être exposé côté client.
Étape 2 : trouvez le slug du formulaire de votre annuaire
Votre annuaire d’utilisateurs est un formulaire doté de son propre slug. Pour le trouver :
Accédez aux paramètres de votre portail et ouvrez la section User directory
Le slug du formulaire est visible dans l’URL lorsque vous ouvrez le formulaire de l’annuaire, ou vous pouvez le récupérer via :
GET https://api.formaloo.me/v3.0/forms/ Headers: x-api-key: {your API key} Authorization: JWT {your authorization token}
Recherchez le formulaire portant le nom de votre annuaire d’utilisateurs. Copiez sa valeur slug : vous l’utiliserez à l’étape 4.
Étape 3 : récupérez les slugs de vos champs
Chaque champ du formulaire de l’annuaire possède son propre slug. Pour voir tous les champs disponibles et leurs slugs, appelez :
GET https://api.formaloo.me/v3.0/forms/{userDirectoryFormSlug}/ Headers: x-api-key: {your API key} Authorization: JWT {your authorization token}
La réponse contient un objet fields. Chaque champ indique son slug, son type et son title. Recherchez :
Le champ e-mail (type :
email) : obligatoireLe champ nom complet (type :
short_text) : recommandéLe champ rôles (type :
multiple_select) : facultatif, si votre portail utilise des rôles
Copiez les slugs des champs que vous souhaitez renseigner.
Étape 4 : obtenez un jeton d’autorisation
L’API Formaloo utilise une authentification en deux étapes. Commencez par échanger votre API Secret contre un jeton JWT de courte durée :
POST https://api.formaloo.me/v3.0/oauth2/authorization-token/ Headers: x-api-key: {your API key} Authorization: Basic {your API secret} Body (form-data): grant_type=client_credentials
Exemple de réponse :
json
{ "authorization_token": "eyJhbGciOi..." }Utilisez ce jeton dans l’en-tête Authorization: JWT {token} pour toutes les requêtes suivantes. Les jetons expirent : demandez-en un nouveau si nécessaire.
Étape 5 : créez un nouvel utilisateur du portail
Envoyez maintenant (POST) une nouvelle ligne vers le formulaire de votre annuaire. Chaque ligne créée devient un nouvel utilisateur du portail :
POST https://api.formaloo.me/v3.0/forms/{userDirectoryFormSlug}/rows/ Headers: x-api-key: {your API key} Authorization: JWT {your authorization token} Content-Type: application/json Body: { "{emailFieldSlug}": "[email protected]", "{nameFieldSlug}": "Jane Smith" }
Exemple :
json
{ "QIjq1tbj": "[email protected]", "DGyU26ZF": "Jane Smith" }Une requête réussie renvoie un statut 201 et la ligne nouvellement créée, avec un username généré automatiquement pour l’utilisateur.
ℹ️ Référence complète de l’API : POST /forms/{slug}/rows/
Étape 6 (facultative) : attribuez un rôle
Si votre portail utilise des rôles (par exemple Member, Admin, Viewer), incluez le slug du champ des rôles dans le corps de votre requête. Les rôles utilisent un champ multiple_select : transmettez donc la valeur sous forme de tableau de slugs de choix :
{ "{emailFieldSlug}": "[email protected]", "{nameFieldSlug}": "Jane Smith", "{rolesFieldSlug}": ["{desiredChoiceSlug}"] }
Pour trouver les slugs de choix de votre champ de rôles, consultez le tableau choice_items dans les données du champ renvoyées à l’étape 3.
Résultat final
Une fois la configuration terminée, vous pouvez ajouter de nouveaux utilisateurs au portail avec un seul appel API par utilisateur, sans aucune manipulation manuelle dans le tableau de bord. Les nouveaux utilisateurs apparaissent immédiatement dans l’annuaire de votre portail avec is_active défini sur true, et peuvent se connecter par OTP dès qu’ils accèdent à votre portail. Cette approche s’adapte à tous les volumes et s’intègre facilement à vos systèmes d’intégration existants ou à votre CRM.
Démarrez plus vite
💬 Faites-vous aider par notre équipe concierge Notre équipe vous aidera à mettre cela en place pour votre propre flux d’intégration.
📅 Réservez une démo pour une configuration Business/Enterprise Découvrez comment les équipes utilisent Formaloo à grande échelle avec des autorisations avancées et des intégrations API.