Upload by URL

Base URL https://api.accessful.de/api/v1/upload-service. Every request needs the X-API-Key header — see Authentication.

Hand us URLs and we fetch the PDFs ourselves. Downloads run asynchronously.

POST /pdf/upload-by-url-list
Content-Type: application/json

{
  "files": [
    { "url": "https://example.com/report.pdf", "filename": "report.pdf" }
  ],
  "callbackUrl": "https://your-app.example.com/hooks/accessful",
  "hmacSignature": "your-webhook-secret"
}

• filename must match ^[A-Za-z0-9_-]+\.pdf$ and contain at most 255 characters.
• hmacSignature (the webhook secret) must match ^[A-Za-z0-9_-]{1,64}$.

202 Accepted

{
  "accepted": [
    { "uri": "https://example.com/report.pdf", "jobId": "7c2f1e4a-…", "filename": "report.pdf" }
  ],
  "failures": {},
  "callbackResult": null
}

Each jobId behaves like a caseId — poll and download with it.

Reliable URL jobs

Only public HTTPS URLs are accepted. Redirects and resolved addresses are checked; private, loopback and link-local targets are rejected. The fetch stops at 50 MiB or 120 seconds, and the actual bytes must be a valid PDF. This is separate from multipart upload limits.

An optional Idempotency-Key UUID makes acceptance durable and repeatable. The same Accessful user, idempotency key and request body return the same job IDs, including after API-key rotation. Different input with the same key returns 409. Entries are retained for at least 24 hours and while jobs remain active. Existing clients may omit this header. Persist the ID before sending the request; a timeout does not prove rejection.

An accepted job is immediately queryable by its owner as queued, before download finishes. Download or validation failure becomes failed. A duplicate becomes failed with error.code: DUPLICATE_FILE and the owner’s existingCaseId; it is not silently skipped.

Source URLs must not contain embedded credentials or fragments. Invalid URL syntax or a malformed Idempotency-Key returns 400 before acceptance. Keep the exact URL and other inputs unchanged when retrying with the same key; renewing a signed source URL changes the request.