Customer Rewards API Documentation: A Developer's Guide to Integrating Referrals and Rewards

If you've been asked to add referrals or rewards to an app, customer rewards API documentation is where the work starts. This guide covers how a rewards API works, how to authenticate, and how to ship an integration.

What Is a Customer Rewards API?

A customer rewards API is a set of web endpoints that lets your app send customer actions to a rewards platform. The platform then decides who earns what and delivers the reward. An API (application programming interface) is a defined way for two software systems to talk.

One connection can power several program types:

• Referrals: Customers share a link or code, and both people can earn when the friend converts.
• Points: Customers collect points for purchases or actions, then redeem them later.
• Loyalty: Ongoing programs reward repeat behavior, such as monthly bill pay.
• Reward-for-action: Customers earn for one specific step, like finishing a profile or leaving a review.
• Promotions: Time-bound offers, such as a welcome bonus, target a specific audience.

Referred customers bring lasting value. A 2013 managerial summary of a peer-reviewed referral program study, published in the Journal of Marketing in 2011 and covering one German bank, reported: "The lifetime value of referred customers, measured over a six-year horizon, was 16 % higher, on average, than that of non-referred customers with similar demographics and time of acquisition."

Many developers open customer rewards API documentation expecting a single "add points" endpoint. Extole's developer-ready offer infrastructure uses events instead, and configurable rules decide the outcome.

How a Rewards API Works: Events, Rules, and Rewards

Extole uses an event-driven model: your app reports what happened, and rules decide what happens next. Reward logic stays out of your codebase, so referral program automation runs without new deploys.

The flow moves through events, campaigns, rules, rewards, and profiles. Each reward updates the person's profile, and that profile shapes the next event.

Events and Persons

An event is a named signal that something happened, sent with a data payload. A payload is the bundle of details attached, like an email address. Common event names include purchase, signup, account_opened, and share.

Events work the same way across industries:

• Banking: A credit union sends account_opened when a new member opens a checking account.
• Telecom: A carrier sends a custom event when a customer upgrades to a larger plan.
• Retail: An online store sends purchase when a referred friend completes a first order.

A Person is one unified identity across every role and campaign. The same customer can be an advocate, a referred friend, and a loyalty member at once. Your referral app tracks one profile per customer.

Campaigns and Rules

A campaign packages everything a program needs: the audience, journeys, rules, and actions. Journeys are the paths customers follow, such as sharing or signing up. This structure is the core of how to set up a referral program on Extole.

Rules decide whether an event earns a reward. Marketers and program managers configure them in Extole without engineering work.

Rule type	What it checks	Examples
Eligibility	Who qualifies for the program or reward	Only members with an active account can earn
Quality	Whether the action is legitimate	Velocity checks, self-referral detection, device and identity checks
Time	When a reward can apply	Conversion windows, cooldowns, expiration
Action	What happens after the rules pass	Issue a reward or trigger the next step

Quality rules are where fraud prevention lives. A velocity check flags too many referrals in a short window. Learn more about how referral tools reduce fraud.

Rewards and the Reward Lifecycle

Extole supports gift cards, coupons, credits, points, cashback, and custom rewards. Custom rewards are delivered by your own systems, such as a statement credit.

Every reward moves through a lifecycle, or set of states:

• Earned: The person met the rules, and Extole records the reward.
• Fulfilled: The reward was delivered, such as a gift card sent or a credit applied.
• Redeemed: The person used the reward.
• Canceled, failed, or revoked: These end states close the lifecycle when a reward is stopped, fails, or is taken back.

Lifecycle endpoints let you cancel, retry, or revoke a reward and read its state history, a clear audit trail for support teams. Programs can also offer collectible rewards with Reward Bank.

The Three APIs You'll Work With

Extole splits its REST APIs by who is calling. REST is a common web API style built on standard HTTP methods. The split keeps powerful credentials on your servers and lighter ones on customer devices.

API	Who calls it	What it's for
Integration: Server to Extole	Your backend servers	Events, persons, rewards, and bulk operations
Integration: Consumer to Extole	Browsers and native apps	Customer-facing calls that back the SDKs
Management API	Admin tools and scripts	Campaigns, audiences, reward suppliers, and reports

Each API comes with OpenAPI definitions, a standard machine-readable format that describes every endpoint. Use them to generate client code or browse them on Extole's API and OpenAPI platform. Machine-readable specs make customer rewards API documentation easier to test against.

API-first design is now common practice. A survey for Postman's 2025 State of the API report found: "Eighty-two percent of organizations have adopted some level of an API-first approach, with 25% operating as fully API-first organizations".

