Intro

The Flourish API is organized around REST.

Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Flourish SDKs

Libraries and tools for interacting with your Flourish integration

Web SDKs

Flourish provides the following web client SDKs to enable integrations with our prebuilt UI components to create all experience of Flourish platform

Web SDK

Mobile SDK

Flourish provides the following mobile SKDs to help you create flutter applications for Apple’s and Android’s devices and platforms. The React Native SDK helps you integrate Flourish into iOS and Android applications built with React Native.

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Integration

Flourish iFrame use bearer authentication token for security. The token provides authentication and authorization to access data.

In order to request a page view, your application needs to request an access token

Request Token

Example Request

curl -X POST "https://api.flourishfi.com/api/v1/access_token"
  -H "Content-Type: application/json"
  -d '{ 
        "partner_uuid": "{{uuid}}", 
        "partner_secret": "{{secret}}", 
        "customer_code": "CLIENT_CUSTOMER_CODE"
      }'

The above command returns the following http status code 200 success response:

{
  "access_token":"{{ACCESS_TOKEN}}"
}

This endpoint is responsible for returning the bearer token to initialize the Web SDK.

HTTP Request

POST https://api.flourishfi.com/api/v1/access_token

Header Parameters

Body

Errors Code

This API returns a 401 if the credentials are invalid

Authentication

Auth Method

Example Request

curl -X POST "https://api.flourishfi.com/api/v1/admin_token"
  -H "Content-Type: application/json"
  -d '{ 
        "partner_uuid": "{{uuid}}", 
        "partner_secret": "{{secret}}"
      }'

The above command returns the following http status code 200 success response:

{
  "access_token":"{{ACCESS_TOKEN}}"
}

This method should be used to request an access token that will be used in any other requests to Flourish's API.

HTTP Request

POST https://api.flourishfi.com/api/v1/admin_token

Header Parameters

Body

Campaign

Set of APIs to perform all movement and inclusion/exclusion of participants in a campaign

Retrieve all active Campaigns

Example Request

curl -H "Authorization: AbCdEf123456" "https://api.flourishfi.com/api/v1/campaign"

The above command returns the following http status code 200 success response:

[{
  "external_id": "0f470ef8-4f35-4044-8446-94514db4eade",
  "description": "Campaign 1",
  "start_datetime": "2024-03-01T22:00:00+0000",
  "end_datetime": "2024-03-31T23:12:33+0000"
}]

This method should be used to retrieve all active campaigns for the client

HTTP Request

GET https://api.flourishfi.com/api/v1/campaign

Header Parameters

HTTP Response

Header Parameters

Body

Add User

curl -X PUT "https://api.flourishfi.com/api/v1/campaign/0f470ef8-4f35-4044-8446-94514db4eade/customer/123"
  -H "Content-Type: application/json"
  -H "Authorization: AbCdEf123456"

The above command returns only a http status code 204 - No Content

Method used to add an user as a participant in the campaign.

HTTP Request

PUT https://api.flourishfi.com/api/v1/campaign/{campaign_id}/customer/{customer_code}

Header Parameters

Path Parameters

Remove User

curl -X DELETE -H "Authorization: AbCdEf123456" "https://api.flourishfi.com/api/v1/campaign/0f470ef8-4f35-4044-8446-94514db4eade/customer/123"

The above command returns only a http status code 204 - No Content

Method used to remove an user as a participant in the campaign.

HTTP Request

DELETE https://api.flourishfi.com/api/v1/campaign/{campaign_id}/customer/{customer_code}

Header Parameters

Path Parameters

Eligibility

Eligibility allows the client to implement, on their side, rules to allow or not allow a customer to redeem prizes.

Eligibility Webhook

Example Request

curl "https://<partner_url>/eligibility/customer/{customer_code}"

The above command returns this response in a JSON

{
  "allow_monetary_prizes" : true
  "allow_gift_card_prizes" : true
}

HTTP Request

GET https://<partner_url>/eligibility/customer/{customer_code}

Header Parameters

HTTP Response

Return 200 with the body filled. Any other return will be defined as ineligible

Response Body

Customer

Use the Customer APIs to retrieve customer's information

Retrieve Wallet Balance

Example Request

curl -H "Authorization: AbCdEf123456" "https://api.flourishfi.com/api/v1/customer/{customer_code}/wallet"

The above command returns the following http status code 200 success response:

{
  "balance": 0.0
}

This method should be used to request an access token that will be used in any other requests to Flourish's API.

HTTP Request

GET https://api.flourishfi.com/api/v1/customer/{customer_code}/wallet

Header Parameters

Path Parameters

HTTP Response

Header Parameters

Body

Referral

Example Request

curl -H "Authorization: AbCdEf123456" "https://api.flourishfi.com/api/v1/customer/{customer_code}/referral/{referral_code}"

