How to Import Data into Confluence: Methods, API Limits & Mapping

Getting data into Confluence at scale is harder than Atlassian's documentation suggests. The native import UI handles Word docs and Google Docs in small batches — up to 30 files at a time in Cloud. There is no built-in Markdown importer, no direct Excel-to-page feature, and CSV import only works for Confluence databases, not pages. If you are migrating a knowledge base with hundreds of pages, nested hierarchies, embedded images, and cross-linked content, you will outgrow the built-in tools fast.

This guide covers every import method available in Confluence Cloud and Data Center, the real API constraints you will hit during programmatic imports, how Confluence maps incoming data (and what it silently drops), and how to choose the right approach based on your scale and source format.

For teams evaluating platforms, see our Notion vs. Confluence comparison. If you need to get data out of Confluence first, start with our Confluence export guide.

Choose the Destination Container Before the Import Tool

Before picking an import method, decide where your data should live inside Confluence. This choice matters more than the file format.

• Page tree: For long-form docs, knowledge articles, and hierarchical content. Most import methods target this. Confluence uses a rigid hierarchy — Instance → Space → Page → Child Page — backed by Confluence Storage Format, an XHTML-based representation.
• Confluence Database: For structured, row-and-column data that needs filters, views, field types, and sortable records. CSV import targets this.
• Cloud space import: For Confluence-to-Confluence migrations where you need to preserve native structure, including version history.

Many bad migrations happen because teams pick the wrong destination object before thinking about format conversion. If users need structured behavior — filters, field types, sorting — import into a Database. If they need narrative content with page trees, import into Pages. Get this wrong and cleanup multiplies.

Native Import Methods: What Works and What Breaks

Word Documents (.docx)

Confluence Cloud lets you import Word documents through the Templates & Import tab. (support.atlassian.com)

The workflow:

1. Create a new page or live doc.
2. Open More actions (…) → Templates and import.
3. Select the Import tab.
4. Choose Word document (.docx).
5. Select files and confirm.

Atlassian's current Cloud documentation allows importing up to 30 external documents per batch with a 50 MB total limit and 10 MB max per file. Multi-file imports land under a temporary Imported pages container for review. (support.atlassian.com)

Only .docx files are supported. Documents saved from LibreOffice or other non-Microsoft apps may not encode correctly.

What gets preserved: Headings, basic text formatting, simple tables, and supported images (BMP, GIF, JPG, PNG, SVG, WEBP).

What breaks:

• Images larger than 900 × 1200 pixels can stop the import process.
• Unsupported images are replaced with placeholder text.
• Word shapes are replaced with placeholders.
• Complex layouts, SmartArt, embedded charts, and ActiveX controls are either flattened or dropped.
• On Data Center, the uncompressed file size is limited to 20 MB by default (configurable via the confluence.word.import.maxsize system property).

Google Docs and OneDrive

Google Docs and OneDrive imports follow the same Templates & Import flow. Google Docs import requires OAuth connection. OneDrive only supports .docx files.

Both produce the same output as Word import — basic formatting preserved, complex layouts flattened. The import is a one-time operation: once a document is imported, the connection is severed. Updates in the original Google Doc will not reflect in Confluence.

HTML Import

The HTML importer handles static site archives and documentation exports from other wikis. Upload a ZIP file containing your HTML pages.

To use it: go to Spaces → Import from other tools → HTML, then upload your ZIP. The top-level folder name becomes the space name, and each HTML filename becomes a page title. For pages with media, that media must live in a folder with the same name as the page. (support.atlassian.com)

Atlassian documents good preservation for headings, paragraphs, lists, bold/italic, links, images, tables, quotes, dividers, inline code, and superscript.

Key limitations:

• HTML files are imported as a flat list — no page hierarchy preservation.
• iframe, figure, nav, and button elements are unsupported. Equations become plain text. Code blocks become plain text. Embedded video becomes a hyperlink.
• The ZIP is limited by the site's attachment-size setting (default 100 MB).
• Complex imports can take hours depending on size and bandwidth.

