Create or update user referrer relationship

Creates or overwrites a referrer-referee relationship via API.

Authentication:

  • Requires API key with service_role scope in the Authorization header: Authorization: Bearer <api_key>
  • The project is automatically derived from the API key's associated project

Use cases:

  • Clients that manage their own referral system (fintechs, CEXs) — sync existing referral relationships with Fuul without using SDK or referral codes flow
  • Projects that need manual control over referral relationships — override, correct, or manually set who referred whom

Behavior:

  • If (project, user_identifier) does NOT exist in user_referrers → create the relationship
  • If it already exists → overwrite the referrer (replace existing)
  • If referral_code is provided, the referral code will be looked up and its rebate_rate will be locked into the user_referrers relationship

Supports all identifier types (email, evm_address, solana_address, etc.).

Body Params
string
required

The identifier of the user (referee)

string
enum
required

The type of identifier for the user

Allowed:
string
required

The identifier of the referrer

string
enum
required

The type of identifier for the referrer

Allowed:
string

Optional referral code to associate with this relationship. If provided, the code will be looked up (must exist and belong to the project), and its rebate_rate will be locked into the user_referrers row.

Responses

400

Bad Request - Invalid identifier, user identifier cannot be the same as referrer identifier, or referral code not found

401

Unauthorized - Missing or invalid API key

403

Forbidden - API key does not have service_role scope

404

Not Found - Project not found

Language
Credentials
Bearer
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json