Ballpoint Marketing API — Integration Docs

Everything you need to integrate with the Ballpoint Marketing direct mail API: ordering, real-time tracking, billing, and webhook delivery.

Getting Started

START_HERE.md — Zero to a working test order in under 5 minutes.

Documentation

Resource	Description
API Integration Kit	Full integration guide: auth, endpoints, webhooks, error handling, partner payment gate
Iframe Integration Kit	Embedded iframe pattern: bootstrap, message contracts, recipient upload, partner payment gate flow
OpenAPI Spec	Machine-readable API specification (import into Postman, Swagger UI, etc.)
Webhook Contract Catalog	Canonical event inventory, JSON Schemas, exact raw-body fixtures, and signed header fixtures
Quick Start Guide	Step-by-step first-order walkthrough
Changelog	Revision history for the integration kits

Examples

Example	Description
Postman Collection	Pre-built requests for every endpoint
Express Integration	Node.js/Express webhook receiver with signature verification
Lambda Webhook	AWS Lambda handler for webhook processing
Cloudflare Worker	Cloudflare Worker webhook receiver

Postman Environments

• Staging — PropStream integration testing (staging-api.ballpointmarketing.com; paste your staging pk_test key)
• Sandbox — internal test key on api.ballpointmarketing.com (no real mail)
• Production — future go-live with a pk_live key

Webhook Security

Webhook endpoints with a provisioned secret are signed with HMAC-SHA256. Your integration must verify signatures before processing events. A migration-grace endpoint without a secret is explicitly marked X-Ballpoint-Insecure: true and must not be treated as authenticated.

Header	Purpose
X-Ballpoint-Signature	sha256=<hex> — HMAC of UTF-8(X-Ballpoint-Timestamp + exact raw body bytes) using your webhook secret
X-Ballpoint-Timestamp	ISO 8601 timestamp — reject if older than 5 minutes (replay protection)
X-Ballpoint-Event-Id	Unique event ID — store and check for deduplication
X-Ballpoint-Delivery	Unique HTTP-attempt ID — changes on each retry; do not use it for event deduplication
Idempotency-Key	Required on POST /v1/billing/orders — prevents duplicate orders on retry

See the API Integration Kit for full verification examples and the webhook receiver templates in examples/ for working implementations.

Support

For API access, environment keys, and technical support, reach out to your partner technical contact at Ballpoint.