If you or your organization do not already have a Dreamaker API key set, please contact us to request access.

Running this API will:

  1. Auto-create user accounts (identical to manual user signup process)

  2. Auto-add users to your organization (identical to inviting users manually to your organization and then users accepting that invitation)

  3. Auto-email a password reset link to each user, as well as the standard welcome to Dreamaker.io email. These emails can be optionally suppressed (using the suppressMemberEmails optional parameter).

API Request

You may call our bulk user creation API using the following parameters:

  • API Endpoint: https://api.app.dreamaker.io/organization/createbulkmembers

  • HTTP method: POST

  • HTTP content-type: application/json

  • HTTP content body sample JSON:

{
"organizationID": "@example.com",
"apiPublicKey": "123_the_public_key",
"apiSecretKey": "123_the_secret_key",
"users": [
{ "firstName": "Alpha", "lastName": "Beta", "email": "alpha.beta@gmail.com" },
{ "firstName": "Gamma", "lastName": "Delta", "email": "gamma.delta@gmail.com" }
],
"organizationDeactivationDate": "2025-06-15",
"templateID": "47d4e408-d816-4c21-808f-d6aea64db26e",
"suppressMemberEmails": false
}

Detailed description of JSON properties:

  • organizationID (required): The organization that appears in your Dreamaker account page, where it says "You're owner of the @____ organization". The organizationID starts with (and includes) the @ sign.

  • apiPublicKey (required) and apiSecretKey (required): These will be given to you by the Dreamaker team.

  • users (required): An array of objects, with each user object containing 3 required properties: firstName, lastName, and email.

  • organizationDeactivationDate (optional): The date when all users' membership in your organization should be automatically deactivated. For example, expected graduation date or the start of a school break. Will be done at midnight in the GMT timezone. Must be in the format "YYYY-MM-DD".

  • templateID (optional): ID of the template to apply to all new users created. Equivalent to selecting a template in the "Select a template to start with" field when signing up. To see a list of templateIDs, put an invalid templateID (eg "asdf") in this property value and a list of templateIDs will be returned, organized hierarchically under each parent domain. This is identical to the visual representation of the template field dropdown in the signup page.

  • suppressMemberEmails (optional, defaults to false): Suppress the emails sent to each user. Used for silent user creation where you would then need to guide the user through resetting their password to be able to login.

API Response

The API response will be JSON. The API operation happens asynchronously and returns a preliminary success response if the request passes initial validation. In this case, the response will look like this:

{
"operationStatus": "The API call is in progress and results will be emailed to dreamaker.admin@example.com"
}

The organization owner will be emailed with a detailed description of the results of the user creation API call. If all users were created successfully, the results in the email will be an empty JSON map:

{}

If any user in the users array already exists (based on email address), all other users will be created and the duplicate user emails will be included in the email, in this format:

{
"emailAlreadyExists": [
"asdf@example.com",
"fdsa@example.com"
]
}

If the API fails initial validation, one of these error codes may be returned by the API call in the HTTP response, and this also indicates that no users were created:

  • UserCreateInvalidEmail: Cannot create user because email '<email>' is invalid.

  • OrganizationInviteMaxMembers: Operation would exceed maximum organization members for this account.

  • OrganizationBulkCreateMissingProperty: A property of array index <n> is missing in the users array. Required properties are 'firstName, lastName, email'

  • OrganizationBulkCreateDuplicateEmail: The email '<email>' is duplicated in the input

  • OrganizationDeactivationDateInvalid: The date parameter is invalid or in the past

  • InvalidAPIKey: Invalid API auth key(s) - one or more of these properties are invalid: organizationID, apiPublicKey, apiSecretKey

  • InvalidJSON: The JSON input is invalid

If you need help resolving an error, please reach out to us and include the requestId that is returned in the HTTP response or in the emailed response.

Member user experience

Two emails will be sent to each newly created member user (if suppressMemberEmails is not true):

  • Subject: "Activate Your Dreamaker.io Account" - This email gives the user a link to reset their password. They will not be able to login without doing this step. Users can also go to the following link to do this step if they cannot find this email (or the email was suppressed intentionally in the API call): https://app.dreamaker.io/reset

  • Subject: "Welcome to Dreamaker.io!" - This email is the standard welcome email, but also includes a reminder to reset their password to activate their account.

Did this answer your question?