{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"redocly_category":"Guides","type":"markdown"},"seo":{"title":"Set up bulk user import","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"set-up-bulk-user-import","__idx":0},"children":["Set up bulk user import"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide describes how to import users into Mosaic from a JSON export of your existing user store. Bulk import is often combined with JIT migration. To choose a migration approach, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/platform/migrate_to_mosaic"},"children":["Migrate user store"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In bulk imports, user records are exported from an existing IDP and uploaded to Mosaic as a JSON file. Mosaic validates the records against its schema and creates users in its identity store. Imported users appear in the Admin Portal like any other Mosaic user."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bulk import doesn't include roles, groups, or authenticators. After the import, assign roles and groups in Mosaic, and register Mosaic authenticators for imported users (for example, in a login journey)."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant You\n participant Mosaic\n participant Store as Object storage\n\n You ->> Mosaic: Request upload URLs\n Mosaic -->> You: Presigned URL and form fields\n You ->> Store: Upload JSON file\n You ->> Mosaic: Start import run\n Mosaic ->> Store: Read file\n Mosaic -->> Mosaic: Validate records and create users\n You ->> Mosaic: Poll run progress\n Mosaic -->> You: Totals and outcome file URLs\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant You\n participant Mosaic\n participant Store as Object storage\n\n You ->> Mosaic: Request upload URLs\n Mosaic -->> You: Presigned URL and form fields\n You ->> Store: Upload JSON file\n You ->> Mosaic: Start import run\n Mosaic ->> Store: Read file\n Mosaic -->> Mosaic: Validate records and create users\n You ->> Mosaic: Poll run progress\n Mosaic -->> You: Totals and outcome file URLs\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The import flow:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You request upload URLs from Mosaic (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/migration/users/files/upload-urls"]},"). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#request-upload-urls"},"children":["Request upload URLs"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You upload each JSON file directly to object storage using its URL. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#upload-each-file"},"children":["Upload each file"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You start an import run (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/migration/users/runs"]},"). Mosaic reads the files, validates the records, and creates users. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-5-start-the-import"},"children":["Step 5: Start the import"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You poll the run (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/migration/users/runs/{run_id}"]},") for totals and outcome files listing failed records. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-6-track-progress-and-review-failures"},"children":["Step 6: Track progress and review failures"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally, you cancel a running import (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/migration/users/runs/{run_id}/cancel"]},") so you can start a new run. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-7-cancel-a-run"},"children":["Step 7: Cancel a run"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":2},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If this is your first time integrating with Mosaic, create an application in the Admin Portal as described ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/create_new_application"},"children":["here"]},". Imported users are assigned to the application you pass when you start the run."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-a-management-app","__idx":3},"children":["Step 1: Create a management app"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bulk import APIs are tenant-level operations. Authorize every call with a client access token generated from a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["management app"]},", not from the application you assign imported users to."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the Admin Portal, go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Management Apps"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add management app"]},", give it a name (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bulk user import"]},"), and save."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the app and copy the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client ID"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/management_apps"},"children":["Leverage management apps"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate a client access token with those credentials:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n 'https://api.transmitsecurity.io/cis/oidc/token' \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d grant_type=client_credentials \\\n -d client_id=MANAGEMENT_APP_CLIENT_ID \\\n -d client_secret=MANAGEMENT_APP_CLIENT_SECRET\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-align-the-user-schema","__idx":4},"children":["Step 2: Align the user schema"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you transform the export, make sure Mosaic can store the attributes you plan to import."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List the identifiers (such as email, phone number, or username) and other user attributes stored in your source user store. You'll map each of them to a Mosaic user field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the default ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/how_users_work"},"children":["Mosaic user schema"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the source uses attributes that Mosaic does not provide out of the box, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/manage_user_schema"},"children":["add custom user fields"]}," (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin Portal"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2C Identity"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Users"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Edit Schema"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Custom fields must exist in the tenant schema before you upload the file. Records that hold an undefined custom field fail validation and aren't created."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-prepare-the-json-file","__idx":5},"children":["Step 3: Prepare the JSON file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Export the source user store from your existing IDP, then transform it into a JSON ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["array of user objects"]},". Field order within each object does not matter. Field names and types must match Mosaic."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each record follows the same structure as the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/user/user.openapi/other/createuser#other/createuser/request/body"},"children":["Create user"]}," request body, with these constraints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["at least one identifier"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone_number"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", or a custom identifier you defined in the schema). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," can be included, but it does not count as an identifier. Records with only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_user_id"]}," fail validation and aren't created."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Identifiers must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unique"]}," across all records in the file and across existing Mosaic users (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]}," is unique per application)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unknown fields are rejected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not include plaintext passwords in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credentials"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delegated_access"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Put custom attributes in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom_user_fields"]}," (subject to availability in your tenant). Those keys must already exist in the tenant schema (see Step 2)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each record can also include these fields supported only for bulk import:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional Mosaic user ID to assign. If omitted, Mosaic generates one. A duplicate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," fails at creation. Ability to provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]}," is subject to availability in your tenant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email_verified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the primary email is already verified."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email_verified_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the email was verified (ISO 8601)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone_verified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the primary phone number is already verified."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone_verified_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the phone number was verified (ISO 8601)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Disabled"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Pending"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_auth"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp of the user's last authentication in the source system (ISO 8601)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashed_password"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pre-hashed password to store as-is. Mosaic verifies it at login using the given algorithm. Do not send a plaintext password."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashed_password_history"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of previous password hashes in the same shape as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashed_password"]},". Up to 20 entries. Requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashed_password"]}," to be set."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashed_password"]}," (and each item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashed_password_history"]},") uses this object:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hash"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The password hash string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Algorithm used to produce the hash. Supported values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["argon2"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bcrypt"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha1"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha2"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha256"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha512"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ssha"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ssha256"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ssha512"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["md5"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["smd5"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firebaseScrypt"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drupalPhpass"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["salt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Salt used when hashing, if the algorithm requires it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["force_replace"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the password is temporary and the user must replace it after a successful login."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["File names must match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["^[a-zA-Z0-9][a-zA-Z0-9._-]*\\.json$"]}," (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["users_eu_1.json"]},") and cannot exceed 255 characters. A file cannot exceed 2 GB. A tenant can store up to 1000 files. Split a large export across multiple files if needed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example file (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["users_batch_1.json"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n {\n \"user_id\": \"3cu0eCGdFIkAXLpcNQnPa\",\n \"external_user_id\": \"ext-2000097700\",\n \"external_account_id\": \"tPgBrCercegT\",\n \"email\": \"max.planck.2000097700@example.com\",\n \"email_verified\": true,\n \"email_verified_at\": \"2025-05-25T05:57:42.813Z\",\n \"phone_number\": \"+14153074425\",\n \"phone_verified\": true,\n \"phone_verified_at\": \"2025-12-28T22:50:33.147Z\",\n \"username\": \"mplanck_2000097700\",\n \"name\": {\n \"title\": \"Ms.\",\n \"first_name\": \"Max\",\n \"middle_name\": \"Woodrow\",\n \"last_name\": \"Planck\"\n },\n \"birthday\": \"1858-09-14\",\n \"address\": {\n \"country\": \"DE\",\n \"state\": \"California\",\n \"city\": \"New Randalfurt\",\n \"street_address\": \"5354 America Passage\",\n \"postal_code\": \"52372\",\n \"type\": \"Other\"\n },\n \"picture\": \"https://avatars.githubusercontent.com/u/79465009\",\n \"language\": \"de\",\n \"status\": \"Disabled\",\n \"last_auth\": \"2026-06-16T03:24:01.209Z\",\n \"hashed_password\": {\n \"hash\": \"$2b$10$sJZrc4geZiludsEJ3nxzg3eRSnTYPWeb66Ee1ZSkLxoxr6DBrTBm8\",\n \"algorithm\": \"bcrypt\",\n \"force_replace\": false\n },\n \"custom_app_data\": {\n \"source\": \"poc\",\n \"batch\": 0,\n \"discipline\": \"science\"\n },\n \"hashed_password_history\": [],\n \"custom_user_fields\": {\n \"discipline\": \"science\",\n \"birth_year\": 1858,\n \"notable_work\": \"The quantum of action\",\n \"is_nobel_laureate\": true,\n \"scholar_id\": \"SCH-00X2T19G\",\n \"first_publication\": \"1883-09-17T00:00:00.000Z\",\n \"research_areas\": [\n \"astrophysics\"\n ],\n \"milestones\": [\n \"1899-04-11T01:11:07.890Z\"\n ],\n \"contact_email\": \"max.planck.2000097700@lab.example.com\",\n \"lab_phone\": \"+12125557286\",\n \"bio\": {\n \"discipline\": \"science\",\n \"born\": 1858,\n \"known_for\": \"The quantum of action\",\n \"verified\": false\n }\n }\n }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-upload-the-files","__idx":6},"children":["Step 4: Upload the files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Files are uploaded directly to object storage, not through the Mosaic API host. The upload takes two calls per batch of files:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request an upload URL for each file name from Mosaic."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload each file to its URL, using the form fields Mosaic returned."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a URL expires (after 15 minutes) or an upload is interrupted, request a new URL for the same file name and upload again."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-upload-urls","__idx":7},"children":["Request upload URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/migration/users/files/upload-urls"]}," with the file names you will upload. You can request up to 100 names in one call. Mosaic returns an upload URL, valid for 15 minutes, and form fields for each name. Re-requesting a name you already uploaded returns a URL that overwrites the same object."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/files/upload-urls' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"files\": [\"users_batch_1.json\"]\n }'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"result\": {\n \"files\": [\n {\n \"name\": \"users_batch_1.json\",\n \"url\": \"https://storage.example/upload\",\n \"fields\": {\n \"key\": \"user-migration/TENANT_ID/files/users_batch_1.json\",\n \"policy\": \"...\"\n },\n \"expires_at\": \"2026-09-15T12:00:00.000Z\"\n }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"upload-each-file","__idx":8},"children":["Upload each file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload each file with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]}," POST to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," returned for that file name. Include every entry in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," as a form field, then attach the file as the last field."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n 'UPLOAD_URL' \\\n -F 'key=OBJECT_KEY' \\\n -F 'policy=POLICY' \\\n -F 'file=@/path/to/users_batch_1.json'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," values Mosaic returned. Add any additional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," entries the response includes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-start-the-import","__idx":9},"children":["Step 5: Start the import"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the files have been uploaded to storage, you can run the import in one of two modes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dry run"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]},"): validates every record against the schema without creating users. Use it to find and fix validation errors before the real import. A dry run always reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Live"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]},"): validates every record and creates the users that pass validation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To start a run:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/runs' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"mode\": \"live\",\n \"app_id\": \"APP_ID\",\n \"files\": [\"users_batch_1.json\"]\n }'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_id"]},": the application the imported users will be assigned to."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]},": the uploaded file names to process. If you omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]},", the run processes every file currently uploaded for the tenant."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["run_id"]},". A tenant can have only one active run at a time. Starting another run while one is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["running"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},". To start a different run, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-7-cancel-a-run"},"children":["cancel"]}," the active one first. Mosaic also rejects the run if a listed file is missing from storage or if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_id"]}," does not exist."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Created users appear in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin Portal"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2C Identity"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Users"]}," and through the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/user/user.openapi/other/getusers"},"children":["Users APIs"]},". Existing users are not updated."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-track-progress-and-review-failures","__idx":10},"children":["Step 6: Track progress and review failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/migration/users/runs/{run_id}"]}," until the run is no longer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["running"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X GET \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/runs/RUN_ID' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"result\": {\n \"run_id\": \"RUN_ID\",\n \"status\": \"completed\",\n \"mode\": \"live\",\n \"total_files\": 1,\n \"processed\": 2,\n \"created\": 1,\n \"failed\": 1,\n \"started_at\": \"2026-09-22T12:00:00.000Z\",\n \"completed_at\": \"2026-09-22T12:05:00.000Z\",\n \"files\": [\n {\n \"name\": \"users_batch_1.json\",\n \"status\": \"completed\",\n \"processed\": 2,\n \"created\": 1,\n \"failed\": 1,\n \"outcome_url\": \"https://storage.example/outcomes/users_batch_1.json\"\n }\n ]\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," for the run is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["running"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed_at"]}," is present only after the run ends."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," are totals across every file. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," covers records that did not match the schema (for example, a missing identifier, an invalid field, or a custom field that is not defined for the tenant) and records Mosaic could not create (for example, a duplicated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", or other unique identifier)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files"]}," reports the same counters per uploaded file. Each file status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["running"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outcome_url"]}," is a download link valid for 24 hours. It appears after that file has completed. Use it to inspect each failed record and the reason."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fix the failed records, upload a new file (or overwrite the same name), and start another run for the remaining users."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-7-cancel-a-run","__idx":11},"children":["Step 7: Cancel a run"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To stop a run that is still ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["running"]},", call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/migration/users/runs/{run_id}/cancel"]},". Mosaic sets the run status to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," and does not process remaining work. Work already in progress finishes, and each file still gets a report. Users that were already created stay in the identity store."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the run is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},", you can start a new run."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/runs/RUN_ID/cancel' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"upload-file-management","__idx":12},"children":["Upload file management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Uploaded files are stored by Transmit for one month and then deleted automatically. Until then, you can reuse an uploaded file in later runs. As a best practice, delete files you no longer need."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List files:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X GET \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/files' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delete one file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X DELETE \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/files/users_batch_1.json' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delete all uploaded files:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -i -X DELETE \\\n 'https://api.transmitsecurity.io/cis/v1/migration/users/files' \\\n -H 'Authorization: Bearer MANAGEMENT_APP_ACCESS_TOKEN'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You cannot delete files while a migration run is in progress."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sample-migration-script","__idx":13},"children":["Sample migration script"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Developed by Transmit Security engineers, this sample script processes up to 1 million user records in about 10 minutes after the files are uploaded. Upload time depends on your network connection and is not included in that 10 minutes. To use the script:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set values for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APP_ID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BASE_URL"]}," at the top of the script. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APP_ID"]}," is the application imported users will be assigned to, not the management app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Run the script with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["management app"]}," client credentials and paths to the files: ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_ID=... CLIENT_SECRET=... node bulk-migrate-users.mjs ./users-1.json ./users-2.json"]}]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"bulk-migrate-users.mjs","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"import { existsSync, openAsBlob } from 'node:fs';\nimport { writeFile } from 'node:fs/promises';\nimport { basename } from 'node:path';\nimport { setTimeout as sleep } from 'node:timers/promises';\n\nconst BASE_URL = 'https://api.transmitsecurity.io/cis'; // Update according to your environment\nconst APP_ID = 'YOUR_APP_ID'; // Replace with your app ID\nconst MODE = 'dry_run'; // Change to 'live' to create the users. 'dry_run' only validates the files\nconst FILE_PATHS = process.argv.slice(2);\n\nlet accessToken;\nlet accessTokenExpiresAt = 0;\n\nasync function getAccessToken() {\n if (Date.now() < accessTokenExpiresAt) {\n return accessToken;\n }\n const response = await fetch(`${BASE_URL}/oidc/token`, {\n method: 'POST',\n body: new URLSearchParams({\n grant_type: 'client_credentials',\n client_id: process.env.CLIENT_ID,\n client_secret: process.env.CLIENT_SECRET,\n }),\n });\n const token = await response.json();\n accessToken = token.access_token;\n accessTokenExpiresAt = Date.now() + (token.expires_in - 60) * 1000;\n return accessToken;\n}\n\nasync function callApi(method, path, body) {\n const token = await getAccessToken();\n const response = await fetch(`${BASE_URL}${path}`, {\n method,\n headers: {\n Authorization: `Bearer ${token}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify(body),\n });\n const responseText = await response.text();\n if (!response.ok) {\n throw new Error(`${method} ${path} failed with ${response.status}: ${responseText}`);\n }\n return JSON.parse(responseText).result;\n}\n\n// 1. Upload each file with its own presigned form\nasync function uploadFiles(filePaths) {\n const missingFiles = filePaths.filter((filePath) => !existsSync(filePath));\n if (filePaths.length === 0) {\n throw new Error('Pass the files to upload: node bulk-migrate-users.mjs users-1.json users-2.json');\n }\n if (missingFiles.length > 0) {\n throw new Error(`Files not found: ${missingFiles.join(', ')}`);\n }\n const fileNames = [];\n for (const filePath of filePaths) {\n const fileName = basename(filePath);\n const file = await openAsBlob(filePath);\n const startedAt = Date.now();\n console.log(`Uploading ${fileName} (${(file.size / 1024 ** 2).toFixed(1)} MB)`);\n const {\n files: [uploadForm],\n } = await callApi('POST', '/v1/migration/users/files/upload-urls', { files: [fileName] });\n const form = new FormData();\n for (const [field, value] of Object.entries(uploadForm.fields)) {\n form.append(field, value);\n }\n form.append('file', file, fileName);\n const upload = await fetch(uploadForm.url, { method: 'POST', body: form });\n if (!upload.ok) {\n throw new Error(`Uploading ${fileName} failed with ${upload.status}`);\n }\n console.log(`Uploaded ${fileName} in ${Math.round((Date.now() - startedAt) / 1000)}s`);\n fileNames.push(fileName);\n }\n return fileNames;\n}\n\n// 2. Start a migration run on the uploaded files\nasync function startRun(fileNames) {\n const { run_id: runId } = await callApi('POST', '/v1/migration/users/runs', {\n mode: MODE,\n app_id: APP_ID,\n files: fileNames,\n });\n console.log(`Started run ${runId}`);\n return runId;\n}\n\n// 3. Poll the run status until the run finishes\nasync function pollRunStatus(runId) {\n while (true) {\n const run = await callApi('GET', `/v1/migration/users/runs/${runId}`);\n console.log(`${run.status}: processed ${run.processed}, created ${run.created}, failed ${run.failed}`);\n if (run.status !== 'running') {\n return run;\n }\n for (let seconds = 10; seconds > 0; seconds -= 1) {\n process.stdout.write(`\\rNext check in ${seconds}s `);\n await sleep(1000);\n }\n process.stdout.write('\\r');\n }\n}\n\n// 4. Save the report of each file\nasync function saveReports(run) {\n for (const { name, outcome_url: outcomeUrl } of run.files) {\n if (outcomeUrl) {\n const reportPath = name.replace(/\\.json$/, '.report.json');\n console.log(`Downloading the report of ${name}`);\n const report = await fetch(outcomeUrl);\n const reportBytes = await report.arrayBuffer();\n await writeFile(reportPath, new Uint8Array(reportBytes));\n console.log(`Saved ${reportPath}`);\n }\n }\n}\n\ntry {\n const fileNames = await uploadFiles(FILE_PATHS);\n const runId = await startRun(fileNames);\n const run = await pollRunStatus(runId);\n await saveReports(run);\n} catch (error) {\n console.error(error.message);\n process.exitCode = 1;\n}\n","lang":"js"},"children":[]}]}]}]},"headings":[{"value":"Set up bulk user import","id":"set-up-bulk-user-import","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Create a management app","id":"step-1-create-a-management-app","depth":2},{"value":"Step 2: Align the user schema","id":"step-2-align-the-user-schema","depth":2},{"value":"Step 3: Prepare the JSON file","id":"step-3-prepare-the-json-file","depth":2},{"value":"Step 4: Upload the files","id":"step-4-upload-the-files","depth":2},{"value":"Request upload URLs","id":"request-upload-urls","depth":3},{"value":"Upload each file","id":"upload-each-file","depth":3},{"value":"Step 5: Start the import","id":"step-5-start-the-import","depth":2},{"value":"Step 6: Track progress and review failures","id":"step-6-track-progress-and-review-failures","depth":2},{"value":"Step 7: Cancel a run","id":"step-7-cancel-a-run","depth":2},{"value":"Upload file management","id":"upload-file-management","depth":2},{"value":"Sample migration script","id":"sample-migration-script","depth":2}],"frontmatter":{"markdown":{"toc":{"depth":2}},"seo":{"title":"Set up bulk user import"}},"lastModified":"2026-10-27T08:47:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/platform/bulk_user_migration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}