Notion Import

Confluence Cloud has a dedicated Notion importer via Spaces → Import from other tools → Notion. It supports importing an entire workspace or selected pages with subpages. With OAuth authentication, Atlassian can map users for @mentions, page comments, creator and editor information, and permissions.

What breaks:

• Macros and complex templates are not supported and may disrupt the import.
• Some images display correctly; others appear as bare URLs.
• Synced blocks, breadcrumb, button, table customization, inline equations, Mermaid code blocks, and database child-page properties are partially supported or unsupported.
• Hierarchical relationships between projects and tasks are not maintained.
• Comments migration support is inconsistent (as of early 2025).

For a deeper look at this path, see our Notion to Confluence migration guide.

Miro and Mural Board Imports

Confluence has specialized importers for Miro and Mural boards into Confluence whiteboards — not pages. Miro bulk import supports up to 10,000 elements and 5 MB per board, with a recommendation to keep each ZIP under 100 boards. Comments do not import. Mural has a similar flow.

Confluence-to-Confluence Space Import

XML space import is the only import method that preserves version history. You export a space as XML from the source instance and import it on the destination.

Key constraints:

• Archives larger than 100 MB should be uploaded via WebDAV.
• The space importer does not overwrite existing spaces — if the destination already has a space with the same space key, the import fails.
• User accounts and groups are not imported. User-linked data (mentions, comments, history) is included, but access and group membership must be recreated. Group-based permissions survive only if identically named groups already exist on the destination site.
• In Cloud, whiteboards and databases will not retain their content, data, or functionality after space import. (support.atlassian.com)

Importing CSV, Markdown, and Excel Data

For formats that Confluence does not natively support in its page import UI, you need workarounds, manual effort, or third-party apps.

CSV → Confluence Database

Confluence databases accept CSV imports directly. Open a database, go to Templates and Import, and upload a CSV file. You can let the imported data match a pre-configured structure, or let Confluence auto-detect field types and headers. (support.atlassian.com)

How auto-detection works:

The import process detects field types for numbers, tags, and Smart Links, defaulting everything else to text. The first row becomes field names, with default names assigned to empty headers and duplicates renamed automatically.

What silently breaks:

• Dates: Confluence assumes month-first parsing. 12/06/2025 becomes December 6, 2025 — not June 12. Date fields are not auto-detected; they must be manually set after import. There is no way to configure the date format during import. International teams using DD/MM/YYYY get silently corrupted data. Confluence also attempts timezone conversion — a date on January 1st may import as December 31st.
• Tags: String fields with mostly non-unique values may auto-convert to tag fields unexpectedly.
• Relations: Entry Link/Entity fields cannot be populated via CSV import. Relational links between databases require the REST API or manual entry.
• Copy-paste from Excel: Pasting from Excel into a database dumps the entire table into the first cell of the first row.

Excel Imports

There is no native feature to import Excel sheets directly as Confluence pages. Your options:

1. Copy-paste table data from Excel into the page editor — basic formatting survives, but formulas, dropdowns, conditional formatting, and merged cells are lost.
2. Save as CSV and import into a Confluence Database (with the date/type caveats above).
3. Use a Marketplace app like Excellentable or Elements Spreadsheet for richer Excel interop.

If you need a database-like view in Confluence from structured data, pasting a table into a page is not enough — it becomes static HTML content, not a queryable database with field settings, views, or filters. The workaround for pages is to create a parent "Index" page with a Page Properties Report macro, then programmatically generate child pages containing Page Properties macros where each row maps to a two-column HTML table inside the macro. This requires API automation.

Markdown Imports

Confluence has no native Markdown file import. The editor supports Markdown commands while typing (via the /markdown slash command), but you cannot upload .md files through the import UI.

The most common approaches:

