PDF Tamper Detection API for Ruby on Rails: Integration Guide

Originally published at htpbe.tech . The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text. A large share of fintech still ships on Rails. Stripe, Gusto, GitHub, Shopify, Instacart — the generation of companies that defined modern payments and payroll built their backends on Ruby, and the startups following them keep reaching for the same stack. So when a forged bank statement, an altered payslip, or a doctored invoice lands in an underwriting queue, more often than you would guess it lands on a Rails controller. Your KYC provider already confirmed the applicant is a real person with a valid identity. It said nothing about whether the PDF they uploaded was edited after the bank generated it. That structural-tampering layer is invisible to identity verification, and the right place to catch it is at ingress — before your Document model saves, before the row reaches underwriting, before any downstream system trusts the file. This guide walks through integrating the PDF tamper detection API into a Ruby on Rails application: from the first curl command to an idiomatic HtpbeClient service object built on Faraday, a Data -class result struct, configuration-bound credentials, a typed error class, an ActiveJob that analyzes an uploaded document and routes on the verdict, and a request spec that stubs the API with WebMock. The patterns target Rails 7.x and Ruby 3.x, but they map cleanly onto Sinatra, Hanami, or a plain Ruby worker. Treat the code as a reference architecture: it runs the real request flow against the documented error codes, but you should adapt and harden it for your own traffic profile and threat model. If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically . Integrating from another stack? See the Python , Node.js , Go , Java / Spring Boot , Laravel / PHP , and C# / .NET guides. TL;DR Two API calls, three verdicts: POST /analyze returns a top-level id , th