By the end of this guide, you'll be able to programmatically add new users to any Formaloo portal's user directory — without touching the dashboard manually. You'll send a single API request per user and have them appear as fully active portal users, ready to log in via OTP. This is the recommended approach for any backend or automated onboarding workflow.
When to use this
You onboard new portal users regularly and want to automate the process
You're building a backend integration that provisions users from your own system
You've already set up a portal with a user directory and need to add users at scale
You want to pre-authorize specific users for portal access without open sign-up
💡 New to portals or user directories? Start here first:
How to manually add users or import users to your portal's user directory
How it works
In Formaloo, every portal's user directory is a form under the hood. Each user in the directory is simply a form submission — a row. This means you can add users programmatically using the same form rows API you'd use to submit any other form.
You don't need a special endpoint. You POST a new row to your user directory form's slug, and a new portal user is created.
Step 1: Get your API credentials
Sign in to your Formaloo dashboard
Click your profile icon in the top-right corner
Jump to API Keys
Copy both your API Key and API Secret — you'll need both
⚠️ Keep your API Secret private. It is used to generate short-lived authorization tokens and should never be exposed client-side.
Step 2: Find your user directory form slug
Your user directory is a form with its own slug. To find it:
Go to your portal's settings and open the User directory section
The form slug is visible in the URL when you open the user directory form, or you can retrieve it via:
GET https://api.formaloo.me/v3.0/forms/ Headers: x-api-key: {your API key} Authorization: JWT {your authorization token}
Look for the form titled after your user directory. Copy its slug value — you'll use it in Step 4.
Step 3: Get your field slugs
Each field in the user directory form has its own slug. To see all available fields and their slugs, call:
GET https://api.formaloo.me/v3.0/forms/{userDirectoryFormSlug}/ Headers: x-api-key: {your API key} Authorization: JWT {your authorization token}
The response includes a fields object. Each field entry shows its slug, type, and title. Look for:
The email field (type:
email) — requiredThe full name field (type:
short_text) — recommendedThe roles field (type:
multiple_select) — optional, if your portal uses roles
Copy the slugs for the fields you want to populate.
Step 4: Get an authorization token
The Formaloo API uses a two-step auth flow. First, exchange your API Secret for a short-lived JWT token:
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
Example response:
json
{ "authorization_token": "eyJhbGciOi..." }Use this token in the Authorization: JWT {token} header for all subsequent requests. Tokens expire, so request a new one when needed.
Step 5: Create a new portal user
Now POST a new row to your user directory form. Each row you create becomes a new portal user:
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" }
Example:
json
{ "QIjq1tbj": "[email protected]", "DGyU26ZF": "Jane Smith" }A successful request returns a 201 status and the newly created row, including an auto-generated username for the user.
ℹ️ Full API reference: POST /forms/{slug}/rows/
Step 6 (optional): Assign a role
If your portal uses Roles (e.g., Member, Admin, Viewer), include the roles field slug in your request body. Roles use a multiple_select field, so pass the value as an array of choice slugs:
{ "{emailFieldSlug}": "[email protected]", "{nameFieldSlug}": "Jane Smith", "{rolesFieldSlug}": ["{desiredChoiceSlug}"] }
To find the choice slugs for your roles field, look inside the choice_items array in the field data returned in Step 3.
Final result
Once set up, you can add new portal users with a single API call per user — no manual dashboard work required. New users appear immediately in your portal's user directory with is_active set to true, and they can log in via OTP as soon as they visit your portal. This approach scales to any volume and integrates cleanly with your existing onboarding systems or CRM.
Start faster
💬 Get help from our concierge team Our team will help you set this up for your specific onboarding workflow.
📅 Book a demo for Business/Enterprise setup See how teams use Formaloo at scale with advanced permissions and API integrations.