• Marketplace apps: Atlassian's documentation points to apps like "Markdown Importer for Confluence" (which supports folders with hierarchy and attachment handling) and "All-in-one File Importer" (which handles Markdown, HTML, Word, LaTeX, ODT, reStructuredText, EPUB, and wiki markup).
• Custom API script: Convert Markdown → HTML → Confluence storage format (XHTML-based), then push pages via the REST API. Each conversion step can introduce formatting artifacts.

For teams migrating Markdown-heavy documentation from tools like Notion or Coda, see our guides for Notion to Confluence and Coda to Confluence.

Confluence REST API: Rate Limits and Attachment Challenges

When native imports cannot handle your scale or format, the Confluence REST API is the next option. Here is what you will actually deal with when building a migration script.

How Rate Limiting Works in Cloud

Confluence Cloud uses a points-based model to measure API usage. Each API call consumes points based on the work it performs — not a simple request count. (developer.atlassian.com)

Key mechanics:

• Quotas are measured per hour and reset at the top of each UTC hour.
• There is no partial throttling — once the quota is reached, all requests are blocked until reset.
• There is no carry-over between hours; unused quota does not accumulate.
• Exceeding the limit returns HTTP 429.

As of March 2, 2026, Atlassian's new points-based quotas began enforcement for Forge, Connect, and OAuth 2.0 apps. API token traffic is still governed by existing burst rate limits.

The response headers you need to monitor:

HTTP/1.1 429 Too Many Requests
Retry-After: 1847
X-RateLimit-Limit: 40000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-10-08T15:00:00Z

Rate Limiting in Data Center

Data Center uses a different model. Administrators configure rate limiting to control how many external REST API requests automations and users can make. Internal Confluence requests are not limited.

Data Center uses a token bucket model: users are given tokens exchanged for requests (one token = one request), with new tokens issued at a constant rate — for example, 10 every minute.

Handling Rate Limits in Migration Scripts

Atlassian's official guidance:

• Set a maximum of 4 retries (5 total attempts).
• Use exponential backoff with jitter: start with a 1-second base delay and double after each retry.
• Distribute requests evenly across the hour rather than sending bursts.
• Add random jitter to scheduled jobs.
• Coordinate across threads and nodes to prevent accidental quota exhaustion.

With the REST API v2, rate limiting is amplified by the N+1 request pattern. Creating a page with attachments, labels, and properties requires separate sequential calls:

# The N+1 problem in Confluence API v2
# Creating a page requires one call
page_response = requests.post(f"{base_url}/api/v2/pages", json=payload)
page_id = page_response.json().get("id")
 
# Attachments, labels, and properties each require separate calls
requests.post(f"{base_url}/api/v2/pages/{page_id}/attachments", files=files)
requests.post(f"{base_url}/api/v2/pages/{page_id}/labels", json=label_data)
requests.post(f"{base_url}/api/v2/pages/{page_id}/properties", json=prop_data)

If your script blasts the API with concurrent POST requests, Atlassian will throttle your token and your migration stalls mid-flight.

The Attachment Problem

Attachments are the most fragile part of any Confluence migration. Text is easy to move; binary files are not. The workflow requires multiple separate API calls per file:

1. Create the base page (to generate a Page ID).
2. Upload the attachment to that specific Page ID via a multipart/form-data API call (POST /rest/api/content/{pageId}/child/attachment). The request requires the X-Atlassian-Token: nocheck header.
3. Retrieve the new Attachment ID.
4. Update the page body with the correct <ac:image> or <ri:attachment> macro pointing to the uploaded file.

curl -X POST /wiki/rest/api/content/{pageId}/child/attachment \
  -H 'X-Atlassian-Token: nocheck' \
  -F 'file=@diagram.png'

Each step can fail independently. An image can upload successfully but fail to render inline if the storage format reference is wrong. This is the most common cause of "broken images" after API-driven migrations — the files exist as page attachments but are not embedded in the page body.

The V2 API endpoints for attachments are GET-only — no PUT or POST. The V1 API is still required for uploading attachments programmatically. That split between V1 for writes and V2 for reads is why DIY imports so often create pages first and fix attachments later.

