Back to home
API preview

Production REST API.
HMAC-signed webhooks. Idempotency-Key on writes.

The Inkli Engine API is the same interface our partner integrations use in production. This page previews the surface — endpoints, auth, events, rate limits — enough for your team to answer "can we integrate this?" before we mint you keys.

Full request / response docs are shared on partner activation.
Talk to sales for keys →

Auth

Bearer tokens · per-actor scoping · 24h idempotency

API keys

Two key formats: pk_live_… (production traffic, real letters) and pk_test_… (unmetered, safe for CI + local dev). Mint, list, and revoke from the partner settings page.

Idempotency

Send an Idempotency-Key header on writes. Same key within 24h returns the same result — safe to retry a POST after a network wobble without creating a duplicate campaign.

Endpoints

What you can hit

POST/api/partner/v1/campaigns

Create a draft campaign with settings + template.

POST/api/partner/v1/campaigns/:id/recipients

Attach a recipient list (bulk).

POST/api/partner/v1/campaigns/:id/process

Fire the render (or Retry a failed run — clean reset).

POST/api/partner/v1/campaigns/:id/duplicate

Clone into a fresh draft. Optional copy_recipients toggle.

GET/api/partner/v1/campaigns/:id

Poll status + progress + delivered files.

GET/api/partner/v1/campaigns/running

Get your currently-running campaign (or null).

GET/api/partner/v1/campaigns

List — status filter, pagination, sub-client scoping.

GET/api/partner/v1/usage?period=YYYY-MM

Letters rendered + by-campaign / by-client rollup + projected bill.

GET/api/partner/v1/invoices

Issued invoices with pre-signed PDF URLs.

Additional sub-resources: delivery targets, layout templates, ICC profiles, sub-clients, webhooks. All follow the same shape.

Webhooks

Events, HMAC-signed

Every webhook carries an X-Inkli-Signature header — HMAC-SHA256 over the raw body with your webhook secret. Verify server-side before trusting the payload.

campaign.completed

Render finished. Payload includes output paths + letter count + delivery target status.

campaign.failed

Render errored. Payload includes error code + retryable flag.

proof.ready

Proof render finished (unmetered, watermarked). Approve to fire the billed run.

Rate limits

Set at activation, generous by default

Reads

60 rpm

sustained · per key

Writes

10 rpm

sustained · per key

Burst

+50%

brief · smoothed over 1min

Higher limits available on request — enterprise partners get bespoke tiers. Response headers surface X-RateLimit-Remaining and X-RateLimit-Reset so you can back off cleanly.

Sample flow

Proof → approve → deliver

  1. 1POST /campaigns — create a draft with your layout template + settings
  2. 2POST /campaigns/:id/recipients — attach the CSV
  3. 3POST /campaigns/:id/process { proof: true } — fire the unmetered proof
  4. 4proof.ready webhook — review the watermarked PDF
  5. 5POST /campaigns/:id/approve — approve; the billed render fires
  6. 6campaign.completed webhook — output delivered to your SFTP / S3

Ready for keys?

Keys are provisioned on partner activation. Tell us what you're integrating and we'll come back within a working day.

Talk to sales for keys