The above command returns the following http status code 200 when success and 404 when the referral code didn't exist

This method should be used to inform to Flourish when a referral code is used

HTTP Request

GET https://api.flourishfi.com/api/v1/customer/{customer_code}/referral/{referral_code}"

Header Parameters

Path Parameters

Point Transaction

Example Request

curl -X POST "https://api.flourishfi.com/api/v1/customer/{customer_code}/coin/register"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer AbCdEf123456"
  -d '{
      "type" : "DEBIT",
      "amount" : 0.0
  }'

The above command returns the following http status code 200 when success

This method should be used to add or remove coins in the user's wallet

HTTP Request

POST https://api.flourishfi.com/api/v1/customer/{customer_code}/coin/register

Header Parameters

Path Parameters

Body

Type Enum

Generic Events

The Flourish application can reward a user based on an activity inside your application. In order to move forward with that, you can send that information to Flourish through our Generic Events API:

Before sending us the events, your application needs to authenticate with us first.

Register An Event

Example Request

curl -X POST "https://api.flourishfi.com/api/v1/external/events/register"
  -H "Content-Type: application/json"
  -H "Authorization: AbCdEf123456"
  -d '{
        "event_name": "update-register",
        "customer_code": "123",
        "reference_date" : ""
      }'

The above command returns only a http status code 202 - Accepted

This method should be used for notifying Flourish about any user's event that happens in your system.

HTTP Request

POST https://api.flourishfi.com/api/v1/external/events/register

Header Parameters

Body

Payments

Use the Payments API to build an integration that can observe the payment habits of a user. It tracks a payment made and can trigger prizes.

Registering A Payment Event

Example Request

curl -X PUT "https://api.flourishfi.com/api/v2/payment/register"
  -H "Content-Type: application/json"
  -H "Authorization: AbCdEf123456"
  -d '{
        "customer_code": "123",
        "payment_id": "1000",
        "type": "BILL",
        "channel": "ONLINE",
        "method": "CREDIT_CARD",
        "provider": "CREDIT_UNION",
        "due_date": "2022-04-06",
        "payment_date": "2022-04-06",
        "amount" : 235.25,
        "total_amount" : 1176.25,
        "currency" : "USD",
        "installment_payment" : true,
        "installment" : 1,
        "total_installment" : 5,
        "extra_data": {
          "order" : "12345"
        }
    }'

The above command returns only an HTTP status code 201 - Created

This method should be used to notify Flourish's API about any payment a customer makes.

HTTP Request

PUT https://api.flourishfi.com/api/v2/payment/register

Header Parameters

Body

Channel Enum

Registering an Auto Payment

Example Request

curl -X POST -H "Authorization AbCdEf123456" "https://api.flourishfi.com/api/v1/payment/customer/1234/auto-payment/electric-bill"

This method should be used to notify Flourish's API after the customer set an auto-payment for any type

HTTP Request

POST https://api.flourishfi.com/api/v1/payment/customer/{customer-code}/auto-payment/{type}

Header Parameters

Path Parameters

Unregistering an Auto Payment

Example Request

curl -X DELETE -H "Authorization: AbCdEf123456" "https://api.flourishfi.com/api/v1/payment/customer/1234/auto-payment/electric-bill"

This method should be used to notify Flourish's API after the customer unset an auto-payment for any type

HTTP Request

DELETE https://api.flourishfi.com/api/v1/payment/customer/{customer-code}/auto-payment/{type}

Header Parameters

Path Parameters

Errors Code

This API returns a 404 if there is no auto-payment for that customer-code with the specific type

Transaction

Use the Transaction API to build an integration that can observe all transactions made or received by a user that can trigger a reward

Registering A Transaction Event

Example Request

curl -X PUT "https://api.flourishfi.com/api/v1/transaction/register"
  -H "Content-Type: application/json"
  -H "Authorization AbCdEf123456"
  -d '{
        "customer_code" : "123",
        "transaction_id" : "018d0d4d-58f9-7ab9-ae94-534db4e0b5d1", 
        "amount" : 100.00,
        "currency" : "USD",
        "transaction_date" : "2024-01-02T15:02:11-03:00",
        "type" : "CREDIT",
        "channel" : "ONLINE",
        "method" : "ACCOUNT-TRANSFER", 
        "origin" : "18548494AS",
        "destination" : "1548SFSASS"
    }'

The above command returns only am HTTP status code 202 - Accepted

This method should be used to notify Flourish's API about any transaction a user makes/receive.

HTTP Request

PUT https://api.flourishfi.com/api/v1/transaction/register

Header Parameters

Body

Type Enum

Card Transactions

API used to record all transaction events made with credit and debit cards

Registering A Card Transaction Event