Default attachment size limit: 100 MB per file (adjustable by admins). Confluence extracts up to 1 MB of text from Excel and PowerPoint files, and 16 MB from Word files, for search indexing purposes.

Standard data connectors have similar gaps. Microsoft's Databricks Confluence connector, for example, ingests only attachment metadata and page content — not the actual attachment files — while automatically retrying on Confluence rate limits. (learn.microsoft.com)

Data Mapping: What Gets Preserved vs. What Breaks

Understanding how Confluence interprets incoming data is the difference between a clean migration and weeks of cleanup.

CSV Columns → Database Fields

Page Content Mapping

When importing via API or Word import, content maps to Confluence storage format — an XHTML-based representation. Key translation rules:

• Headings → <h1> through <h6> (direct mapping)
• Ordered/unordered lists → standard HTML lists (preserved)
• Tables → Confluence table markup (basic structure preserved, merged cells often lost)
• Code blocks → <ac:structured-macro ac:name="code"> (requires explicit macro wrapping)
• Callouts/info panels → Must be mapped to <ac:structured-macro ac:name="info"> or equivalent
• Internal links → Break on every import. Source-platform URLs do not map to Confluence page IDs. These must be rewritten post-import.
• Page hierarchy → Not preserved in HTML or Word imports. Only XML space import maintains parent-child relationships.
• Macros from other platforms → No equivalent unless manually rebuilt

A table pasted or imported into a normal page becomes static HTML content. It does not become a queryable database with field settings, views, or filters. If you need structured behavior, create a Database.

Hierarchy Preservation by Method

Document import creates one page per file. HTML import produces a flat list. Only XML space import preserves an existing Confluence page tree. This is why teams are often disappointed when a bulk import technically succeeds but the destination architecture is wrong — all pages land flat and need manual restructuring.

What Never Survives Import

Regardless of method, these elements are always lost:

• Page history/version log (except XML space import)
• Comments (except XML space import and Notion importer with OAuth)
• Permissions/restrictions (must be reconfigured manually)
• Macros from source platforms (Notion toggles, Coda buttons, SharePoint web parts)
• Automations and workflows
• Inline database relations (CSV import cannot populate Entry Link fields)

Edge Cases and Real Migration Problems

Encoding Issues

CSV files with non-ASCII characters (accented names, CJK characters, currency symbols) must be UTF-8 encoded with BOM for reliable import. Files exported from Excel in certain locales use Windows-1252 encoding by default, producing garbled characters in Confluence. Always verify encoding in a plain text editor before import.

Date Format Corruption

Users in non-US locales report all dates being read as M/D/YYYY regardless of the source format, with no way to correct this during import. Confluence also attempts timezone conversion — a date on January 1st may import as December 31st. This is particularly damaging for audit-sensitive data.

Duplicate Pages and Key Conflicts

Confluence does not allow two pages with the same title in the same space. If your import produces duplicate titles (common when importing folder structures with index.html files), pages are silently renamed or rejected.

For XML space imports: if the destination already has a space with the same space key, the import fails entirely.

Atlassian also warns against special characters in page, live doc, or attachment names — search and some functions can behave unexpectedly. Uploading a file with the same name to the same page creates a new attachment version, not a second file.

Large Dataset Performance

For API-driven imports of 5,000+ pages:

• The hourly rate limit is your bottleneck, not network speed.
• Community users report creation rates dropping from a page per second to a page every 6 seconds during peak hours — likely due to shared infrastructure load on Confluence Cloud.
• Attachment-heavy imports multiply API calls per page by 3–5x (upload + link per attachment).
• There is no batch creation endpoint — each page is a separate POST.

Comparing Your Migration Options

Automation tools like Make and n8n expose modules for creating and updating pages, but they are designed for ongoing flows and small repeatable imports — not replaying a historical knowledge base with hierarchy, attachments, and cutover controls.

