> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Anon API in 5 minutes

This guide will help you quickly integrate with the Anon API to embed our migration modal
on your website and check migration status.

The server-side example is written in Node.js, but can be adopted with any language.

<Steps>
  <Step title="Generate an API key">
    Generate and obtain an API key from the [Anon Dashboard](https://dashboard.anon.com/keys). See the [Authentication guide](/v1/guides/auth) for detailed instructions.
    <Note>Only organization admins can generate API keys. Contact your Anon point-of-contact for assistance.</Note>
  </Step>

  <Step title="Make a POST request to create a modal embed URL">
    Here is the [API Reference](https://docs.anon.com/api-reference/migration-modal/create-migration-modal) for this endpoint.

    Here is an example implementation to create a modal embed URL

    <CodeGroup>
      ```js JavaScript theme={"system"}
      const ANON_API_KEY = process.env.ANON_API_KEY;
      const ANON_BASE_URL = "worker.anon.com";

      async function getAnonEmbedUrl() {
        const response = await fetch(`https://${ANON_BASE_URL}/api/v1/migration-modal`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${ANON_API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            user_id: 'your_end_user_UUID'
            source_provider: 'gusto'
          })
        });

        if (!response.ok) {
          throw new Error('Failed to get signed URL');
        }

        const anonEmbedUrlResponse = await response.json();
        return anonEmbedUrlResponse.url;
      }
      ```

      ```bash cURL theme={"system"}
      curl -X POST https://worker.anon.com/api/v1/migration-modal \
        -H "Authorization: Bearer ANON_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "user_id": "your_end_user_UUID"
          source_provider: 'gusto'
        }'
      ```
    </CodeGroup>

    The API will respond with an signed/encrypted URL.

    ```json theme={"system"}
      {
      "object": "migration_modal",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "migration_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "created": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z"
      }
    ```

    <Warning>We **do not recommend** creating multiple migration modals in quick succession with the same `user_id` in the body. This can create multiple migrations that overwrite or interfere with each other.</Warning>
  </Step>

  <Step title="Embed the migration modal (client-side)">
    Embed the migration modal using the signed URL in an iFrame.

    ```jsx theme={"system"}
        async function embedAnonModal() {
        const url = await getAnonEmbedUrl();
        
        // Create fullscreen iframe
        const iframe = document.createElement('iframe');
        iframe.src = url;
        iframe.style.cssText = 'position:fixed;inset:0;width:100%;height:100%;border:0;z-index:9999';
        iframe.setAttribute('allow', 'clipboard-read; clipboard-write');
        
        document.body.appendChild(iframe);
      }
    ```

    You can refer to this example Github repository with an implementation

    <Card title="Anon Modal Integration Demo" icon="github" href="https://github.com/anon-dot-com/anon-demo">
      A full example implementation showing how to integrate the Anon migration modal into a Next.js application.
    </Card>

    The user can now interact with the modal within the iframe to start a migration. The modal will handle the entire migration flow.
  </Step>

  <Step title="Configure client-side communication between the iFrame and your parent window">
    The Anon modal uses a structured event system to communicate user interactions and modal state to the parent window when embedded as an iframe. Events are sent via `window.postMessage()` and always include user and migration context.

    <Card title="Modal Communication" icon="messages" href="/v1/modal/messages">
      Read comprehensive implementation guidance for `window.postMessage()` events
    </Card>

    To listen for modal events, add a message event listener in your parent application. Always check the event source and type:

    ```javascript Example implementation theme={"system"}
      window.addEventListener("message", (event) => {
      // You can also check: event.origin === "https://dashboard.anon.com" for extra security
      if (event.data?.source !== "anon_modal") return;

      const modalEvent = event.data.event;
      if (!modalEvent) return;

      switch (modalEvent.type) {
        case "migration_modal.opened":
          // Handle modal opened
          break;
        case "migration_modal.completed":
          // Handle migration success
          break;
        case "migration_modal.closed":
          // Handle user exit
          break;
        case "migration_modal.failed":
          // Handle unrecoverable error
          break;
        // ... handle other event types as needed
        default:
          // Unknown event
          break;
      }
    });
    ```
  </Step>

  <Step title="Configure server-side communication using webhooks">
    <Tip>You can use some webhook events to be notified when migration tasks are complete, as a trigger to poll the Files API.</Tip>
    Your Anon organization can subscribe to [webhook events](/v1/modal/webhooks) to receive push‑style notifications whenever important events occur during the data‑migration lifecycle.

    <Steps>
      <Step title="Create and add an endpoint">
        Navigate to **[dashboard.anon.com/webhooks](https://dashboard.anon.com/webhooks)** and click **`+ Add endpoint`**.
      </Step>

      <Step title="Define your event source">
        Enter the HTTPS URL (e.g. `https://api.example.com/anon/webhooks`) where you want to recieve events.
      </Step>

      <Step title="Create and test events">
        * Click on **Create**. You'll start receiving events immediately.
        * You can create a [Svix Play](https://docs.svix.com/play) endpoint to test receiving events
        * You can also send example events (svix.ping) through the Testing tab of your endpoint
      </Step>
    </Steps>

    All webhook events share the same payload format:

    ```json theme={"system"}
    {
      "id": "evt_01HX4J1SQ93Y9F6VBQ4JPZW66S",
      "object": "event",
      "created": 2025-06-18T00:50:40.301173,
      "type": "<event_type>",
      "data": {
        "migration_id": "mig_01HX4J3SQ4QZZ9V9JMP8J2V7KZ",
        "object": { /* resource object (see below) */ },
        "error_message": "Only present for *.failed events"
      }
    }
    ```
  </Step>

  <Step title="Use the files API to retrieve extracted data">
    The files API allows you to list and retrieve files associated with migrations.
    Responses from the files API are returned in a structured JSON format as shown:

    ```json theme={"system"}
        {
        "object": "file",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "type": "CompanyInfo-EntityType-Screenshot",
        "url": "<string>",
        "size": 123,
        "content_type": "<string>",
        "migration_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
    ```

    <Note>Anon uses a medallion stricture to arrange files into three distinct layers that progressively improve data quality and structure. Bronze files are raw, unprocessed files from source systems. Silver files are standardized, machine-readable (typically JSON) files with enforced schemas.</Note>
  </Step>
</Steps>

<Check>That's it! You're now ready to implement and use Anon's data migration agents!</Check>