Merge, split and modify PDF documents with the PDFCrowd Go client. The client handles communication with the API, while processing runs on PDFCrowd's servers.
Add the Go client to your module with go get, or see
other installation options.
go get github.com/pdfcrowd/pdfcrowd-go
You can run the examples below with the displayed API credentials. Update the input URLs and filenames as needed.
Merge a cover, proposal, price list and contact page in that order, then save the PDF locally as offer.pdf:
package main import ( "log" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") client.AddPdfFile("cover.pdf") client.AddPdfFile("proposal.pdf") client.AddPdfFile("price.pdf") client.AddPdfFile("contact.pdf") err := client.ConvertToFile("offer.pdf") checkError(err) } func checkError(err error) { if err != nil { log.Fatal(err) } }
Conversion methods return an error if the input or settings are invalid, or if the conversion fails. See Handle Errors.
Place the first page of watermark.pdf over every page of proposal.pdf and save the PDF locally as company_offer.pdf:
package main import ( "log" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") client.SetPageWatermark("watermark.pdf") client.AddPdfFile("proposal.pdf") err := client.ConvertToFile("company_offer.pdf") checkError(err) } func checkError(err error) { if err != nil { log.Fatal(err) } }
Extract page 3 and pages 7 through the end of a PDF, then save them locally as output.pdf:
package main import ( "log" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") client.SetAction("extract") client.SetPageRange("3,7-") client.AddPdfFile("13_pages.pdf") err := client.ConvertToFile("output.pdf") checkError(err) } func checkError(err error) { if err != nil { log.Fatal(err) } }
Pass your PDFCrowd username and API key to
NewPdfToPdfClient.
Find your credentials on the API Keys page.
Add each PDF before calling a conversion method. The default action joins the documents in the order they were added.
| Input | Method |
|---|---|
| Local PDF file | AddPdfFile() |
| PDF bytes in memory | AddPdfRawData() |
For encrypted input PDFs, set the document password with SetInputPdfPassword() before conversion.
This is separate from your API key and the passwords used to protect the output PDF.
Read two local PDFs as bytes, merge them in order, and save the result locally as merged.pdf:
package main import ( "log" "os" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") cover, err := os.ReadFile("cover.pdf") checkError(err) proposal, err := os.ReadFile("proposal.pdf") checkError(err) client.AddPdfRawData(cover) client.AddPdfRawData(proposal) err = client.ConvertToFile("merged.pdf") checkError(err) } func checkError(err error) { if err != nil { log.Fatal(err) } }
Set conversion options on the client before calling a conversion method.
For example, client.SetLinearize(true) optimizes the output PDF for progressive loading.
Common settings are listed below. See the method reference for all available options or browse Go examples.
| Purpose | Methods |
|---|---|
| Join, interleave, extract or delete pages | SetAction(), SetPageRange() |
| Watermark and background | SetPageWatermark(), SetPageBackground(), SetMultipageWatermark(), SetMultipageBackground() |
| Optimize for progressive loading | SetLinearize() |
| Output protection | SetEncrypt(), SetUserPassword(), SetOwnerPassword(), SetNoCopy(), SetNoPrint() |
| Metadata and attachments | SetTitle(), SetAuthor(), SetUseMetadataFrom(), AddAttachment() |
Use "extract" with a page range to keep selected pages, or "delete" to remove them.
The "shuffle" action interleaves pages from the input PDFs.
After adding the inputs and settings, choose how to receive the PDF:
| Output | Method |
|---|---|
| Local file | Convert() + os.WriteFile() |
| Byte slice | Convert() |
io.Writer | ConvertToStream() |
The examples receive PDF bytes and use os.WriteFile to save them,
checking conversion and write errors separately. An existing destination file is overwritten.
This example merges two PDFs, receives the result as a
[]byte and saves it as merged.pdf:
package main import ( "log" "os" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") client.AddPdfFile("cover.pdf") client.AddPdfFile("proposal.pdf") result, err := client.Convert() checkError(err) checkError(os.WriteFile("merged.pdf", result, 0644)) } func checkError(err error) { if err != nil { log.Fatal(err) } }
See the reference for file and stream handling.
When serving the result from a web application, use Content-Type: application/pdf.
Conversion methods return an error. API and validation errors have the
type pdfcrowd.Error; local file and
connection failures can return other error types.
This example merges two PDFs, logs any error,
and uses errors.As to read the HTTP status and reason code when available:
package main import ( "errors" "log" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") client.AddPdfFile("cover.pdf") client.AddPdfFile("proposal.pdf") err := client.ConvertToFile("merged.pdf") checkError(err) } func checkError(err error) { if err != nil { var apiError pdfcrowd.Error if errors.As(err, &apiError) { log.Printf("Status: %d; reason: %d", apiError.GetStatusCode(), apiError.GetReasonCode()) } log.Fatal(err) } }
See the error-object reference for status, reason, and message accessors.
Error() returns the complete error message, including available status and reason codes.
| Status | What it means | What to do |
|---|---|---|
400 | Invalid input, settings, or conversion failure | Read the reason code and correct the input or settings. |
401 | Missing credentials or an inactive license | Check your username, API key, and license status. |
403 | Suspended service or no credits remaining | Check your account and available credits. |
413 | Upload exceeds the 300 MB limit | Reduce the upload size. |
429 | Request rate limit reached | Wait and reduce the rate of new requests. |
430 | Concurrent request limit reached | Allow active requests to finish before starting more. |
503 | Temporary network issue | Check your retry policy before submitting another request. |
See all status and reason codes for specific explanations and Limits and Retries for retry behavior.
For job IDs, credit usage, and other conversion details, see the reference.
Request rate and concurrency limits depend on your license. Control how quickly
your application submits conversions and how many it runs at once. A
429 response concerns request rate; a 430 response
concerns requests already in progress. The maximum upload size is 300 MB.
The Go client automatically retries a request once when it receives HTTP
502 or 503. Use
SetRetryCount()
to change that count, or set it to 0 to disable automatic retries.
Account for these retries when adding an application-level retry policy.
This example merges two PDFs with debug logging enabled and logs the debug log URL when available. Use the input and settings from the conversion you are investigating.
package main import ( "log" "github.com/pdfcrowd/pdfcrowd-go" ) func main() { client := pdfcrowd.NewPdfToPdfClient("demo", "demo") client.SetDebugLog(true) client.AddPdfFile("cover.pdf") client.AddPdfFile("proposal.pdf") err := client.ConvertToFile("merged.pdf") if debugLogURL := client.GetDebugLogUrl(); debugLogURL != "" { log.Printf("Debug log: %s", debugLogURL) } checkError(err) } func checkError(err error) { if err != nil { log.Fatal(err) } }
The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.
| Problem | Check |
|---|---|
| The PDF cannot be read | Check file paths, read permissions and whether each input is a valid PDF. For encrypted inputs, use SetInputPdfPassword(). |
| Pages are missing or in the wrong order | Check the order of added PDFs, the selected action and the page range. Use the default join action to append documents, or "shuffle" to interleave their pages. |
| The watermark hides the document | A watermark is placed over the page. Use a transparent watermark or SetPageBackground() to place content behind the page. |
For help, contact support and include any available diagnostics, the client version, and enough detail to reproduce the problem.