Adding a handful of people in Wizard Application takes a few minutes. Adding fifty, or a few hundred, by hand is a day of copying names and emails out of another system, with a mistake waiting somewhere in the middle.
The users API lets you bring your whole team across in a few requests. You send the people you already have in your HR system, payroll or old software, Wizard Application creates their accounts, places them in the right roles, departments and reporting lines, and invites each of them to sign in.
This guide covers what to prepare, how to create an API key that can add users, how the import works, how passwords and invitations are handled and what to check afterwards.
Before you start
The API is available on the Professional and Enterprise plans, and API keys are created by an administrator. Before you import, set up the things your users will be placed into, so the import can find them by name.
- Roles. Decide which roles people need and what each can see and do. Our guide to roles and permissions walks through how to plan them.
- Departments. If you use departments, create them first. When departments are switched on, every person needs one.
- Managers. Everyone except administrators reports to a manager. Make sure each manager is in your list, or already has an account.
- Payment details. Each person you add is a paid seat, so the workspace needs a payment method on file before a key can add users.
Prepare your team list
Export your people from your current system and tidy the list before you send it. For each person you need an email address, a first name and a last name. You can also include a job title, a phone number, their role, their department and their manager.
Roles and departments can be given by name, exactly as they appear in Wizard Application, and managers by their email address. You do not need to look up any IDs first.
Put managers before the people who report to them. The import works through your list in order, so a manager added earlier in the same request can be named by everyone below them. Starting with your most senior people and working down is the simplest way to get this right.
Create a key that can add users
In Wizard Application, go to Settings, then API Keys, and create a new key. Give it a name that says what it is for, such as Team import, and choose its permissions.
- Users - Read lets the key list your team and look people up.
- Users - Create and update lets it add people and change their details.
Because every person the key adds is a paid seat, ticking Users - Create and update asks you to accept the per-seat charge for the users it adds. This is the same charge as adding someone in the app, and it is recorded against the key. A key without it can read your team but cannot add anyone.
Copy the key when it is shown and store it somewhere safe. It is only displayed once. When your import is finished you can switch the key off, or set an expiry date when you create it.
Run the import
Send your list to the import endpoint, up to 100 people per request. For a larger team, split the list into batches and send them in order.
curl -X POST "https://your-workspace.wizardapp.io/api/v1/users/import" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"users": [
{
"email": "alex@example.com",
"first_name": "Alex",
"last_name": "Morgan",
"role": "Administrator"
},
{
"email": "sam@example.com",
"first_name": "Sam",
"last_name": "Lee",
"job_title": "Operations Coordinator",
"role": "Team Member",
"department": "Operations",
"manager_email": "alex@example.com"
}
]
}'The response lists every person with one of three results.
- Created. The account exists and the person has been invited.
- Skipped. Someone with that email address is already in your workspace, so nothing changed.
- Failed. Something needs fixing, such as a role name that does not exist or a missing manager. The response says what.
Each person stands on their own, so one failure does not stop the rest. Fix the rows that failed and send the same list again. People already added are skipped, so running an import twice never creates duplicates.
The import respects the same rules as adding people in the app, including your plan's limit on team members and any email domains you have restricted sign ups to.
Passwords and invitations
The API never sets or sees anyone's password. Each person you add receives their own invitation email with a link to choose a password, which has to meet your workspace's password rules. Until they accept, they show as invited and cannot sign in. Once they accept, they are active.
By default the invitations go out as soon as each person is added. If you would rather load everyone first and invite them later, for example on your launch day, set "send_invitation": false for each person. When you are ready, send each invitation with POST /api/v1/users/{id}/invitation. The same request resends an invitation that someone has lost, and the link in it stays the same, so an earlier email still works.
Tell your team the invitation is coming. A short message explaining what Wizard Application is and why they will receive an email makes it far less likely to be ignored or mistaken for spam.
Check the result
- Compare the totals. The summary at the end of each response counts created, skipped and failed people. Make sure the numbers add up to your list.
- Look at the reporting lines. Open the team in Wizard Application and check a few managers have the right people under them.
- Follow up on invitations. List users with the status invited to see who has not signed in yet, and resend their invitation if needed.
- Tidy up the key. Once the import is done, switch off the key or let it expire, unless you plan to keep your HR system in step with it.
Keeping your team in step
The users API is not only for a one off move. If people join in your HR system first, the same key can add them to Wizard Application as they start, and update their job title, role, department or manager when those change. Email addresses can only be changed inside Wizard Application, and people cannot be removed through the API, so leavers are always taken out by an administrator.
Frequently asked questions
Do imported users get an email?
Yes. Each person gets their own invitation email to choose a password, unless you hold it back with send_invitation set to false and send it later.
Can I set passwords for my team during the import?
No. Passwords are never sent through the API. Each person chooses their own from the invitation link, so nobody else ever knows it.
Is each imported user charged?
Yes. Every person is a paid seat, charged in the same way as adding someone in the app. That is why a key has to accept the per-seat charge before it can add users.
What happens if I run the same import twice?
Nothing is duplicated. Anyone whose email address is already in your workspace is reported as skipped.
How many people can I import at once?
Up to 100 per request. For a bigger team, send your list in batches, managers first.
Where is the full API reference?
Every field, response and error is in the API documentation, alongside our official SDKs.
Once your team is in, our employee onboarding checklist covers what to set up for each person in their first weeks.
