Firewards API
Build your own integrations on top of Firewards.
Import subscribers, track referrals server-side, and pull referrer data into your dashboards or custom workflows.
Overview
The Firewards API is a JSON REST API that lets you programmatically interact with your referral campaign. It is the same API our official integrations are built on top of, so anything you can do through one of our ESP integrations — importing subscribers, tracking a successful referral, looking up a subscriber's referral code, listing top referrers — can also be done from your own backend.
The full reference (with request/response examples in multiple languages) is available at documenter.getpostman.com/view/16330514/TzeahR66.
Base URL & Authentication
All endpoints are served under the base URL:
https://app.firewards.com/api/v1
Authenticate every request by sending your API key in the
X-Api-Key HTTP header.
You can find (and rotate) your key inside your Firewards dashboard under your campaign
settings. Treat the key as a secret — it grants full access to your campaign data.
What you can do with the API
The API is organized around two core resources: subscribers (people on your list, each with their own referral code and link) and referrals (the act of one subscriber bringing in another).
- Import subscribers — bulk-load existing or new subscribers into Firewards so they get a referral code and link generated and synced back to your ESP.
- Look up a subscriber — fetch a single subscriber by email, including their referral code, referral link, and referral count.
- List subscribers, referrals and referrers — paginate through all of your data for reporting, exports, or building your own dashboards.
- Track a referral server-side — if you run your own newsletter signup form, you can credit a referral to the referrer from your backend after the new subscriber has been added to your ESP.
- Delete a subscriber — remove a subscriber and unsubscribe them from your ESP, automatically reverting any referral they were credited for.
Endpoints
POST /subscribers
Import Subscriber(s). Imports up to 500 subscribers per call into the synchronization engine and makes them eligible to participate in the campaign. Each imported subscriber receives a referral code and link, which are then synced back to your ESP asynchronously (this can take a few minutes depending on your ESP's response time).
The body is a JSON array of subscriber objects. email
and id (the reference ID in your ESP) are
required; firstname,
lastname,
status,
created and a free-form
fields object are optional.
GET /subscriber?email=...
Get Subscriber By Email. Returns a single subscriber with their referral fields (referral code, referral link, number of referrals, etc.).
DELETE /subscriber?email=...
Delete Subscriber. Removes a subscriber from Firewards and
unsubscribes them from your ESP. If the subscriber had been invited by another subscriber,
any referral status credited to the inviter is reset. The response indicates whether the
subscriber was originally invited (invitedBy).
GET /subscribers?limit=25&page=0
Get Subscribers. Returns a paginated list of all subscribers on your campaign with their referral information.
GET /referrals?limit=25&page=0
Get Referrals. Returns a paginated list of recorded referrals (who referred whom and when).
GET /referrers?limit=25
Get Referrers. Returns a paginated list of subscribers who have brought in at least one referral — useful for leaderboards and top-referrer reports.
POST /track-referral
Track Referral. Credits a referral to a referrer. Use this when you run your own newsletter form: after the new email has been successfully subscribed at your ESP, call this endpoint from your backend so the referrer's points are incremented.
Form fields:
email— the email address that just subscribedrefcode— the referral code of the referrerclient— your Firewards unique URL handle
Response format
Every response follows the same envelope: a _meta
object with a success flag and a
total count, and a
data object (or array) carrying the actual
payload. List endpoints support limit and
page query parameters for pagination.
Need help?
The full Postman reference at documenter.getpostman.com/view/16330514/TzeahR66 contains live request/response examples and code snippets for cURL, JavaScript, Python, PHP, Go, C#, and more. If you run into questions while integrating, just reach out via our support page — we're happy to help.