Skip to main content
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.
1

Generate an API key

Generate and obtain an API key from the Anon Dashboard. See the Authentication guide for detailed instructions.
Only organization admins can generate API keys. Contact your Anon point-of-contact for assistance.
2

Make a POST request to create a modal embed URL

Here is the API Reference for this endpoint.Here is an example implementation to create a modal embed URL
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;
}
The API will respond with an signed/encrypted URL.
  {
  "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"
  }
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.
3

Embed the migration modal (client-side)

Embed the migration modal using the signed URL in an iFrame.
    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

Anon Modal Integration Demo

A full example implementation showing how to integrate the Anon migration modal into a Next.js application.
The user can now interact with the modal within the iframe to start a migration. The modal will handle the entire migration flow.
4

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.

Modal Communication

Read comprehensive implementation guidance for window.postMessage() events
To listen for modal events, add a message event listener in your parent application. Always check the event source and type:
Example implementation
  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;
  }
});
5

Configure server-side communication using webhooks

You can use some webhook events to be notified when migration tasks are complete, as a trigger to poll the Files API.
Your Anon organization can subscribe to webhook events to receive push‑style notifications whenever important events occur during the data‑migration lifecycle.
1

Create and add an endpoint

Navigate to dashboard.anon.com/webhooks and click + Add endpoint.
2

Define your event source

Enter the HTTPS URL (e.g. https://api.example.com/anon/webhooks) where you want to recieve events.
3

Create and test events

  • Click on Create. You’ll start receiving events immediately.
  • You can create a Svix Play endpoint to test receiving events
  • You can also send example events (svix.ping) through the Testing tab of your endpoint
All webhook events share the same payload format:
{
  "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"
  }
}
6

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:
    {
    "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"
    }
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.
That’s it! You’re now ready to implement and use Anon’s data migration agents!