Public API

Public API

Server-to-server API for brands: API keys, signed webhooks, conversion postbacks, and read models for campaigns, deals, placements, tracked links, escrow, and workspace. Authenticate with X-Api-Key, never a user JWT.

Who this is for

Brand backends, attribution partners, and internal tools. This is not the website login API. Creators do not get public REST keys. Billing: Growth is read, Scale and Agency are full. Live routes check key scope only: read lists campaigns, deals, links, placements, escrow, conversions, webhooks, and tests; write mints keys and registers webhooks. Conversion postbacks accept any valid key for that brand.

Base URL

All paths below are relative to versioned brand-api.

  • Production: https://api.pactreach.com/api/v1
  • Development: https://api-dev.pactreach.com/api/v1

Content-Type is application/json. Dates are ISO-8601. Money is integer valueMinor (kobo / cents), never a decimal string.

Integration flow

  1. 01Mint an API keyFirst key uses a bootstrap token from PactReach Support. Later keys use rotate-key with write scope. Store the secret immediately.
  2. 02Register a webhookPOST your receiver URL. Save signingSecret once. Send a test ping and verify HMAC before going live.
  3. 03Call the APISend X-Api-Key (or Bearer) on every request. brandId in the path must match the key. Responses use a standard envelope.
  4. 04Record conversionsPartner postbacks hit record-postback with Idempotency-Key. Or install the browser pixel for on-site events.

Response envelope

Every JSON response uses the same shape, including errors.

{
  "status": true,
  "statusCode": 201,
  "message": "API key created. Store the secret now; it will not be shown again",
  "data": { },
  "requestId": "req_..."
}

Treat status plus statusCode as the contract. errorCode appears only on failures and is stable for automation; message is for humans. Paginated lists put paging in meta. requestId is always present.

Guides

FAQ

Is this the same as logging into pactreach.com?
No. The website uses a user access JWT. The public API uses a brand API key (pr_live_...). Do not send a login token to these routes.
Which plan includes API access?
Billing advertises Growth as read and Scale or Agency as full. Live routes authorize by key scope only: read can list campaigns, deals, links, placements, escrow, conversions, webhooks, and send a test ping; write can mint keys and register webhooks. Conversion postbacks accept any valid key for that brand. Upgrade under Plan in the brand app.
Where do I see the full API secret again?
You cannot. create-key and rotate-key return secret once. Store it in your secrets manager. Listing keys only returns the prefix, scopes, and last used time.
Does rotate-key replace the old key immediately?
No. rotate-key mints a new key. The previous key stays valid until you revoke it. Switch traffic, then revoke the old id.
How do I verify a webhook is from PactReach?
Compute HMAC-SHA256 of `{timestamp}.{rawBody}` with your endpoint signing secret. Compare to X-PactReach-Signature (prefix sha256=). Reject if the timestamp is older than 5 minutes.
What if my webhook endpoint is down?
PactReach retries up to 6 times: ~30s, 2m, 10m, 1h, 6h. After too many consecutive failures the endpoint is switched off. Re-enable with isActive: true (that also clears the failure counter).
Why must conversion postbacks send Idempotency-Key?
Ad networks retry. The same key returns the existing conversion with replay: true instead of double-counting. Keys must be 16-128 characters (letters, digits, dash, underscore, or colon).
Can I use NGN and USD in postbacks?
Yes. Send currency as NGN or USD (integer valueMinor). If you omit currency, PactReach stores NGN.
Can the public API create campaigns or release escrow?
No. Create, invite, draft review, and escrow release stay in the brand app. The public API exposes read status for campaigns, deals, placements, tracked links, and escrow so your backend can attribute conversions.

Need a bootstrap token?

Open Support from a signed-in brand account and ask for a public API bootstrap token for your brandId. Include the workspace name. create-key always uses that token (not an API key). After you have a write key, mint further secrets with rotate-key.