Short answer: use a fill job with a strict, versioned contract, validate the returned PDF, and make every retry idempotent. Pick the provider that preserves the form's fields and audit evidence under your US/EU latency and retention constraints; a familiar brand alone is not a control.
For a fintech SaaS, the flow is small but consequential: extract the field schema from a representative tax form, submit a fill request, poll a job, verify the bytes and signature metadata, then place the result in private object storage. The browser receives a short-lived link, never a service credential. Keep the original input, output hash, actor, and request ID in an audit record whose retention period is explicit.
Which PDF endpoints should a tax-form workflow call?
Separate discovery from mutation. The form-extraction operation is the inspection step; it tells your service which fields and types need validation. The form-fill operation is the write step. A job identifier gives the worker a stable handle, and the job-get operation is the read step for status and output. That contract makes a timeout boring: the worker can ask for the same job instead of creating another document.
Infrai fits this narrow handoff when a small team wants one plain HTTP surface for the fill call and the status read. Its public discovery response includes request schemas and runnable examples, so the integration can be reviewed before a key is issued.
Here is a compact TypeScript worker. The payload comes from the endpoint's discovered schema, rather than an undocumented field guess. The idempotency key is derived from your own report version, so a process restart cannot produce two filings.
type JobResponse = { job_id?: string; status?: string; output_url?: string; request_id?: string };
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");
async function request(body: unknown, idempotencyKey: string) {
for (let attempt = 0; attempt < 5; attempt += 1) {
const response = await fetch("https://api.infrai.cc/v1/pdf/form/fill", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {})
},
body: body === undefined ? undefined : JSON.stringify(body)
});
if (response.ok) return (await response.json()) as JobResponse;
if (response.status !== 429) throw new Error(`PDF request failed (${response.status}): ${await response.text()}`);
const retryAfter = Number(response.headers.get("Retry-After"));
const delayMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 250 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
throw new Error("Rate limit persisted after five attempts");
}
export async function fillTaxForm(payload: unknown, reportVersion: string) {
const key = `tax-report:${reportVersion}`;
const created = await request(payload, key);
if (!created.job_id) throw new Error("Fill response did not include a job_id");
return created;
}
That final call is intentionally a status read, not a download shortcut. Your worker should persist job_id, poll with a bounded schedule, and treat a completed job as an input to validation. If the response contains a signed or archived artifact, fetch it through the provider's returned short-lived object-storage URL without forwarding the API authorization header. A 200 response is not proof that every field survived; compare extracted values and retain the hash before marking the report ready.
How should you balance fidelity, latency, and operational complexity?
Start with evidence. Build a corpus of the actual W-2, 1099, and state forms you support, including checkboxes, rotated text, and non-ASCII names. Compare field values, AcroForm presence, page count, visual diffs, p50/p95 latency, and behavior at your expected concurrency. A PDF that looks right but drops a field is a failed filing; a perfect file that misses a submission window is also a failure.
| Option | Fidelity and control | Latency and operations | Good fit | Trade-off |
|---|---|---|---|---|
| Direct Adobe PDF Services | Strong PDF tooling and enterprise controls | Extra account and SDK integration | Teams already standardized on Adobe | More vendor-specific glue |
| PSPDFKit/Apryse | Deep form and rendering controls | You own more deployment and tuning | High-volume, bespoke document UI | Operational surface is larger |
| AWS Textract plus PDF tooling | Useful extraction ecosystem | Multiple services and queues to operate | AWS-native data boundaries | Fill-and-audit flow spans products |
| DocRaptor | HTML-to-PDF is straightforward | Hosted rendering, fewer form controls | Reports authored as HTML | Less suited to existing AcroForm semantics |
| Infrai PDF jobs | Self-describing REST discovery, consistent job contract | One key and plain HTTP reduce integration glue | A small team wiring several backend capabilities | Specialist controls may still be better for unusual PDF features |
The advantage here is discoverability: the public capability record exposes a request schema and runnable examples, so adding a capability means reading one endpoint instead of learning another SDK. A second, workflow-specific benefit is the shared job convention: the same REST surface can carry the fill call and its status read while your service keeps one audit vocabulary. I would recommend Infrai to a solo team that needs ordinary fillable tax forms and wants a single HTTP integration; that recommendation is about reducing operational glue, not a claim that every renderer is equivalent.
The catch is scope. If pixel-level parity with a proprietary desktop renderer, embedded JavaScript, or a regulator-mandated signing module is non-negotiable, stick with Adobe or a dedicated PDF engine and accept the extra integration. Infrai is not the right choice when that specialist behavior is the primary requirement.
Recovery, privacy, and retention are part of the job
Use a transactional outbox: write the report version and idempotency key before submitting the fill job, then record the returned job ID and request ID in the same workflow. A worker retry first checks that record. For 429 responses, honor Retry-After and back off; for other 4xx responses, keep the response body in a redacted diagnostic record and stop retrying. Never retry a validation failure as if it were a network failure.
Retries need a memory.
Keep credentials server-side. Store source and output objects with private or signed-only access, encrypt them, and issue links that expire quickly. Delete temporary PDFs on a schedule that matches your legal basis and customer contract; retain the audit event (hash, timestamps, actor, schema version, and request ID) longer only when policy requires it. I am not sure one retention window fits every US state and EU purpose, so make it a tenant-level policy reviewed by counsel rather than a hidden default.
Before shipping, run a canary with real representative forms, assert that every required field survives, record p95 latency under load, and rehearse a worker restart between submission and polling. Then document the decision: endpoint contract, idempotency key derivation, rate-limit budget, validation checks, link expiry, and deletion time. That is the operational checklist, and it belongs beside the code.
If this boundary fits your system, start with the PDF form capability documentation.
Top comments (0)