curl -X POST "https://api.flourishfi.com/api/v1/card_transaction/register"
  -H "Content-Type: application/json"
  -H "Authorization: AbCdEf123456"
  -d '{
    "customer_code": "123",
    "transaction_id": "1000",
    "transaction_type": "DEBIT",
    "channel": "ONLINE",
    "wallet": "NO_TOKEN",
    "payment_method": "CREDIT_CARD",
    "transaction_date": "2022-04-06",
    "amount" : 235.25,
    "currency" : "USD",
    "mcc" : "6021",
    "extra_data": {
      "order" : "12345"
    }
}'

The above command returns an HTTP status code 201 - Created if it's the first time that this transaction_id was sent, and 202 - accepted if we received already

This method should be used to notify Flourish's API about any card transaction a customer makes.

HTTP Request

POST https://api.flourishfi.com/api/v1/card_transaction/register

Header Parameters

Body

Channel Enum

Transaction Type Enum

Wallet Enum

Method Enum

Financial Integration

One of the main features of our platform is to evaluate and change the financial behavior of users. We offer some features that allow you to encourage savings and examine customer transactions.

Get User Accounts Information

Example Request

curl "https://<partner_url>/<partner_path>/customer/{customer_code}/accounts"

The above command returns this response in a JSON

[{
        "code" : "123456",
        "display_code" : "01112-3",
        "currency" : "BRL",
        "type" : "Savings Account"
}]

This method is used to retrieve all accounts for the user and allow the user to decide which one to link to the savings milestone feature

HTTP Request

GET https://<partner_url>/<partner_path>/customer/{customer_code}/accounts

Header Parameters

HTTP Response

Enroll User Account

Example Request

curl -X PUT "https://<partner_url>/<partner_path>/customer/{customer_code}/account/{account_code}"

The above command returns only a http status code 202 - Accepted

This method is used to inform the user which account the customer has selected

HTTP Request

PUT /customer/{customer_code}/account/{account_code}

Header Parameters

Registering A Balance Event

Example Request

curl -X POST "https://api.flourishfi.com/api/v1/financial/customer/{customer_code}/account/{account_code}/balance"
  -H "Content-Type: application/json"
  -H "Authorization: AbCdEf123456"
  -d '{
        "balance" : 100.00,
        "reference_date": "YYYY-MM-DD"
      }'

The above command returns only an HTTP status code 201 - Created

This method must be used to inform Flourish about every user closed balance in D-1

HTTP Request

POST https://api.flourishfi.com/api/v1/financial/customer/{customer_code}/account/{account_code}/balance

Header Parameters

Path Parameters

Body

Rewards Events

Reward Notification

Example Request

curl -X POST "https://<partner_url>/<partner_path>"
  -H "Content-Type: application/json"
  -d '{
        "rewards": [{
          "id": "f04aaf22-8423-438c-8e35-279218633448",
          "date_time": "2022-05-02 12:59:14",
          "customer_code": "12345",
          "amount": 50,
          "category": "currency",
          "reason": "sweepstake",
          "extra_data" : {
            "ticket_number" : 12345,
            "ticket_type" : "sweepstake-ticket-1"
          }
        }]
      }'

The above command returns only a http status code 200 - OK

Each reward given internally in Flourish will trigger a callback. If you want to deliver money prizes or save the rewards earned by the users in your system, you can implement an API to receive a callback from us.

This method should be used to retrieve information (through a Callback schema) about rewards given to users by the Flourish system.

HTTP Request

POST https://<partner_url>/<partner_path>

Header Parameters

Body

Category Enum

Reason Enum

Extra Data

Sweepstake

Trivia

Generic Mission/Streak

Referral

Action Enum

Mission Completed Notification

Example Request

curl -X POST "https://<partner_url>/<partner_path>"
  -H "Content-Type: application/json"
  -d '{
        "id": "f04aaf22-8423-438c-8e35-279218633448",
        "date_time": "2022-05-02 12:59:14",
        "customer_code": "12345",
        "amount": 50,
        "category": "currency",
        "reason": "sweepstake",
        "extra_data" : { }
      }'

The above command returns only a http status code 200 - OK

Each mission when given a reward internally in Flourish will trigger a callback. If you want to want to receive information on when the user completes a mission and receive a reward(that can be redeemed or not), you can implement an API to receive a callback from us.

This method should be used to retrieve information (through a Callback schema) about a reward given to users by the Flourish system.

HTTP Request

POST https://<partner_url>/<partner_path> OR POST https://<partner_url>/<partner_path>/customer/{customer_code}

Header Parameters

Body

Category Enum

Reason Enum

Referral

Action Enum

Errors

Supported

The Flourish API uses the following error codes:

400 - Bad Request

For 400 errors we return this object

Body

422 - Unprocessable Entity

For 422 errors we return this object

Body