Mesclar PDF

---
name: merge-pdf
description: "Merge PDF combines multiple documents into one organized PDF file. In addition to PDFs, users can upload supported document and image formats, which are converted to PDF before being merged. Use this skill when the user asks to merge pdf via the Cross Service Solutions API."
---

# Merge PDF

## Solution Description

Merge PDF combines multiple documents into one organized PDF file. In addition to PDFs, users can upload supported document and image formats, which are converted to PDF before being merged.

*This widget is provided by PDF24. Get your own widget to enable your visitors to convert to PDF.

## Input

| Parameter | Type | Required | Description |
|---|---|---|---|
| `files` | multiple_files | Yes | Combine or join multiple files into a single PDF |

**Constraints:**

- `files` accepts multiple values — repeat the form field once per item

## Expected Outcome

Executing this solution creates an asynchronous job. Poll the "Get Result" endpoint
until `status` is no longer `pending` — a `done` status means `output` will contain
the result (`output.result`, `output.data`, and/or `output.files[]` depending on the
solution), while a `failed` status means the job could not be completed.

## Execute Solution

This is a free endpoint — no `Authorization` header is required.

```bash
curl -D - -X POST 'https://api.cross-service-solutions.com/solutions/solutions/free/63' \
  -F 'files=@/path/to/file1.pdf' \
  -F 'files=@/path/to/file2.pdf'
```

The response sets `Solution_id` and `Solution_uuid` cookies via `Set-Cookie` headers
(visible with `-D -`). Read their values — they're required for the "Get Result"
request below.

## Get Result

```bash
curl --location 'https://api.process-machine.com/solutions/solutions/free/solution/latest' \
  --header 'Cookie: Solution_id=<id>; Solution_uuid=<uuid>'
```

Replace `<id>` and `<uuid>` with the `Solution_id` and `Solution_uuid` values captured
from the "Execute Solution" response headers. This endpoint lives on a different
domain than "Execute Solution", so the cookies must be passed explicitly via the
`Cookie` header — they won't be forwarded automatically across domains by a reused
cookie jar.

**Response example:**

```json
{
    "id": 101373,
    "name": "Free - Merge PDF",
    "status": "done",
    "steps": [
        { "name": "Merge PDFs", "status": "done" },
        { "name": "Merge PDFs", "status": "done" }
    ],
    "output": {
        "result": "",
        "data": null,
        "files": [
            { "name": "pdf.pdf", "path": "https://storage.googleapis.com/..." }
        ]
    }
}
```

**Polling behavior:**
- Poll every 3 seconds
- Timeout after 60 seconds (20 attempts) — if still `pending`, tell the user the
  job is taking longer than expected and offer to keep waiting or retry
- On `done`: download the file(s) from `output.files[].path` (a signed, time-limited
  URL) — or check `output.result`/`output.data` if `files` is empty
- On `failed`: surface the `error` field (if present) to the user in plain language;
  do not retry automatically more than once

## Error Handling

| Scenario | Response |
|---|---|
| Missing required parameter(s) | Ask the user for the missing field(s): `files` |
| Invalid or unreadable file | Tell the user which file couldn't be processed and ask them to check the format or re-upload |
| API returns `failed` status | Report the failure reason if available; offer to retry |
| `403 Forbidden` on Get Result | The `Solution_id`/`Solution_uuid` values are missing, incorrect, or expired — re-run "Execute Solution" and retry with the fresh values |