Support tools

When a customer writes in, your support agent can see their referral context right next to the conversation:

• A referred customer: "Referred by Ana · $40.00 credit unused", plus when they were referred and what the referral has earned.

• A partner: "Partner · Gold · $412.00 pending", plus programs, approved and paid amounts, the next payout date, their referral link, and flags such as an open fraud review.

Only your org's data is shown. Contacts are matched by your own ids first (a partner's externalRef, your customer ref, or the tool's verified external id), and by email only when the tool sends nothing stronger.

The lookup API

curl "https://referalli.com/v1/support/context?email=dana@example.com" \
  -H "Authorization: Bearer $KEY"     # a key with partners:read

{
  "partner": null,
  "customer": {
    "referredBy": { "partnerId": "ptr_…", "name": "Ana" },
    "attributedAt": "2026-09-14T10:02:11.000Z",
    "rewardState": { "kind": "store_credit", "status": "issued", "amountMinor": 4000, "currency": "usd", "remainingMinor": 4000 },
    "commissionsMinor": 1200,
    "currency": "usd"
  },
  "links": { "dashboard": "https://referalli.com", "partner": null, "referral": "https://referalli.com/referrals/ref_…" }
}

Query by partnerExternalRef, ext, customerRef or email. Money is in integer minor units.

Connect a tool

In the dashboard, open Settings → Integrations → Support tools. Choose the tool, follow its steps, and save its secret. Each tool calls its own card URL:

https://referalli.com/v1/support/cards/{orgId}/{tool}

Requests that aren't signed, are signed with the wrong secret, are stale, or come from a tool you haven't connected all get a 404. Preview card shows what a tool would display for an email, without calling the tool.

Chatly

Customer card. In Chatly, add a customer card (Settings → Developer → Customer cards, or POST /v1/customer-cards) with key referalli and the Chatly card URL. Then paste the signing secret Chatly shows (cc_… or cce_…) into Referalli. Chatly signs each request with x-chatly-timestamp and x-chatly-signature.

AI tools. Create read-only tools in Chatly (POST /v1/ai/tools) that point at the Chatly AI tools URL: my_referral_link, my_balance, my_next_payout and why_commission_pending. Set each one to requiresVerifiedIdentity: true and give it a signing secret, plus a body of {"tool": "<name>", "externalId": "<the contact's verified externalId>"}. Paste the same secret into Referalli. Answers are keyed on the partner's externalRef only, never on an email. AI stays BYOK: Referalli holds no AI key.

Intercom

This is a Canvas Kit inbox app (see integrations/intercom-app). Use the Intercom card URL as both the initialize URL and the submit URL, and paste the app's client secret. Intercom signs requests with X-Body-Signature.

Zendesk

This is a private sidebar app (see integrations/zendesk-app). Upload it and set its Referalli card URL. Then paste the app's public key, from /api/v2/apps/{app_id}/public_key.pem, and your subdomain. The app calls Referalli with signed requests, and Referalli verifies Zendesk's token.

HubSpot

This is a CRM card on Contacts (see integrations/hubspot-app). Its data fetch URL is the HubSpot card URL, and it sends the email property. Paste the app's client secret. Requests carry the v3 signature (X-HubSpot-Signature-v3) and are refused after five minutes.

Front

This is a sidebar plugin plus a small relay on your server (see integrations/front-app). The relay signs each call with X-Front-Request-Timestamp and X-Front-Signature, so the secret never reaches the browser.

Help Scout

This is a dynamic app. Use the Help Scout card URL as the callback URL and choose a secret key. Paste the same secret key into Referalli. Help Scout signs requests with X-HelpScout-Signature.

Custom

For any other tool, enable Custom. Referalli creates a secret and shows it once. POST {email?, customerRef?, partnerExternalRef?, ext?} to the custom card URL with:

X-Referalli-Timestamp: <unix seconds>
X-Referalli-Signature: v1=<hex HMAC-SHA256 of "{timestamp}.{raw body}" with the secret>

The answer is the context above, plus found.

MCP

The MCP server (@referalli/mcp) has three read-only partner self-service tools: my_referral_link, my_balance and my_next_payout. Each takes the partner's partnerExternalRef.