Where Native Imports Fail

• 200+ documents that need hierarchy → batch import creates flat pages, not trees.
• Relational data (linked databases, cross-references) → CSV cannot populate relations.
• Attachments must stay inline → native imports often decouple images from page context.
• Version history required → only XML space import preserves it, and only from another Confluence instance.

Where API Scripts Fail

• Rate limits throttle large jobs → a 10,000-page migration can take days if you constantly hit 429s.
• Attachment re-linking is error-prone → the multi-step upload-get-update pattern fails silently when storage format references are wrong.
• No built-in rollback → a half-completed API migration leaves your Confluence space in an inconsistent state.
• Macro mapping requires deep Confluence knowledge → converting source elements to ac:structured-macro XML is brittle.

Where Marketplace Apps Fail

• Most apps handle one format well (Markdown or Word or CSV) but cannot handle mixed-format migrations.
• Few support hierarchy preservation.
• Enterprise licensing costs add up when you need multiple apps for a single migration.
• Review each app's privacy and security page carefully — Atlassian's privacy policy does not automatically govern Marketplace app usage.

Pre-Import Checklist for a Clean Confluence Workspace

Before you import anything:

1. Decide on page tree vs. database. Do not start from the file format. Start from how the content needs to behave after go-live.

2. Audit your source content. Delete outdated, duplicate, and draft pages. Migrations are the best time to trim dead weight. Do not move trash into a new system.

3. Map your target space architecture. Design your Confluence space hierarchy — Spaces → Parent pages → Child pages — before importing. Draw it out. Restructuring after 500 pages land in a flat list is painful. Do not dump all imported content into a single "Migrated Data" space. If you are consolidating multiple instances, read our guide on how to export all data from Confluence.

4. Normalize file formats. Pick one import path and convert everything to that format. If you are using the API, standardize on HTML or Confluence storage format. If native import, convert to .docx.

5. Normalize names. Atlassian warns against special characters in page or attachment names — search and some functions behave unexpectedly. Uploading a file with the same name to the same page creates a new attachment version, not a duplicate.

6. Validate CSV encoding and date formats. Open CSVs in a plain text editor. Confirm UTF-8 encoding (with BOM). Convert all dates to MM/DD/YYYY if targeting Confluence databases, or plan to fix them post-import.

7. Check your attachment budget. The default attachment size limit is 100 MB. If you have larger files, increase the limit before import. For large XML space imports (>100 MB), set up WebDAV. Standard plans have finite storage.

8. Plan for broken links. Internal links from your source platform will not work in Confluence. Build a link mapping table (old URL → new Confluence page ID) and run a find-and-replace pass after import. For Cloud-to-Cloud transfers, Atlassian has a separate link-fixing step for broken tiny URLs, comment links, and Jira work-item links. (support.atlassian.com)

9. Test with a small batch first. Import 10–20 pages into a sandbox space. Check formatting, images, links, and hierarchy. Fix your process before committing to the full import. Atlassian explicitly recommends a dry run and UAT on a test Cloud site before production import.

Real-World Migration Scenarios

Spreadsheet → Confluence Database

Scenario: A team has 2,000 rows of product inventory data in Excel and wants it in a Confluence database.

Decision path:

1. Export Excel as CSV (UTF-8 with BOM).
2. Create the target database with correct field types pre-configured — especially Date fields, which auto-detection handles poorly.
3. Import CSV.
4. Manually fix any string-to-tag misconversions.
5. Entry Link fields cannot come from CSV — you need the API or manual entry for relational lookups.

Gotcha: If the spreadsheet has relational lookups (VLOOKUP references to other sheets), those relationships are gone. Confluence databases support Entry Links between databases, but there is no way to populate them via CSV import.

Blog/Content Archive → Confluence Pages

Scenario: A company is migrating 800 blog posts from a static site (HTML files with embedded images) into Confluence.

Decision path:

