API Integration Guide for Developers

How the iFileConverter API Works

The API follows a straightforward pattern: authenticate with a token, POST a file to the conversion endpoint, receive a job reference, and either poll for status or wait for a webhook callback. For most use cases — invoice pipelines, document archives, automated report generation — this covers everything you need.

Authentication: Tokens, Not Passwords

The API uses token-based authentication. Each account has a token balance; each conversion deducts from that balance based on file size and output format. This model has two practical implications for developers:

• Your integration code should check the token balance before submitting large batches. A job that runs out of tokens mid-batch will leave you with partial output and no clear indication of where it stopped.
• Store your API key in an environment variable, never in source code. A key committed to a public repository and later rotated still appears in git history — treat it the same way you would treat a database password.

Synchronous vs. Asynchronous Conversion

Short conversions (single-page PDFs, small DOCX files) typically complete within a few seconds and can be handled synchronously: POST the file, await the response, download the result. For larger documents, a polling approach is more reliable:

1. POST the file — receive a job ID in the response.
2. GET /api/convert/status/:jobId every 2–5 seconds until status is completed or failed.
3. On completed, download from the returned URL. The file is available for 24 hours before automatic deletion.
4. On failed, read the error field — common causes are unsupported format combinations, encrypted inputs, or token exhaustion.

If your infrastructure supports inbound webhooks, prefer that over polling. Register a callback URL on your account; the API will POST the result payload to that URL when the job finishes, eliminating the need for polling loops entirely.

Error Codes Worth Knowing

Most API errors fall into three categories:

• 4xx client errors — invalid format, file too large, insufficient tokens. These are fixable on your side before retrying.
• 5xx server errors — transient infrastructure issues. Implement exponential backoff: wait 1s, then 2s, then 4s before giving up. Do not retry immediately in a tight loop.
• Conversion failures (status failed with 200 HTTP) — the API call succeeded but the document could not be converted. Encrypted PDFs, severely corrupted files, and unsupported format pairs fall here. Log the job ID and error message; do not retry without addressing the root cause.

A Practical Example: PDF Invoice Pipeline

A common real-world use case is extracting data from incoming PDF invoices into a spreadsheet for accounting. The integration pattern looks like this: watch an email inbox or upload folder for new PDFs → POST each to the conversion API with target format XLSX → on completion, parse the XLSX for line items, totals, and invoice numbers → write to your accounting database. The 24-hour file retention window means you should download and store the XLSX immediately after conversion rather than relying on the URL remaining valid.

Rate Limiting and Throughput

The API applies per-account rate limits. If your integration submits jobs faster than the limit allows, you will receive 429 Too Many Requests responses. The response includes a Retry-After header — respect it rather than continuing to hammer the endpoint. For high-volume pipelines, queue jobs on your side and submit them at a controlled rate rather than firing all requests simultaneously.