📝 Docs update

docs/core-concepts/custom-fields.mdx

@@ -11,7 +11,17 @@ Creating a `Field Mapping` involves two majors actions:
 - Defining a custom field on Panora's side
 - Mapping it to a field from your customer's software.
 
-_insert video_
+In this video we define a field and then once a connection is available we fetch fields inside your user's software so you can map the custom field with Panora.
+
+<Frame type="glass">
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/definefields.mp4"
+  ></video>
+</Frame>
+
+## Create a custom field mapping using the our UI dashboard
 
 <Steps>
 
@@ -20,23 +30,55 @@ _insert video_
     </Step>
 
     <Step title="Define your custom field">
-    Click `Add Field Mapping`. Select a unified object you want to extend, and give your custom field a slug and a friendly name. You also need to select a data type.
+    Click `Define a custom field`. Select a unified object you want to extend, and give your custom field a slug and a friendly name. You also need to select a data type.
     </Step>
 
     <Step title="Map your custom field to a remote field">
 
-Now, move to the `Map Fields` section. To finish the mapping, select the custom field you just created, and fill the fields `Provider` and Linked User ID.
+Now, click on the `Map a custom field` button. To finish the mapping, select the custom field you just created, and fill the fields `Provider` and `Linked User Id`.
 
 </Step>
 
     <Step>
 
-You will now find all the fields your user has in its software. Pick the one that you want to map to.
+You will now find all the fields your user has in its software. Pick the one that you want to map to. Click `Map`.
 
 </Step>
 
 </Steps>
 
