# ConvertAPI

> ConvertAPI is a cloud-based file conversion and document management REST API supporting 500+ file formats and 300+ conversion tools. It is designed for developers and enterprises to automate document workflows, perform PDF manipulation, extract data, and integrate file conversion into applications via SDKs, REST API, no-code connectors, or an MCP server.

ConvertAPI is hosted on IBM Cloud across 60+ global data centers with GeoDNS-based routing to the nearest region. It guarantees 99.95% uptime, complies with ISO 27001, SOC 2, HIPAA, and GDPR, and processes all files with AES-256 encryption in transit and at rest. Files can be converted in-memory without storing them, or stored for a maximum period of 3 hours. You can also delete them via REST-API call as soon as you finished processing. 

It is rated highly on Capterra, G2, and Trustpilot and is used by small businesses, mid-sized companies, and large enterprises.

Upon sign up, users will find an interactive dashboard, where they can set up the conversion and it's parameters, try out the result online for evaluation (no coding required), and copy the auto-generated code snippet in their preferred programming language.

---

## Key Resources

- [Homepage](https://www.convertapi.com/)
- [Developer Documentation](https://docs.convertapi.com/)
- [Interactive API Tools on the account dashboard](https://www.convertapi.com/a/api-tools)
- [API Reference](https://www.convertapi.com/api/)
- [Postman Collection](https://www.postman.com/convertapi/convertapi/overview)
- [OpenAPI Schema](https://docs.convertapi.com/docs/openapi-schema)
- [GitHub (SDKs & Libraries)](https://github.com/ConvertAPI)
- [Pricing](https://www.convertapi.com/prices)
- [Status Page](https://status.convertapi.com/)
- [Security & Compliance](https://www.convertapi.com/compliance)
- [Help Center](https://help.convertapi.com/)
- [Changelog](https://docs.convertapi.com/changelog)

---

## Getting Started

New users sign up at https://www.convertapi.com/a/signup and immediately receive an API Token. The free trial includes 250 conversions with no credit card required. After signing up, users select a conversion at https://www.convertapi.com/a/api-tools, configure parameters in the interactive online tool, and receive an auto-generated code snippet for their preferred language. They can try out the conversion on their account dashboard - no coding required.

Base API URL: `https://v2.convertapi.com`

---

## Authentication

All API requests must include a `Authorization: Bearer <token>` header. Two authentication methods are supported:

### API Token (recommended for server-to-server)

Simple, immediately usable tokens created and managed at https://www.convertapi.com/a/authentication. Tokens support environment separation (Production/Development), usage limits, and per-environment consumption tracking.

```bash
curl -X POST https://v2.convertapi.com/convert/docx/to/pdf \
  -H "Authorization: Bearer your_api_token" \
  -F "File=@/path/to/my_file.docx"
```

### JWT Token (advanced security)

JWT tokens provide enhanced security with time-based expiration, IP address restriction, and stateless authentication. JWT tokens can be generated via the ConvertAPI endpoint or self-signed using the API Token secret.

**Generate JWT via API:**

```bash
POST https://v2.convertapi.com/token/jwt
Authorization: Bearer your_api_token
Content-Type: application/json

{
  "Kid": "1fbde8c8-df21-457d-8b8a-3e24ee42a823",
  "ExpiresInSec": 3600,
  "ClientIp": "localhost,197.0.0.1"
}
```

**Self-signed JWT payload:**

```json
{
  "kid": "1fbde8c8-df21-457d-8b8a-3e24ee42a823",
  "exp": 1748344522,
  "iat": 1748344502,
  "nbf": 1748344502,
  "clientIp": "localhost,197.0.0.1"
}
```

Self-signed tokens must use the HS256 algorithm, signed with the API Token secret.

| Use Case | Method |
|---|---|
| Simple server-to-server integration | API Token |
| Frontend or distributed systems | JWT |
| IP-restricted access | JWT |
| Short-lived secure access | JWT |

---

### Master Token

Master token allows you to access administration endpoints, like retrieving user information, consumption, usage logs, etc.

Example usage:

```
GET https://v2.convertapi.com/user
Authorization: Bearer YOUR_MASTER_TOKEN
Accept: application/json
```

### Secret (deprecated)

The secret key is deprecated and should no longer be used. Use API Tokens instead.

## Conversion Endpoint

```
POST https://v2.convertapi.com/convert/{from}/to/{to}
```

Replace `{from}` and `{to}` with the source and target format extensions (e.g., `docx`, `pdf`, `jpg`, `xlsx`).

**Minimal cURL example (DOCX → PDF):**

```bash
curl -X POST https://v2.convertapi.com/convert/docx/to/pdf \
  -H "Authorization: Bearer your_api_token" \
  -F "File=@/path/to/my_file.docx"
```

---

## Request Content Types

ConvertAPI supports three request content types:

### 1. `application/json`

File content is Base64-encoded, provided as a URL, or referenced by an uploaded File ID.

```json
POST https://v2.convertapi.com/convert/doc/to/pdf

{
  "Parameters": [
    {
      "Name": "File",
      "FileValue": {
        "Name": "my_file.doc",
        "Data": "--Base64 encoded file content--"
      }
    }
  ]
}
```

For multi-file converters (e.g., merge PDF), use `FileValues` with a list of `Name`/`Data`, `Url`, or `Id` entries.

### 2. `multipart/form-data` (preferred)

Each parameter is a separate form part. Array parameters use indexed names: `Files[0]`, `Files[1]`, etc.

```
POST https://v2.convertapi.com/convert/doc/to/pdf
Content-Type: multipart/form-data; boundary=----7MA4YWxkTrZu0gW

------7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="File"; filename="my_file.doc"
--FILE DATA--
------7MA4YWxkTrZu0gW--
```

### 3. `application/octet-stream`

Raw file body — most bandwidth-efficient. Requires `Content-Disposition: attachment; filename="my_file.doc"` header. Additional parameters can be passed via URL query string.

### Query Parameters Only (GET or POST)

When a file is accessible by URL or already uploaded by File ID, the entire request can be expressed as query parameters:

```
GET https://v2.convertapi.com/convert/docx/to/pdf?File=http://example.com/myfile.docx&StoreFile=true
```

---

## Response Format

Successful conversions return HTTP 200 with a JSON body:

```json
{
  "ConversionTime": 2,
  "Files": [
    {
      "FileName": "my_file.pdf",
      "FileSize": 523672,
      "FileData": "--Base64 encoded file content--"
    }
  ]
}
```

When `StoreFile=true` is set, the response includes `FileId` and `Url` instead of inline `FileData`:

```json
{
  "ConversionCost": 4,
  "Files": [
    {
      "FileName": "result.jpg",
      "FileSize": 526012,
      "FileId": "d57646acef91155eb7a57376e9cf8d55",
      "Url": "https://v2.convertapi.com/d/d57646acef91155eb7a57376e9cf8d55/result.jpg"
    }
  ]
}
```

Response fields:
- `ConversionTime` – seconds taken; deducted from account balance
- `FileName` – name of converted file
- `FileSize` – size in bytes
- `FileData` – Base64-encoded file content (when not stored)
- `FileId` – unique ID for stored file (valid for 3 hours)
- `Url` – download URL for stored file

---

## Response Codes

| HTTP Code | Code | Description |
|---|---|---|
| 200 | — | Conversion completed successfully |
| 400 | 4000 | Parameter validation error |
| 400 | 4001 | No content disposition provided |
| 400 | 4002 | Bad JSON format |
| 400 | 4005 | Base64 file not found |
| 401 | 4010 | Invalid secret |
| 401 | 4011 | Invalid token |
| 401 | 4012 | Invalid self-generated token |
| 401 | 4013 | Missing credentials |
| 401 | 4014 | Conversion balance exhausted |
| 401 | 4015 | User account inactive |
| 415 | — | Unsupported media type |
| 500 | 5000 | Conversion timeout |
| 500 | 5001 | Conversion failed |
| 500 | 5002 | File is damaged |
| 500 | 5003 | File is password protected |
| 500 | 5004 | No tables found in PDF |
| 500 | 5005 | Cannot delete all pages (must keep at least one) |
| 500 | 5006 | Encryption does not support Unicode passwords |
| 500 | 5007 | Cannot decrypt PDF |
| 500 | 5008 | Unable to access file |
| 500 | 5009 | Invalid File ID |
| 500 | 50013 | No images found in PDF |
| 500 | 50020 | No supported files for extraction |
| 500 | 50050 | Unexpected exception |
| 503 | — | Throttle failure — retry after a few seconds |

---

## OpenAPI Schema

ConvertAPI provides an OpenAPI schema describing all available endpoints.

HTML view:

https://www.convertapi.com/integration/openapi

JSON schema:

https://v2.convertapi.com/info/openapi

### Retrieve OpenAPI schema for a specific conversion

Example: DOCX -> PDF

https://v2.convertapi.com/info/openapi/docx/to/pdf

### List all endpoints that convert to a specific format

Example: all conversions that output PDF

https://v2.convertapi.com/info/openapi/*/to/pdf

### List all conversions available from a specific format

Example: all conversions supported from PDF

https://v2.convertapi.com/info/openapi/pdf/to/*

This wildcard pattern applies to all file formats and supported conversions.

## Discovering API Endpoints Programmatically

Agents and integrations should dynamically discover supported conversions instead of assuming them.

Use the OpenAPI discovery endpoints to inspect available endpoints and conversion capabilities.

---

### Check if a conversion is supported

Endpoint:

GET https://v2.convertapi.com/info/canconvert/{from}/to/{to}

Example:

GET https://v2.convertapi.com/info/canconvert/doc/to/pdf

This endpoint returns whether a specific conversion is supported and can be used before performing a conversion.

---

## File Storage

Files can be uploaded once and reused across multiple conversions without re-uploading. Stored files are retained for up to 3 hours and can be deleted via REST-API call manually at any time.

### Upload (raw binary — preferred)

```
POST https://v2.convertapi.com/upload
Content-Disposition: inline; filename="my_file.doc"
--FILE DATA--
```

Response:
```json
{
  "FileId": "25811safe8e61dd3f51ef00ee5f58b92",
  "FileName": "my_file.doc",
  "FileExt": "doc"
}
```

### Upload (multipart/form-data)

```bash
curl -F 'file=@/path/to/my_file.doc' https://v2.convertapi.com/upload
```

### Upload from Remote URL

```
POST https://v2.convertapi.com/upload?url=http%3A%2F%2Fexample.com%2Ffile.doc&FileName=my_file.doc
```

Optional `HeaderName`/`HeaderValue` parameters can be added to authenticate against third-party systems (e.g., private Google Drive files).

### Use Uploaded File in Conversion

```
GET https://v2.convertapi.com/convert/doc/to/pdf?File=25811safe8e61dd3f51ef00ee5f58b92
```

### Download Uploaded File

```
GET https://v2.convertapi.com/d/25811safe8e61dd3f51ef00ee5f58b92
```

### Delete Uploaded File

```
DELETE https://v2.convertapi.com/d/25811safe8e61dd3f51ef00ee5f58b92
```

---

## Conversion Workflows

Multi-step workflows allow chaining conversions without additional network overhead. Use `StoreFile=true` in each step and reference intermediate results via `FileId` (not URL) in subsequent steps.

**Example: PDF → JPG → ZIP**

Step 1: Convert PDF to JPG (store result)

```json
POST https://v2.convertapi.com/convert/pdf/to/jpg
{
  "Parameters": [
    { "Name": "File", "FileValue": { "Name": "my_file.pdf", "Data": "--Base64--" } },
    { "Name": "StoreFile", "Value": true }
  ]
}
```

Step 2: ZIP all resulting JPGs by FileId

```json
POST https://v2.convertapi.com/convert/any/to/zip
{
  "Parameters": [
    {
      "Name": "Files",
      "FileValues": [
        { "Id": "dfaca13bc861c529d00d22cfacf71c63" },
        { "Id": "d57646acef91155eb7a57376e9cf8d55" },
        { "Id": "4c78541c67d66045dfe5378dc8852ae5" }
      ]
    },
    { "Name": "StoreFile", "Value": true }
  ]
}
```

> Important: Always use `FileId` (not `Url`) when referencing intermediate results in a workflow.

---

## Throttle and Fallback

Business and Enterprise plans have no hard concurrency limits, but heavy load may trigger a `503 Service Unavailable` response.

Recommended retry pattern:
1. Wait 5 seconds → retry
2. Wait 10 seconds → retry
3. Wait 15 seconds → retry

```
POST /convert/docx/to/pdf → 503
→ Wait 5s → retry
→ Wait 10s → retry
→ Wait 15s → retry → 200 OK
```

---

## User Info Endpoint

```
GET https://v2.convertapi.com/user
Authorization: Bearer YOUR_MASTER_TOKEN
```

Response:
```json
{
  "Active": true,
  "FullName": "Name Surname",
  "Email": "user@example.com",
  "ConversionsTotal": 5000,
  "ConversionsConsumed": 1642
}
```

### Usage Statistics

```
GET https://v2.convertapi.com/user/statistic?startDate=2024-01-01&endDate=2024-02-01
Authorization: Bearer YOUR_MASTER_TOKEN
Accept: application/json   (or text/csv)
```

---

## MCP Server

ConvertAPI provides a Model Context Protocol (MCP) server in both hosted and self-hosted versions. The MCP server exposes document converters and tools as discoverable tools for MCP-compatible AI clients including AI agents, IDE extensions, and desktop applications.

Hosted MCP URL: https://mcp.convertapi.io
Landing page: https://www.convertapi.com/integration/mcp-server
Documentation: https://docs.convertapi.com/docs/mcp-server

---

## SDKs and Client Libraries

Official SDKs are available for the following languages (all open-source on GitHub at https://github.com/ConvertAPI):

| Language | Repository |
|---|---|
| PHP | convertapi-php |
| Python | convertapi-python |
| Node.js | convertapi-node |
| Java | convertapi-java |
| .NET (C#) | convertapi-dotnet |
| Ruby | convertapi-ruby |
| Go | convertapi-go |
| Swift | convertapi-swift |
| JavaScript (browser) | convertapi-library-js |
| CLI | convertapi-cli |

**JavaScript (browser) example:**

```javascript
import ConvertApi from 'convertapi-js'
let convertApi = ConvertApi.auth('your_api_token')

let params = convertApi.createParams()
params.add('file', fileInput.files[0])
let result = await convertApi.convert('docx', 'pdf', params)
let url = result.files[0].Url
```

**With additional parameters (PDF → JPG, scaled):**

```javascript
params.add('ScaleImage', 'true')
params.add('ScaleProportions', 'true')
params.add('ImageHeight', '300')
params.add('ImageWidth', '300')
let result = await convertApi.convert('pdf', 'jpg', params)
```

**Using a regional endpoint:**

```javascript
let convertApi = ConvertApi.auth('api-token', 'https://eu-v2.convertapi.com/')
```

---

## No-Code Integrations

ConvertAPI provides native connectors for the following no-code and automation platforms:

- **Zapier** – connect ConvertAPI to Zaps using the API token
- **Make (Integromat)** – upload files and trigger conversions via the ConvertAPI Make module
- **n8n** – file conversion nodes
- **Bubble** – no-code app integration
- **ChatGPT** – via MCP or plugin
- **PowerAutomate** – no-code app integration

and more, like Workato, Latenode, Copilot Studio, Power Apps, Ottokit, Azure Logic Apps, Mokedo, etc.

For all of these platforms: obtain the API Token value from https://www.convertapi.com/a/authentication and enter it when creating a connection in the workflows.

For platforms that support OAuth (for example Zapier), user can authenticate using ConvertAPI OAuth server.

---

## Quick Tips

### Conversion Using URL Only (no file upload required)

```
GET https://v2.convertapi.com/convert/docx/to/pdf
  ?File=http://example.com/myfile.docx
  &StoreFile=true
```

### Conversion Using JSON

Send JSON body with `application/json` content type. Files are Base64-encoded or referenced by URL/FileId.

### View File In a Browser

Append the File ID to the download endpoint. Stored files are accessible via their URL for up to 3 hours.

### Virtual File Server

ConvertAPI can serve as a temporary file server. Files uploaded or produced by conversions (with `StoreFile=true`) are accessible via their URL or FileId for up to 3 hours.

### Web to PDF: Headers and Footers

When converting web pages or HTML to PDF, custom headers and footers can be injected using dedicated conversion parameters. See: https://docs.convertapi.com/docs/web-to-pdf-headers-and-footers

### Dynamic Converters

Converter information and parameters are discoverable programmatically via the dynamic converters endpoint. See: https://docs.convertapi.com/docs/converter-information

---

## Supported Format Categories

ConvertAPI organizes its tools into the following categories:

- **PDF Tools** – Generate, modify, compress, protect, merge, split, rotate, watermark, repair, redact, print-preflight and prepare PDFs for long-term storage using PDF/A or PDF/UA
- **Security** – Encrypt/decrypt with AES-256, password-protect, and redact documents (including AI-driven redaction)
- **Extract** – Extract text, images, tables, and metadata from PDF and other documents; includes OCR support
- **Optimize** – Compress files and reduce size for sharing or archiving
- **Document Builder** – Dynamic document generation from templates
- **MS Office** – Convert Word (DOC, DOCX), Excel (XLS, XLSX), PowerPoint (PPT, PPTX) to PDF/A, images, and vice versa
- **Image** – Convert between image formats (JPG, PNG, TIFF, BMP, WebP, SVG, and more); scale, crop, and transform images
- **Email** – Convert email files (EML, MSG), extract information and attachments, convert to PDF or other formats
- **Document Converters** – Convert between hundreds of document types including HTML, RTF, ODF, CSV, XML, and more

Notable supported format pairs include (non-exhaustive):
- DOCX → PDF, PDF/A, HTML, JPG, PNG, TXT
- XLSX → PDF, CSV, HTML
- PPTX → PDF, JPG, PNG
- PDF → DOCX, JPG, PNG, TXT, HTML, ZIP
- HTML → PDF, JPG, PNG
- Images → PDF, JPG, PNG, TIFF, WebP
- EML/MSG → PDF
- Any → ZIP

---

## Server Locations

Requests are automatically routed by GeoDNS to the nearest available data center.

| Region | Domain | Routing |
|---|---|---|
| World Wide (default) | v2.convertapi.com | GEO (auto) |
| Europe – London, UK | uk-v2.convertapi.com | Direct |
| Europe EU – Amsterdam / Frankfurt | eu-v2.convertapi.com | Direct |
| US East – Washington DC | us-v2.convertapi.com | Direct |
| US West – San Jose | us-v2.convertapi.com | Direct |
| North America – Toronto | ca-v2.convertapi.com | Direct |
| Southeast Asia – Singapore | as-v2.convertapi.com | Direct |
| East Asia – Tokyo | jp-v2.convertapi.com | Direct |
| Oceania – Sydney | au-v2.convertapi.com | Direct |

The Europe (EU) instance (eu-v2.convertapi.com) is fully GDPR compliant. Additional regions (Paris, São Paulo, Chennai, Hong Kong, Seoul, etc.) can be set up on request.

To force a specific region, replace the base URL in all API calls:
```
https://eu-v2.convertapi.com/convert/docx/to/pdf
```

---

## Security and Compliance

- **Encryption in transit:** TLS for all API communications
- **Encryption at rest:** AES-256 for all stored files
- **Automatic file deletion:** Files are deleted immediately after processing by default; configurable retention policies available
- **In-memory conversion:** Supported — files never written to disk
- **Standards:** ISO 27001 certified, HIPAA compliant, GDPR compliant
- **BAA:** Business Associate Agreement supported (for HIPAA-covered entities)
- **Security audits:** Continuous monitoring, third-party assessments, and regular patches
- **Scoped API keys:** Per-environment tokens with usage limits

Security details: https://www.convertapi.com/compliance

---

## Pricing Overview

- **Free trial:** 250 conversions, no credit card required
- **Paid plans:** Billed by conversion count per month/year; plans scale from small to enterprise volumes
- **Overage:** Exceeding the plan limit incurs overage charges (not automatic cutoff by default)
- **Business/Enterprise:** Custom feature requests, Signed contracts, No hard concurrency limits; priority processing

Current pricing: https://www.convertapi.com/prices

---

## Team Management

Account owners can invite team members at https://www.convertapi.com/a/team-members, assign roles, and control access levels per member. API tokens can be scoped per environment to separate Production and Development consumption.

---

## Architecture

ConvertAPI is built on IBM Cloud infrastructure with auto-scaling to handle variable load. The grid scales to maintain the 99.95% uptime SLA. Architecture schema: https://docs.convertapi.com/docs/architecture-schema

---

## Common Use Cases

- Generating invoices and contracts from DOCX templates → PDF
- Converting user-uploaded Office files to PDF for web display
- Extracting text from PDFs for search indexing or AI pipelines
- Producing thumbnails and preview images from documents
- Exporting reports to PDF for download
- Merging multiple PDFs into a single document
- Redacting sensitive information from documents (AI-driven redaction available)
- Converting emails (EML/MSG) to PDF for archiving
- Building book-on-demand or print-ready PDF workflows
- Integrating document conversion into CRM or ERP systems

---

## Support

- Help Center: https://help.convertapi.com/
- Support contact: https://www.convertapi.com/support
- Discussions: https://docs.convertapi.com/discuss
- System status: https://status.convertapi.com/