Overview

The Rewardful API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
We highly recommend checking out Insomnia, a desktop app that makes testing API requests and responses a breeze 👍
Authentication
All API requests require authentication with HTTP Basic Auth, similar to how Stripe authenticates. Provide your API Secret as the basic auth username value. You do not need to provide a password.
1
curl https://api.getrewardful.com/v1/affiliates/7B016217-18AF-44DD-A30C-0DE0C1534D2A \
2
  -u YOUR_API_SECRET:
Copied!
Be sure to replace YOUR_API_SECRET with your actual API Secret. For example, if your API secret was ABC123, the curl command to fetch all affiliates would be:
1
curl --request GET \
2
  --url https://api.getrewardful.com/v1/affiliates \
3
  -u ABC123:
Copied!
Your API Secret can be found on the Company Settings page.
Keep your API Secret safe! 
Your API Secret grants full access to your Rewardful account. Do not:
Share your API Secret with third parties
Commit your API Secret to version control (i.e. Git)
Share your API Secret over email or chat
Send your API Secret to the web browser in HTML or JavaScript
Contact us as soon as possible if you believe your API Secret has been compromised so we can rotate it for you.
Request and Response Formats
Rewardful will provide a JSON-based REST API through which merchants can create affiliate accounts and fetch data for reporting. Endpoints accept form-encoded request bodies and return JSON-encoded responses.
Rewardful uses UUID strings for primary keys (IDs) for all resources. If you plan to store Rewardful IDs in your database, make sure to use a column type (string, UUID, etc) appropriate for your database engine.
Dates and times in the Rewardful API are represented as ISO 8601 formatted strings.
Errors
Missing or invalid authorization will return a 401 Unauthorized JSON response:
1
{  "error": "Invalid API Secret." }
Copied!
Requesting a nonexistent object will return a 404 Not Found JSON response:
1
{  "error": "Affiliate not found: " }
Copied!
Passing invalid data to a create/update endpoint will return a 422 Unprocessable Entity JSON response:
1
{
2
  "error": "Could not create affiliate.",
3
  "details": ["Email can't be blank"]
4
}
Copied!
Pagination
API endpoints that return a list of objects include pagination, unless noted otherwise. The data structure has two root objects:
Key
Description
pagination
Pagination data, such as current/next/previous page numbers, counts, etc.
data
An array of objects returned for the specified page number.
The `pagination` object
Key
Description
previous_page
Previous page number. Will be null if there's no previous page.
current_page
Current page number.
next_page
Next page number. Will be null if there's no next page.
count
The number of objects on this page.
limit
The requested number of objects per page.
total_pages
The total number of pages.
total_count
The total number of objects returned across all pages.
Example
This example demonstrates the pagination for a collection of 150 objects in total, split into 3 pages of 50 objects per page:
1
{
2
  "pagination": {
3
    "previous_page": 1,
4
    "current_page": 2,
5
    "next_page": 3,
6
    "count": 50,
7
    "limit": 50,
8
    "total_pages": 3,
9
    "total_count": 150
10
  },
11
  "data": [
12
    // Array of objects
13
  ]
14
}
Copied!
Expanding objects
Many objects allow you to request additional information as an expanded response by using the expand request parameter. You can use expand to expand a single type of object, or expand[] to expand multiple types of objects.
The documentation for each endpoint will list which objects are expandable (if any) for that endpoint.
For example, to expand an affiliate you would prepend this query string parameter to the request URL:
1
?expand=affiliate
Copied!
To expand both affiliate and sale objects, prepend this query string parameter to the request URL:
1
?expand[]=affiliate&expand=sale
Copied!

JavaScript API - Previous

Overview

Next - REST API

Affiliates

Last modified 1yr ago

Export as PDF

Copy link

Contents

Authentication

Request and Response Formats

Errors

Pagination

The `pagination` object

Example

Expanding objects