List the people you referred

list_referrals

Lists the accounts that subscribed through your referral code, with their status and monthly earnings.

POST /v1/list_referralsScopeaccount:readRead only

This is your own referral record and cannot be pointed at anybody else, and it needs no workspace. A referral is listed once its workspace starts a paid subscription carrying your code, so a free signup is not in it, and Share and Earn invites, a separate program, are not counted here.

Each referral has a masked first name in Name, its Plan, BillingPeriod, Status (active, canceled or overdue), JoinedAt and MonthlyEarnings, your commission in dollars. Search by name with term, narrow by status and page with offset and limit, and the answer states the total. See Referrals and payouts.

Request

Call it with a POST to https://api.modulify.ai/v1/list_referrals, sending the inputs below as a JSON object. The token needs the account:read scope.

It only reads and changes nothing, so retrying it is safe.

curl -X POST https://api.modulify.ai/v1/list_referrals \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Over MCP, the same method is the list_referrals tool.

Inputs

Input	Type	Required	Description
`term`	string	No	Matches part of the referred person's name.
`status`	string	No	Only referrals in this status: `active`, `canceled` or `overdue`.
`sort`	string	No	`oldest` puts the oldest first. Anything else, or leaving it out, puts the newest first, by the date the referred workspace was created.
`offset`	integer	No	How many to skip.
`limit`	integer	No	How many to return. Defaults to 8 and is capped at 120.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.