Playbook and FAQs

2min

To add a user to the  system, complete the following steps:
Prepare the User Data: Gather the necessary user information, including a unique user_id, email, and any additional attributes you want to include.
Make a POST Request: Send a POST request to the  endpoint for creating a user﻿.
Accept the terms and conditions: Using the unique user_id in Step 1 above, the user must accept the terms and conditions for  which the user's status will become ACTIVE.
Create a User
Here is an example of how to create a user using cURL:
curl --location 'https://rewards.finfare.com/api/v1/users' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' 
--header 'x-api-key: secret-key'
--data '{
  "publisher_user_id": "unique_user_id",
  "email": "[email protected]",
  "account_status": "PENDING",
  "attributes": {},
  "created_at": "2023-10-01T12:00:00"
}
Response
If the user is successfully created, the API returns a user object with a 200 response code. The response includes the user details that were provided with account_status set to PENDING.
By default, all new users have a PENDING status until they Accept Terms and Conditions, upon which their status will be set to ACTIVE.
Accept terms and conditions
To accept the terms and conditions for a user in the  system, Publishers must use the Accept T&Cs for a user﻿ endpoint. 
Example request
curl --location 'https://rewards.finfare.com/api/v1/terms/accept' \
--header 'Content-Type: application/json' \
--header 'x-api-key: your_api_key' \
--data-raw '{
    "publisher_user_id": "example_user_id",
    "tnc_id": 1
}'
Example response
json{
  "publisher_user_id": "example_user_id",
  "email": "[email protected]",
  "account_status": "Active"
}
Body parameters
Name
Data type
Description
publisher_user_id  REQUIRED﻿
string
Publisher's unique identifier for the user. This ID is sent by the publisher to  to identify a user in the publisher’s system.
tnc_id
REQUIRED﻿
integer
Unique id﻿ of the Terms and Conditions object.
Response
Name
Data type
Description
publisher_user_id 
string
Publisher's unique identifier for the user. This ID is sent by the publisher to  to identify a user in the publisher’s system.
email
string
Email address linked to the user which can be used to directly communicate with the user.
account_status
enum
This indicates the status of the user in the  system and is used primarily to determine if a user has accepted the Terms and Conditions. This can also be used to determine if a user is still active in the system.
Possible values:
ACTIVE - User has accepted Terms and Conditions.
INACTIVE - Indicates that the publisher has deactivated the user.
PENDING - User has not accepted the Terms and Conditions.
By following these steps, publishers can successfully accept the terms and conditions for a user in the   system.
A user can gain rewards on the   system through transactions linked to offers and brands. See the workflow steps below:
Transactions: Users earn rewards by making transactions that are eligible for cashback. These transactions are tracked and linked to specific Offers and Brands﻿. Publishers can use their Plaid﻿ link to send transactions to .
Pending cashback: After a transaction, the rewards are initially marked as pending. This means the cashback is not yet available for redemption. The pending status is typically due to the transaction being within a refund period or awaiting confirmation.
Available cashback: Once the pending period is over and the transaction is confirmed, the cashback becomes available. This available cashback can then be redeemed by the user.
Total earned cashback: This is the cumulative amount of cashback a user has earned over their lifetime on the platform.

To retrieve a summary of a user's rewards, use the Get Rewards Summary for a Single User﻿ endpoint:

The response includes:
available_cashback: The amount of cashback ready to be redeemed.
pending_cashback: The amount of cashback that is not yet available.
total_earned_cashback: The total lifetime cashback earned by the user.

For more detailed information on transactions, use the Get transactions﻿ endpoint to retrieve all reward-related transactions for a user.
In the  system, Offers and Brands play a crucial role in determining the rewards that users can earn through their transactions. Here's how they matter:
﻿Brands﻿﻿
Definition: Brands are products or companies for which offers are promoted by advertisers. In the , brands are often synonymous with advertisers.
Attributes: Each brand has attributes such as a unique identifier brand_uid category ID, name, website, description, logo image URLs, offer description, reward type, maximum customer offer, and global terms and conditions.
Function: Brands are used to find offers and calculate rewards for each transaction. Each brand can be linked to multiple active offers.
﻿Offers﻿﻿
Definition: Offers are specific promotions linked to brands that determine whether transactions are eligible for rewards.
Attributes: Each offer has attributes such as a unique identifier offer_uid, name, description etc.
Types of offers: Offers can be of various types, including card-linked offers, affiliate offers, gift card offers, and voucher code offers.
Reward types: Rewards can be in the form of discounts or cashback. Both reward types can be in dollar amount or percentage.
Importance in the ﻿
Transaction eligibility: Offers determine whether a transaction is eligible for rewards. The system uses the brand information in transactions to find relevant offers.
Reward calculation: The attributes of offers, such as reward type and customer offer amount, are used to calculate the rewards for each transaction.
User Engagement: By linking users to attractive offers from popular brands, the system enhances user engagement and satisfaction.
Customization: Offers can be tailored to specific user segments, such as new customers or location-based offers, providing a personalized experience.
Example
A user makes a purchase at Nike (a brand). The system checks for active offers linked to Nike and calculates the reward based on the offer's attributes, such as a 10% cashback on purchases over $50.
API endpoints
﻿Get brands for a user﻿: Retrieve a list of brands for a given user based on their transactions.
﻿List of Brands﻿: Retrieve a list of brands and corresponding offers for a publisher
Conclusion
Offers and brands are integral to the  system as they enable the calculation and distribution of rewards based on user transactions.
﻿

Name	Data type	Description
publisher_user_id REQUIRED	string	Publisher's unique identifier for the user. This ID is sent by the publisher to to identify a user in the publisher’s system.
tnc_id REQUIRED	integer	Unique id of the Terms and Conditions object.

Name	Data type	Description
publisher_user_id	string	Publisher's unique identifier for the user. This ID is sent by the publisher to to identify a user in the publisher’s system.
email	string	Email address linked to the user which can be used to directly communicate with the user.
account_status	enum	This indicates the status of the user in the system and is used primarily to determine if a user has accepted the Terms and Conditions. This can also be used to determine if a user is still active in the system. Possible values: ACTIVE - User has accepted Terms and Conditions. INACTIVE - Indicates that the publisher has deactivated the user. PENDING - User has not accepted the Terms and Conditions.

Gift Card Purchases

API and White Label change log

Playbook and FAQs

How can I add a rewards user to the Finfare Connect System?

How can a user accumulate rewards in the Finfare Connect System?

How are Offers and Brands important to the Finfare Connect System?