+## Create a custom field mapping using our API
+
+The following example creates a custom field mapping in two steps (**define and map**) where we map a remote field called `hair_color_hubspot_123_id` (existing in the `Husbpot` provider) and mapping it to the `crm.contact` unified model of Panora under the name of `hair_color`.
+
+        <CodeGroup>
+        ```shell Define custom field
+        curl --request POST \
+             --url https://api.panora.dev/field-mappings/define \
+             --header 'Authorization: Bearer <MY_API_KEY>' \
+             --header 'Content-Type: application/json' \
+             --data '{
+                "object_type_owner": "crm.contact",
+                "name": "hair_color",
+                "description": "My hair_color field mapping",
+                "data_type": "text"
+             }'
+        ```
+
+        ```shell Map custom field
+        curl --request POST \
+             --url https://api.panora.dev/field-mappings/map \
+             --header 'Authorization: Bearer <MY_API_KEY>' \
+             --header 'Content-Type: application/json' \
+             --data '{
+                "attributeId": "id_defined_field", # retrieve that from response of the /define request
+                "source_custom_field_id": "hair_color_hubspot_123_id", # id of the remote field inside the remote provider
+                "source_provider": "hubspot",
+                "linked_user_id": "acme_customer_a"
+             }'
+        ```
+        </CodeGroup>
+
 [✏️ Suggest an update](https://tally.so/r/mRD1QQ?feedback_source=custom_fields)
 
 [Need help? Come chat on Discord!](https://discord.gg/G7fr4HNyTb)

docs/core-concepts/magic-links.mdx

@@ -5,11 +5,11 @@ icon: "wand-magic-sparkles"
 ---
 
 <Frame type="glass">
-  <img
-    className="block"
-    src="/images/generate-magic-link.gif"
-    alt="Hero Light"
-  />
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/magiclinks.mp4"
+  ></video>
 </Frame>
 
 ## Send your first Magic Link
@@ -18,14 +18,19 @@ icon: "wand-magic-sparkles"
 
 <Step>Login to your [account dashboard](https://dashboard.panora.dev)</Step>
 
-<Step>Go to the _Connections_ [section](https://dashboard.panora.dev/connections) and click button `Create a Magic Link`</Step>
+<Step>
+  Go to the _Connections_ [section](https://dashboard.panora.dev/connections)
+  and click button `Create a Magic Link`
+</Step>
 
 <Step>Click `Create a Unique Magic Link`</Step>
 
 <Step>
   You'll be asked for two informations: an `Origin User Email` and an `Origin
   User Identifier`. The `Origin User Identifier` is the id of the user you're
-  inviting, as represented in your systems.
+  inviting, as represented in your systems. If you already have created a
+  [Linked User](/recipes/import-existing-users) you have the option to select
+  it.
 </Step>
 
 <Step>Click `Generate`</Step>

docs/mint.json

@@ -405,7 +405,6 @@
     {
       "group": "Recipes",
       "pages": [
-        "recipes/share-magic-link", 
         "recipes/embed-catalog", 
         "recipes/import-existing-users", 
         "recipes/catch-connection-token",

docs/quick-start.mdx

@@ -14,7 +14,7 @@ Before you begin, make sure you have the following:
 
 ## **Step 1: Get access to your users data**
 
-You either have the option to use a **no-code magic link** or the **embedded frontend snippet** to get access to your user's data.
+You either have the option to use a [**no-code magic link**](/core-concepts/magic-links) or the [**embedded frontend snippet**](/recipes/embed-catalog) to get access to your user's data.
 Choose the one that fits your needs !
 
 <Steps titleSize="h3">
@@ -38,7 +38,8 @@ Choose the one that fits your needs !
         You'll be asked for two informations: an `Origin User Email` (of the user
         you're creating the link for) and an `Origin User Identifier`. The `Origin
         User Identifier` is the id of the user you're inviting, as represented in your
-        sofwtare.
+        sofwtare. If you already have created a [Linked User](/recipes/import-existing-users) you have the option to select
+        it.
       </Step>
       <Step>Click `Generate`</Step>
     </Steps>
@@ -65,22 +66,36 @@ Choose the one that fits your needs !
                 ```javascript React
                 import "@panora/embedded-card-react/dist/index.css";
                 import PanoraProviderCard from "@panora/embedded-card-react";
+                import PanoraDynamicCatalog from "@panora/embedded-card-react";
                 ```
             </CodeGroup>
         </Step>
 
-        <Step title="Use the catalog in your integrations page:">
+        <Step title="Use the catalog in your integrations page">
+            You can either import a single connector card or a catalog of all connectors that you select in the UI dashboard configuration (see [here](//recipes/embed-catalog) for more details).
+            <Info>In order to fill the `linkedUserId` prop, use your own remote id that exist in your system **OR** check this [recipe](/recipes/import-existing-users) ! </Info>
             <CodeGroup>
-                ```javascript React
+                ```javascript Single Connector Card
                 <PanoraProviderCard
                     name={"hubspot"} # name of the provider
-                    vertical={"crm"} # vertical where provider belongs to
+                    category={"crm"} # vertical where provider belongs to
+                    projectId={"c9a1b1f8-466d-442d-a95e-11cdd00baf49"} # the project id tied to your organization
+                    returnUrl={"https://acme.inc"} # the url you want to redirect users to after the connection flow is successful
+                    linkedUserId={"b860d6c1-28f9-485c-86cd-fb09e60f10a2"}  # the linked id of the user if already created in Panora system or user's info in your system
+                />
+                ```
+                ```javascript Whole Connector Catalog
+                <PanoraDynamicCatalog
+                    category={"crm"} # optional but if provided it returns only connectors of the category
                     projectId={"c9a1b1f8-466d-442d-a95e-11cdd00baf49"} # the project id tied to your organization
                     returnUrl={"https://acme.inc"} # the url you want to redirect users to after the connection flow is successful
                     linkedUserId={"b860d6c1-28f9-485c-86cd-fb09e60f10a2"}  # the linked id of the user if already created in Panora system or user's info in your system
                 />
                 ```
             </CodeGroup>
+            You should see a card or catalog being rendered client-side !
+
+            __insert photo__
         </Step>
     </Steps>
 

docs/recipes/add-custom-provider-creds.mdx

@@ -14,5 +14,9 @@ icon: "gear-code"
 Visit the _Manage Connectors_ [section](https://dashboard.panora.dev/configuration), choose the connector you wish to add credentials for and add your own credentials.
 
 <Frame type="glass">
-  <img src="/images/custom-oauth.png" />
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/customcreds.mp4"
+  />
 </Frame>

docs/recipes/import-existing-users.mdx

@@ -2,4 +2,79 @@
 title: "Import Your Existing Users"
 description: ""
 icon: "users"
----
+---
+
+## Using the UI
+
+#### You can add a single linked user
+
+<Frame type="glass">
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/linkedusers.mp4"
+  ></video>
+</Frame>
+
+#### You can add a batch of linked users by using the drag n drop tool
+
+<Frame type="glass">
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/linkedusers.mp4"
+  ></video>
+</Frame>
+
+## Using our API
+
+This code adds a single/batch of linked accounts inside Panora. It helps us have an exact mapping of your existing users insdie our system.
+
+<CodeGroup>
+ ```shell Import a single existing user
+  curl --request POST \
+      --url https://api.panora.dev/linked-users \
+      --header 'Authorization: Bearer <MY_API_KEY>' \
+      --header 'Content-Type: application/json' \
+      --data '{
+          "linked_user_origin_id": "acme_user_1", # your remote id (id representing your existing user inside your system)
+          "alias": "acme", # your company name
+          "id_project": "ikloqqkq90-djsddhjs-prs12dj",
+      }'
+  ```
+    ```shell Import a batch of existing users
+    curl --request POST \
+        --url https://api.panora.dev/linked-users/batch \
+        --header 'Authorization: Bearer <MY_API_KEY>' \
+        --header 'Content-Type: application/json' \
+        --data '{
+            "linked_user_origin_ids": ["acme_user_1", "acme_user_2", "acme_user_3"], # array of remote ids (ids representing your existing users inside your system)
+            "alias": "acme", # your company name
+            "id_project": "ikloqqkq90-djsddhjs-prs12dj",
+        }'
+    ```
+</CodeGroup>
+
+# How to fetch linked users
+
+You must know how to fetch linked users as you'll have to use them in the UI widget prop.
+
+## Fetch using our library functions
+
+At any point in your code, if you have successfully added your linked users (see above) you'll be able to fetch them by calling :
+
+- `linkedUserFromRemoteId(remote_id: string)` where `remote_id` is the id of the user inside your system and this function returns a [LinkedUser object](/glossary/linked-account-object).
+- `fetchLinkedUsers()` where this function returns an array of [LinkedUser objects](/glossary/linked-account-object) for your projectId.
+
+<CodeGroup>
+ ```shell linkedUserFromRemoteId
+    curl --request GET \
+            --url https://api.panora.dev/linked-users/fromRemoteId?remoteId=acme_id_1 \
+            --header 'Authorization: Bearer <MY_API_KEY>' \
+    ```
+    ```shell fetchLinkedUsers
+    curl --request GET \
+            --url https://api.panora.dev/linked-users \
+            --header 'Authorization: Bearer <MY_API_KEY>' \
+    ```
+</CodeGroup>

packages/api/src/@core/linked-users/linked-users.controller.ts

@@ -54,13 +54,13 @@ export class LinkedUsersController {
   }
 
   @ApiOperation({
-    operationId: 'getLinkedUsers',
+    operationId: 'fetchLinkedUsers',
     summary: 'Retrieve Linked Users',
   })
   @ApiResponse({ status: 200 })
   @UseGuards(JwtAuthGuard)
   @Get()
-  getLinkedUsers(@Request() req: any) {
+  fetchLinkedUsers(@Request() req: any) {
     const { id_project } = req.user;
     return this.linkedUsersService.getLinkedUsers(id_project);
   }
@@ -79,14 +79,14 @@ export class LinkedUsersController {
   }
 
   @ApiOperation({
-    operationId: 'getLinkedUser',
-    summary: 'Retrieve a Linked User',
+    operationId: 'linkedUserFromRemoteId',
+    summary: 'Retrieve a Linked User From A Remote Id',
   })
-  @ApiQuery({ name: 'originId', required: true, type: String })
+  @ApiQuery({ name: 'remoteId', required: true, type: String })
   @ApiResponse({ status: 200 })
   //@UseGuards(JwtAuthGuard)
-  @Get('single')
-  getLinkedUserV2(@Query('originId') id: string) {
+  @Get('fromRemoteId')
+  linkedUserFromRemoteId(@Query('remoteId') id: string) {
     // validate project_id against user
     return this.linkedUsersService.getLinkedUserV2(id);
   }

packages/api/swagger/swagger-spec.json

@@ -502,7 +502,7 @@
         ]
       },
       "get": {
-        "operationId": "getLinkedUsers",
+        "operationId": "fetchLinkedUsers",
         "summary": "Retrieve Linked Users",
         "parameters": [],
         "responses": {
@@ -546,7 +546,31 @@
         "summary": "Retrieve a Linked User",
         "parameters": [
           {
-            "name": "originId",
+            "name": "id",
+            "required": true,
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": ""
+          }
+        },
+        "tags": [
+          "linked-users"
+        ]
+      }
+    },
+    "/linked-users/fromRemoteId": {
+      "get": {
+        "operationId": "linkedUserFromRemoteId",
+        "summary": "Retrieve a Linked User From A Remote Id",
+        "parameters": [
+          {
+            "name": "remoteId",
             "required": true,
             "in": "query",
             "schema": {