docs: document batch create identities

docs/migrate-to-ory/import-identities.mdx

@@ -0,0 +1,80 @@
+---
+id: import-identities
+title: Bulk-import identities from other providers
+sidebar_label: Bulk-import identities
+slug: bulk-import-identities
+---
+
+# Bulk-import identities from other providers
+
+To import multiple identities into Ory Identites, use the
+[Identity Import API](https://www.ory.sh/docs/reference/api#tag/identity/operation/batchPatchIdentities).
+
+A maximum of 2000 identities can be created in a single request. If you need to import more identities, you can split the import
+into multiple requests.
+
+The endpoint accepts a JSON array of identities, each of which must have a `create` propery which holds the identity that should
+be created. Optionally, you can specify a `patch_id` property which will be returned in the response. This can be used to
+correlate the response with the patch.
+
+The following example shows how to import two identities. It will create two identities with the email addresses `[email protected]`
+and `[email protected]` and the passwords `foopassword` and `barpassword` respectively.
+
+```bash
+curl --location --request PATCH 'https://${YOUR_PROJECT_SLUG}.projects.oryapis.com/admin/identities' \
+--header 'Authorization: Bearer ${YOUR_ORY_ACCESS_TOKEN}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "identities": [
+        {
+            "create": {
+                "credentials": {
+                    "password": {
+                        "config": {
+                            "password": "foopassword"
+                        }
+                    }
+                },
+                "state": "active",
+                "traits": {
+                    "email": "[email protected]"
+                },
+                "schema_id": "preset://email"
+            }
+        },
+                {
+            "create": {
+                "credentials": {
+                    "password": {
+                        "config": {
+                            "password": "barpassword"
+                        }
+                    }
+                },
+                "state": "active",
+                "traits": {
+                    "email": "[email protected]"
+                },
+                "schema_id": "preset://email"
+            }
+        }
+    ]
+}'
+```
+
+The service will respond with the two identity IDs created:
+
+```json
+{
+  "identities": [
+    {
+      "action": "create",
+      "identity": "55f93ea4-09ff-4273-8b88-082cc70d6d44"
+    },
+    {
+      "action": "create",
+      "identity": "f70c9b29-4790-4330-90dc-920db16a4b85"
+    }
+  ]
+}
+```

src/sidebar.js

@@ -304,6 +304,7 @@ module.exports = {
       items: [
         "hydra/self-hosted/migrating-from-mitreid",
         "migrate-to-ory/auth0",
+        "migrate-to-ory/import-identities",
       ],
     },
     {