The Management API also lets you keep program setup in version control. See our guide to managing referral programs as code.

Authentication: Bearer Tokens vs. Consumer Tokens

Authentication is how an API confirms who is making a request. Extole uses bearer tokens for servers and consumer tokens for browsers and apps, because server credentials can do far more than any one customer should.

The OWASP API Security Top 10 lists Broken Authentication as API2: "Authentication mechanisms are often implemented incorrectly, allowing attackers to compromise authentication tokens or to exploit implementation flaws to assume other user's identities temporarily or permanently."

Server-Side Bearer Access Tokens

A bearer access token is a secret string that grants access to whoever holds, or "bears," it. Create one in the My Extole Security Center, then pass it in the Authorization: Bearer header on every server request.

# Illustrative request: replace the token and payload with your own values
curl -X POST "https://api.extole.io/v6/events" \
  -H "Authorization: Bearer $EXTOLE_ACCESS_TOKEN" \
  --json '{"event_name":"signup","data":{"email":"member@example.com"}}'

Scopes limit what a token can do. Available scopes are CLIENT_ADMIN, CAMPAIGN_EDIT, USER_SUPPORT, and ANY. If a token lacks the scope an endpoint needs, the API returns a 403 scopes_denied error.

Managed tokens from the Security Center are long-lived, which suits stable server jobs. Follow three rules:

• Keep tokens on the server: Never put a bearer token in browser JavaScript or mobile app code.
• Use the smallest scope: Give each token only the access its job needs, such as read-only reporting.
• Use short-lived tokens for temporary work: Request one from /v4/tokens so access expires quickly.

Consumer Access Tokens and Verified Identity

A consumer access token stands for one customer in one browser or app. The JavaScript, iOS, Android, and React Native SDKs create and manage these tokens for you. An SDK (software development kit) is a prebuilt code library.

Each consumer token has a security level that controls how much reward data it can reach:

Security level	What Extole knows	Typical use
Anonymous	Nothing about who the visitor is yet	Showing a share page before login
Identified	Who the visitor says they are, such as an email	Pre-filling a referral form
Verified	Proof of identity from your systems	Showing reward balances and history

To verify a person, your server signs a JWT and the app sends it in the X-Extole-Jwt header. A JWT (JSON Web Token) is a signed token that proves facts about a user. Each JWT must include a kid, or key ID, so Extole knows which key to check.

Extole supports HS256, RS256, and other signing algorithms. The IETF JWT best practices (RFC 8725, 2020) state: "human-memorizable passwords MUST NOT be directly used as the key to a keyed-MAC algorithm such as "HS256"". If JWTs don't fit your stack, you can verify by email or through an OAuth resource owner grant.

How to Integrate a Referral Program Into Your Application

If you need to integrate a referral program into your application, the work follows four steps. The same flow fits an app referral program for a credit union, a streaming subscription, or a wireless carrier.

1. Get sandbox access: Set up a safe test environment and credentials.
2. Add the share experience: Use an SDK so customers can refer friends.
3. Send conversion events: Report purchases and sign-ups from your backend.
4. Listen for rewards: Use webhooks to keep your systems in sync.

Step 1: Get Sandbox Access and Credentials

A sandbox is a test environment that never touches real customers. Request one through your Extole guide.

The sandbox uses the same token endpoints as production, and the client_id tells Extole which environment you mean. Create a bearer token, then find your program domain, such as acme.extole.io, in the Tech Center.

Step 2: Add the Share Experience With an SDK

A zone is a spot in your app where Extole renders content, such as a refer_a_friend panel. The SDKs render zones and manage consumer tokens, so customers can share without leaving your app. For banks and credit unions, referrals can live inside the digital banking experience.

For full design control, use the headless option: call POST /v6/zones/{event_name} and render the returned content yourself. Headless means Extole supplies the data while your team builds the interface.

For mobile patterns, read our guide to building a native app referral program.

Step 3: Send Conversion Events From Your Backend

A conversion event tells Extole that a customer completed the action your program rewards. Send it from your backend with your bearer token, so customers can't fake it.

# Illustrative payload: use your own event names and data fields
curl -X POST "https://api.extole.io/v6/events" \
  -H "Authorization: Bearer $EXTOLE_ACCESS_TOKEN" \
  --json '{"event_name":"purchase","data":{"email":"friend@example.com"}}'

POST /v6/events is synchronous, so Extole processes the event within the same request. For high volume, such as a nightly batch of retail orders, use POST /v6/async-events. It is not rate-limited.

