Quickstart

This quickstart shows the shortest path to a working server-to-server integration. Open https://portal.iyzpdf.com/login and sign in to your account.

2. Create An API Key

Go to the API Keys screen, create a new key, and copy the full value immediately. IyzPdf only shows the full secret once after creation. If you need the full workflow, see API Keys.

3. Store The Key In Your Server Environment

export IYZPDF_API_KEY="iyz_live_your_key_here"

Do not embed this key in browser code, mobile apps, or public repositories.

4. Send Your First Request

The example below renders inline HTML into a PDF.

curl --request POST \
  --url https://api.iyzpdf.com/v1/convert/html-to-pdf \
  --header "X-API-Key: $IYZPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "html": "<!doctype html><html><body><h1>Invoice #1042</h1><p>Total: $99.00</p></body></html>",
    "options": {
      "format": "A4",
      "marginTop": "2cm",
      "marginBottom": "2cm",
      "printBackground": true
    }
  }' \
  --output invoice.pdf

5. Read The Response

Successful requests return the generated file as an attachment by default. Common success headers:

X-Request-Id
X-Processing-Time-Ms
X-Credits-Used
X-Credits-Remaining
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

If you only want metadata, add an Accept: application/json header:

curl --request POST \
  --url https://api.iyzpdf.com/v1/convert/html-to-pdf \
  --header "X-API-Key: $IYZPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "html": "<html><body><p>Metadata only</p></body></html>"
  }'

Example response:

{
  "fileName": "output.pdf",
  "size": 183240,
  "creditsUsed": 1,
  "creditsRemaining": 49,
  "contentType": "application/pdf"
}

6. Handle Errors Consistently

Errors follow a stable JSON envelope:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You need 2 credits but have 0 remaining.",
    "creditsRequired": 2,
    "creditsBalance": 0,
    "purchaseUrl": "https://iyzpdf.com/portal/credits"
  }
}

Typical status codes:

200 for success
400 for validation errors
402 for insufficient credits
413 for payload size errors
415 for unsupported file types or media types
429 for rate limiting
500 for processing failures

Getting Started

Workflows

2. Create An API Key

3. Store The Key In Your Server Environment

4. Send Your First Request

5. Read The Response

6. Handle Errors Consistently

​1. Sign In To The Portal

​2. Create An API Key

​3. Store The Key In Your Server Environment

​4. Send Your First Request

​5. Read The Response

​6. Handle Errors Consistently

1. Sign In To The Portal

2. Create An API Key

3. Store The Key In Your Server Environment

4. Send Your First Request

5. Read The Response

6. Handle Errors Consistently