← PDFtoSCAN Banye / Nweta igodo API

Akwụkwọ API

Use the PDFtoSCAN conversion from your applications. All API requests require an API key (obtain one after registration).

Base URL

All endpoints are relative to:

https://pdftoscan.com/api/v1

Authentication

Include your API key in every request using one of these methods:

Header Header X-API-Key: your-api-key
Header Header Authorization: Bearer your-api-key

To get an API key: registration, then in your Dashboard generate a new key. The key is shown only once—store it securely.

Convert to scanned look

POST /convert.php

Upload a PDF or image, or send a file URL, and receive a PDF with a scanned appearance (tilt, noise, optional dirty background, optional A4).

Request

Method: POST
Content-Type: multipart/form-data (or application/x-www-form-urlencoded when using file_url only you can use application/x-www-form-urlencoded)

Parameters

Parameter	Type	Required	Description
`file` or `pdf`	file	No	PDF, JPG, PNG, TIFF, or WebP file to convert (upload). Use either file or file_url.
`file_url`	string	No	HTTP(S) URL of a PDF or image to convert. Use either file upload or file_url (max 50 MB, 30 s timeout).
`color_mode`	string	No	color or bw. Default: bw (black & white).
`rotate`	number	No	Page tilt in degrees (-1.5 to 1.5). Default: 0.
`noise`	number	No	Noise amount 0–1. Default: 0.1 (10%).
`dirty_background`	string	No	1 (default) to show dirty black edges, 0 to disable.
`force_a4`	string	No	1 (default) to fit output to A4, 0 to keep original size.

Response

Success (200): Response body is the PDF file. Save or stream the binary content.

Error (4xx/5xx): JSON body: {"ok": false, "error": "Error message"}

Status codes

Code	Meaning
200	Success — response is the PDF.
400	Bad request — missing file, wrong format, or upload error.
401	Unauthorized — missing or invalid API key.
405	Method not allowed — use POST.
500	Server error — conversion failed.
503	Service unavailable — conversion not available on server.

Examples

cURL

Upload a file:

curl -X POST "https://pdftoscan.com/api/v1/convert.php" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "color_mode=bw" \
  -F "force_a4=1" \
  -o scanned.pdf

Or send a file URL:

curl -X POST "https://pdftoscan.com/api/v1/convert.php" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "file_url=https://example.com/document.pdf" \
  -d "color_mode=bw" \
  -d "force_a4=1" \
  -o scanned.pdf

JavaScript (fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('color_mode', 'bw');
formData.append('force_a4', '1');

const response = await fetch('https://pdftoscan.com/api/v1/convert.php', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(err.error || 'Request failed');
}
const blob = await response.blob();
// e.g. save or open blob as PDF

Python

import requests

url = 'https://pdftoscan.com/api/v1/convert.php'
headers = {'X-API-Key': 'YOUR_API_KEY'}
files = {'file': open('document.pdf', 'rb')}
data = {'color_mode': 'bw', 'force_a4': '1'}

r = requests.post(url, headers=headers, files=files, data=data)

if r.status_code != 200:
    print(r.json().get('error', 'Error'))
else:
    with open('scanned.pdf', 'wb') as f:
        f.write(r.content)

CORS

Requests from browsers are allowed from any origin. Preflight OPTIONS requests are supported.

Usage and limits

Each conversion is counted per API key. In your dashboard you can see total usage and usage over the last 7 and 30 days. There are no built-in rate limits; server upload and resource limits may apply.

Supported formats

Input: PDF, JPG, JPEG, PNG, TIFF, WebP.

Output: Always PDF (with scanned look).