Step 4: Listen for Rewards With Webhooks

A webhook is a message Extole sends to a URL you own when something happens. Extole reward webhooks tell your systems when a reward is earned or fulfilled.

Custom rewards follow a simple loop:

• Receive the webhook: Extole tells your system that a custom reward was earned.
• Fulfill it yourself: Your system applies the reward, such as a bill credit or a free subscription month.
• Report the result: Mark the custom reward fulfilled, sent, redeemed, or failed through the API to keep its history accurate.

Rate Limits, Errors, and Retries

A rate limit caps how many requests you can send in a set time. Extole allows 100 requests per minute per IP address or token, and 10 per second per identified person.

Errors return as JSON with consistent fields. Log the unique_id so you can trace each failed request.

{
  "unique_id": "illustrative-id-123",
  "http_status_code": 403,
  "code": "scopes_denied",
  "message": "Illustrative error message",
  "parameters": {}
}

Retry some errors with exponential backoff, which means waiting longer after each failed try. For the rest, fix the request or refresh the token first.

Status code	What it means	Retry?
429	Too many requests	Yes: wait 1s, 2s, 4s, then 8s, capped at 30s
500	Server error	Yes: use the same backoff
400	Bad request	No: fix the payload
401	Unauthorized	After refresh: get a new or refreshed token, then retry.
403	Forbidden	No: check the token's scopes
415	Unsupported media type	No: send JSON

Consumer event endpoints work differently. They always return 200 and put any error in the X-Extole-Error-Message header, so check that header in client code. For more detail while debugging, add the X-Extole-Debug header with level 1, 2, or 3.

Build vs. Buy: Why Developers Build on Rewards Infrastructure

Technical teams often ask, "We could build this ourselves, but should we?" Sending an event is the simple part. The hard parts sit underneath:

• Eligibility: Deciding who qualifies under multi-step, business-specific reward rules.
• Fraud prevention: Catching self-referrals, velocity abuse, and duplicate identities before rewards go out.
• Fulfillment: Delivering gift cards, credits, and points reliably, with retries.
• Attribution: Proving which advocate and which event earned each reward.
• Audit: Keeping a clean record of every decision for finance and compliance.

Extole handles this layer so your team can focus on the customer experience. Build the offer logic. Don't rebuild the offer infrastructure.

The results are measurable. In a Forrester Total Economic Impact study commissioned by Extole, the composite organization saw a 282% ROI over three years. The same composite organization saw an 80% reduction in unqualified redemptions.

Security is built in as well. Per Extole's API platform page, Extole is ISO/IEC 27001 certified and supports GDPR, CCPA, and EU-US Data Privacy Framework compliance.

AI-ready tooling adds speed on top. OpenAPI definitions and llms.txt files, plain-text summaries for AI models, help coding assistants read customer rewards API documentation accurately.

MCP (Model Context Protocol) is a standard way for AI tools to connect to software. With the Extole MCP server, AI agents can inspect and configure programs through permissioned workflows.

AI assists the setup, while Extole's deterministic runtime makes every live reward decision. Build with AI. Deliver with trust.

Ready to start building? Request a sandbox from your Extole guide, or request a demo to see how Extole fits your stack.

FAQ

How do I authenticate requests to a customer rewards API?

Server requests send a bearer access token in the Authorization: Bearer header. Browsers and apps use consumer access tokens, which the SDKs manage and JWTs can verify.

What do I need before making my first rewards API call?

You need sandbox access, a bearer token with the right scope, and your program domain from the Tech Center. Your Extole guide can set up the sandbox.

Can I add a referral program after my app has launched?

Yes, add an SDK zone for sharing and send conversion events from your existing backend. Rules live in Extole, so most program changes don't need an app release.

How do I prevent referral fraud like self-referrals?

Turn on quality rules for velocity checks, self-referral detection, and device and identity checks. Send conversion events from your server and verify identities with JWTs.

What rate limits apply, and how should I handle throttled requests?

Limits are 100 requests per minute per IP or token, plus 10 per second per identified person. Retry 429 responses with exponential backoff capped at 30 seconds.

How do I test my rewards integration in a sandbox?

Request a sandbox from your Extole guide, then use the production token endpoints with your sandbox client_id. Add the X-Extole-Debug header to see extra detail while you test.

Should I build my referral program in-house or use a platform?

Building in-house means owning eligibility, fraud prevention, fulfillment, attribution, and audit yourself. A platform like Extole provides that infrastructure, so your team can focus on offer logic.