PDF Split API - Split or Extract Pages by Range, Even/Odd, or Last Page
A 300-page scan of mixed invoices is useless to your accounting system until every invoice is its own file. The PDF Split & Extract Pages API breaks a PDF apart or pulls out exactly the pages you need through two REST endpoints, processed asynchronously so large jobs never block a request thread. Send page ranges, individual page numbers, or even/odd/last selections, and get back one file per range, a single combined document, or a ZIP of individual pages: fonts, images, and layout untouched. Built for developers automating invoice processing, legal document workflows, and document management pipelines. Start with 10,000 free credits, no credit card, and credits are only charged on successful responses.
Features
Custom Ranges & Selection Keywords
Thepages parameter accepts individual numbers, ranges, and the keywords even, odd, all, and last, mixed in any order, 1-5,10,15-last is a valid selection. On the split endpoint, each repeated pages parameter produces a separate output file, so a single request can cut one document into any number of parts. Use it to burst a report into chapters or isolate every odd page of a duplex scan.Separate or Combined Extraction Output
The extract endpoint'sseparated parameter controls packaging: with separated=false (the default), every selected page merges into one new PDF; with separated=true, each page is saved as an individual file inside a ZIP archive. That flexibility makes it a practical PDF extract pages API for both single-document deliverables and page-level processing. Use it to build one clean signature packet, or to feed pages one at a time into an OCR queue.Asynchronous Processing
Every request returns ataskId immediately instead of holding the connection open while the document processes. Poll the task-status endpoint to track progress and collect output file IDs when the job completes, and use the inputIds in the response to reference your uploaded source files. Use it to keep request threads free while large documents process in the background, no timeout tuning required.Webhook Notifications with HMAC Verification
Addwebhook_url to any request and the API POSTs the result to your endpoint the moment processing completes or fails. Delivery is attempted up to 3 times, so a transient receiver error doesn't lose the event. Set a custom X-Webhook-Authorization header, enable webhook_failure_notification for email alerts, and verify every payload against the HMAC-SHA256 signature computed from the request body with your API key. Use it for event-driven pipelines where documents must move the moment they are ready.Split Stored Files Without Re-Uploading
Pass afile_id instead of a multipart upload to split or extract from a file already on APIFreaks servers, the output of a previous merge, compress, or upload call. Files are retained for up to 30 days depending on your plan, so multi-step pipelines never transfer the same bytes twice. Use it to chain PDF operations without re-uploading large documents at every step.1GB Payload per Request
Each request accepts a payload of up to 1GB, which covers scanned archives, image-heavy reports, and high-resolution print files that browser-based splitters reject. Combined with asynchronous processing, oversized documents run in the background with no connection-timeout risk on your side. Use it to burst large batch scans straight from a document-intake pipeline instead of pre-cutting them by hand.
Zero Data Retention on Request
Enabledestroy and your input and output files are deleted immediately instead of being held for the standard retention window. File-status calls report creation and deletion timestamps, so you can audit exactly when data left the platform. Use it for compliance-sensitive workloads (legal, healthcare, and financial documents) where storage minimization is a hard requirement rather than a preference.No Quality Loss
Output files keep the source document's pages exactly as authored: fonts, embedded images, vector graphics, page dimensions, and layout carry over with no recompression and no downsampling. Splitting and extraction are structural operations, not re-renders, so a page in the output is identical to the same page in the input. Use it when output must stay print-ready or legally faithful: court filings, signed contracts, archival records.
Built for These Use Cases
Invoice and statement bursting
A nightly billing run produces one PDF containing hundreds of invoices. One split PDF REST API call per batch cuts it into per-invoice files your accounting system can ingest. Each range you define becomes its own document. Run it as the PDF splitter API behind your ERP intake queue.
Contract page extraction
Pull signature and exhibit pages from executed contracts into one clean packet, or as individual files for review tools. Legal ops teams run this page extraction API pattern after every signing round, routing only the pages that matter to counsel and the deal record.
Report and chapter distribution
One split PDF API call turns a master report into per-chapter files, so each audience receives only its section. Pair it with the Merge PDF API to re-assemble custom document packs per recipient from the same source material.
Scan separation and archive prep
Batch scanners produce one oversized PDF per tray. Split it into logical documents at known page boundaries, then pass the outputs to the PDF Compress API to shrink them before they enter long-term storage.
Split PDF API
API Endpoint
$ pip install requestsimport requests
url = "https://api.apifreaks.com/v1.0/pdf/split?pages=1-5&output=split_document"
payload = {}
files=[
('file',('file.pdf',open('/path/to/file.pdf','rb'),'application/pdf'))
]
headers = {
'X-apiKey': 'API-KEY'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
Extract Pages API
API Endpoint
$ pip install requestsimport requests
url = "https://api.apifreaks.com/v1.0/pdf/extract-pages?pages=1%2C5%2C10-15&output=extracted_pages"
payload = {}
files=[
('file',('file.pdf',open('/path/to/file.pdf','rb'),'application/pdf'))
]
headers = {
'X-apiKey': 'API-KEY'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
Utility & Resource APIs
Use these endpoints to manage files and check task status.
Task Status API
task_id. The response includes creation and expiry timestamps to help you track result availability, along with specific error details if a task fails. Results are retained for up to 7 days, depending on the operation.File Status API
file_id. Returns details including file name, size, type, and creation/deletion timestamps. Generated or uploaded files are retained up to 30 days based on user's plan, unless destroy is enabled to delete them immediately. You can use this endpoint to check if the file has expired using its file_id.File Download API
PDF Delete API
Files List API
File Upload API
multipart/form-data request. Each file receives a unique file_id that can be used with the PDF APIs.Upload Binary API
file_id for uses with the PDF APIs.How-To-Guides
Split PDF into Pages
You have one oversized PDF and downstream systems that each need their own file. This walkthrough runs the full job: upload the document and split it at the ranges you define, poll the task status, and download each output file. The same three steps sit behind any splitting workflow you automate. The only thing that changes is the page selection.
Step 1: Upload and Split PDF
Kick off the job by POSTing to /pdf/split. Attach the document as a multipart file field or reference a stored file_id, and pass one pages parameter per output you want. Each range becomes its own PDF. The response returns a taskId for tracking and inputIds confirming the source file that entered the job.
# Standard Response { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f" ] } # Response with destroy=true (No File IDs as they are deleted right away) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d" }curl -X POST "https://api.apifreaks.com/v1.0/pdf/split?pages=1-5&pages=10-15&pages=20-last&output=split_document" \ -H "X-apikey: YOUR_API_KEY" \ -F "file=@/path/to/document.pdf"
Notes:
- The API accepts only one PDF file per request (multipart file takes priority over file_id)
- Use the Upload Binary API to significantly speed up large file uploads.
- Multiple
pagesparameters create multiple output files - Each page range generates a separate PDF in the output
- Use
pages=allto split PDF into individual pages - Use the
destroy=trueparameter to delete input file after split completes (returns onlytaskId) - File IDs must reference valid, active files stored on the API Freaks server. You can verify if a file is still available using the File Status API
Step 2: Check Task Status
The split runs in the background, so your request thread is already free. Poll the Task Status API with your taskId until it reports completed. The response carries the output file references you'll download in the next step, and a failed status carries the error details your retry logic needs.
# Response (completed) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "status": "completed", "createdAt": "2025-01-26 10:30:00", "outputUrls": [ "https://api.apifreaks.com/v1.0/pdf/resource/download?resource_id=9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f" ], "outputFileId": [ "9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f" ], "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f" ], "expiresAt": "2025-01-27 10:30:00" }curl -X GET "https://api.apifreaks.com/v1.0/pdf/task-status?task_id=04a06cd5-158d-4191-a45b-6f58249c599d" \ -H "X-apikey: YOUR_API_KEY"
# Response (failed) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "status": "failed", "createdAt": "2025-01-26 10:30:00", "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f" ], "error": "Invalid PDF File", "message": "The provided file is not a valid PDF file.", "expiresAt": "2025-01-27 10:30:00" }curl -X GET "https://api.apifreaks.com/v1.0/pdf/task-status?task_id=04a06cd5-158d-4191-a45b-6f58249c599d" \ -H "X-apikey: YOUR_API_KEY"
Step 3: Download Split PDFs
Fetch each output through the File Download API using its file ID. Multi-range jobs arrive as separate PDFs, delivered as a ZIP archive when the job produces several files. Store the IDs instead of downloading if the next step is another PDF operation.
curl -X GET "https://api.apifreaks.com/v1.0/pdf/resource/download?resource_id=9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f" \ -H "X-apikey: YOUR_API_KEY" \ --output split_document.pdf
Extract Pages from PDF
A 90-page contract goes to counsel, but they only need the signature and exhibit pages. This walkthrough pulls the exact pages you list into a new PDF: one combined file by default, or individual files packaged in a ZIP when your pipeline needs page-level output.
Step 1: Upload and Extract Pages
POST to /pdf/extract-pages with the required pages selection. The default returns one combined PDF of the selected pages; set separated=true to receive each page as its own file in a ZIP. Tracking and download then follow the same Step 2 and Step 3 as the split flow above.
# Standard Response { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f" ] } # Response with destroy=true (No File IDs as they are deleted right away) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d" }curl -X POST "https://api.apifreaks.com/v1.0/pdf/extract-pages?pages=1,5,10-15,20&output=extracted_pages" \ -H "X-apikey: YOUR_API_KEY" \ -F "file=@/path/to/document.pdf"
Notes:
- The API accepts only one PDF file per request (multipart file takes priority over file_id)
- For faster uploads of large files, Upload Binary API can be used.
- The
pagesparameter is required and defines which pages to extract. - When
separated=false(default), all extracted pages are combined into one PDF and forseparated=true, each page is saved as an individual PDF in a ZIP file. - Extract custom PDF page ranges using any combination of numbers and ranges.
- Use the
destroy=trueparameter to delete input file after extraction completes (returns onlytaskId). - File IDs must reference valid, active files stored on the API Freaks server. You can verify if a file is still available using the File Status API.
Webhook Support
Polling wastes cycles when documents finish on their own schedule. Provide a webhook with your request and the API calls your endpoint the moment a task completes or fails, with an HMAC signature you can verify before trusting the payload.
Get automatic notifications when your task completes instead of polling the task status endpoint. Good for event-driven applications and real-time document processing.
Add webhook_url to your request. We'll send a POST request to this URL when the task finishes (either completed or failed).
See the Complete Webhook Example section below for a full demonstration including custom authorization headers.
Webhook Delivery
Webhook delivery will be attempted up to 3 times. If all retries fail and webhook_failure_notification is enabled, we'll send an email notification to the requesting user or their organization admin.
Custom Authorization Header
Use X-Webhook-Authorization to add a custom header to webhook requests for endpoint security.
Format: Key:Value
Example: If you send Authorization:Bearer token123, the webhook request will include: Authorization: Bearer token123
See the Complete Webhook Example below for a full demonstration.
Complete Webhook Example
Here's a complete example showing webhook integration with custom authorization header and failure notifications:
# Response { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "inputIds": [ "566dc743-d8fe-4943-8cef-61e5d3d6096c" ] }curl -X 'POST' \ 'https://api.apifreaks.com/v1.0/pdf/split?webhook_url=https://yourdomain.com/webhook/pdf-split&webhook_failure_notification=true' \ -H 'X-apiKey: YOUR_API_KEY' \ -H 'X-Webhook-Authorization: Authorization:Bearer token123' \ -F 'file=@/path/to/document.pdf'
Webhook Request Format
When your task completes, we send a POST request to your webhook_url with these headers:
| Header | Description |
|---|---|
Content-Type | Always application/json |
X-Signature | HMAC-SHA256 signature of the request body using your API key. Use this to verify the payload is authentic. |
| Custom Header | (If provided) Your custom header from X-Webhook-Authorization |
Webhook Response
The webhook payload contains the same response structure as the Task Status API endpoint when checked for the task ID.
Verifying Webhook Authenticity
Use the X-Signature header to verify webhook requests actually came from API Freaks and weren't tampered with.
How the signature works:
- We compute an HMAC-SHA256 hash of the request body using your API key as the secret
- We Base64-encode the result
- We send this as the
X-Signatureheader value
To verify the webhook:
- Take the raw payload body (JSON string exactly as received without parsing it)
- Compute HMAC-SHA256 of the payload using your API key as the secret
- Base64-encode the result of the hash
- Compare with the
X-Signatureheader value
Important: Don't transform or process the raw request body before verification. Adding whitespace or other formatting creates a different signature and verification will fail.
Frequently Asked Questions
/v1.0/pdf/split) produces one output file per pages range you send. Repeat the parameter and each range becomes its own PDF. The extract-pages endpoint is the extract pages from PDF API path: it pulls every page you list into a single new PDF by default, or into individual files in a ZIP when separated=true. Use split to divide a document; use extract to lift pages out of one.5), ranges (10-15), the keywords even, odd, all, and last, and any mixed combination such as 1-5,10,15-last. On the extract-pages endpoint, pages is required.file upload takes priority over file_id if both are sent. For multiple documents, send parallel requests; the asynchronous model returns a taskId for each immediately, so concurrency is limited by your plan, not by connection handling.webhook_url to your request and the API POSTs the outcome to your endpoint when processing completes or fails, retrying delivery up to 3 times. You can set a custom X-Webhook-Authorization header, enable webhook_failure_notification for email alerts, and verify each payload using the HMAC-SHA256 signature computed from the request body with your API key.file_id reference to a stored file. See the pricing section for how request size affects credit cost.X-AF-Credits-Cost response header shows the exact cost of each call, and the pricing section below includes a per-endpoint estimation calculator.Pricing
To use this PDF Split API, API credits are required. Charges apply only for successful queries, defined by a 2xx status code. If a request results in a 4xx or 5xx status code, no credits will be deducted, and any credits already charged will be refunded. In the event of a Task Processing Error, a maximum of 200 credits will be refunded. Surcharges for additional file sizes are non-refundable.
For each successful request, 200 credits will be charged. 1 extra credit will be charged per MB beyond 50 MB.
Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.