1. HTML ZIP import creates pages but destroys hierarchy and may drop images.
2. Better approach: write a Python script that reads each HTML file, downloads referenced images, uploads them to Confluence via the REST API, converts HTML to Confluence storage format, and creates pages with correct parent-child relationships.
3. Handle rate limits with exponential backoff and jitter.
4. Run a link-rewriting pass after all pages are created to fix internal cross-references.

Estimated effort: 2–4 weeks of engineering time for the script, testing, and cleanup. For 800 pages with images, expect the actual API import to take 6–12 hours across multiple rate-limit windows.

Tool-to-Tool Migration (SharePoint → Confluence)

Scenario: An enterprise is moving 15 SharePoint document libraries (3,000+ documents with metadata, permissions, and version history) into Confluence.

Decision path:

1. No native SharePoint importer exists in Confluence.
2. Exporting SharePoint content to HTML or Word loses metadata, permissions, and versions.
3. API-driven migration using SharePoint REST API (export) + Confluence REST API (import) preserves more, but requires custom field mapping, attachment handling, and rate limit management.
4. Version history can be partially preserved by creating multiple page versions via the API (one PUT per version, sequentially).

This is the category of migration where in-house scripting becomes a multi-month project. For a deeper look at this specific path, see our SharePoint to Confluence migration guide.

Modern Workspace App → Confluence

If the source is Notion, start with the native importer and test the exact blocks you use before building scripts. If the source is a generic wiki or knowledge base export, Atlassian does not include specific tools for third-party wiki import — the fallback is plain text, HTML, Confluence storage format, or a custom solution. Attachments may still need manual upload and re-linking regardless of the path.

For Coda-based teams, see our Coda to Confluence migration guide.

When Standard Tools and Scripts Hit the Wall

The pattern across these scenarios is consistent: as migration complexity grows, the gap between what built-in tools offer and what the project requires widens fast.

Standard tools and DIY scripts break when:

• Data spans multiple source formats — some Word, some Markdown, some HTML, some API-only.
• Cross-references and relational links must survive — this requires a two-pass migration (create all pages first, then rewrite all links with correct Confluence page IDs).
• Nested page hierarchies run 4–5 levels deep — native imports flatten everything; API scripts need explicit parent-child mapping logic.
• The migration window is tight — rate limits mean a 10,000-page migration via API can take days. If the business needs it done in hours, you need parallelized, rate-limit-aware infrastructure.
• Attachments number in the thousands — the multi-step upload-link-embed cycle per attachment, multiplied by rate limits, is where most DIY migrations stall or produce broken images.

That transition point is where teams stop asking "how do we upload files" and start asking "how do we preserve structure without weeks of cleanup." Those are different questions.

Complex Migrations: When to Bring in a Dedicated Team

We built ClonePartner for the scenarios where standard tools fail. When a migration involves thousands of pages, mixed source formats, deep hierarchies, and attachment-heavy content, the engineering cost of a DIY approach often exceeds the cost of a managed migration — and takes 5–10x longer.

What we handle that standard tools do not:

• Automated rate limit management — our migration infrastructure tracks Confluence's hourly points quota in real time, distributes requests with jitter, and handles 429s and 503s without manual intervention.
• Parent-child hierarchy preservation — we build the full page tree programmatically, creating parents before children and mapping relationships from the source structure.
• Attachment downloading, uploading, and inline re-linking — each image and file is fetched from the source, uploaded to the correct Confluence page, and embedded in the page body with the correct storage format reference.
• Custom field and metadata mapping — source platform properties (Notion database properties, SharePoint metadata columns, Coda table schemas) are translated into Confluence-native structures including macros.
• Two-pass link rewriting — all internal cross-references are captured in the first pass and rewritten with correct Confluence page IDs in the second.

With 1,200+ migrations completed, we have hit every edge case discussed in this guide and built tooling to handle them. If your internal team has the bandwidth to own this engineering and QA, build it in-house. If not, outsourcing is typically faster and lower-risk than discovering edge cases in production.