Referral Rock MCP by usefulapi

List the referral programs in the account: id, name, type (Web or Form), active flag, title, the member and referral offers and the share/widget URLs. Use the ids (or names) to filter members, referrals and rewards. GET /api/programs.

{
  "type": "object",
  "properties": {
    "program": {
      "description": "Only the program with this id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "offset": {
      "description": "Starting index, 0 based (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "count": {
      "description": "Results per page, 1-200 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One referral program by its exact name: id, active flag, offers and URLs. GET /api/program/getsingle.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The program's exact name (see referralrock_list_programs)."
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The reward rules of one program: what triggers a reward (referral status, referral count or sales limits), how the amount is worked out (fixed or percent), the payout type and delivery delay. GET /api/rewardrules.

{
  "type": "object",
  "properties": {
    "program_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Program id (a GUID; see referralrock_list_programs)."
    }
  },
  "required": [
    "program_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List members (the people who refer others), newest first by default, with their referral code and share URL, referral counts, rewards earned and activity dates. Filter by program, by an email / id / external id / referral code, by created date, or active vs disabled. GET /api/members.

{
  "type": "object",
  "properties": {
    "program": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Program id, program name or program title."
    },
    "query": {
      "description": "A member's email address, id, external id or referral code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "show_disabled": {
      "description": "true = disabled members, false = active members. Leave out for the default.",
      "type": "boolean"
    },
    "sort": {
      "description": "Sort order (default Create_Dt_Desc).",
      "type": "string",
      "enum": [
        "Create_Dt_Desc",
        "Create_Dt_Asc",
        "Member_Views_Desc",
        "Member_Views_Asc",
        "Page_Views_Desc",
        "Page_Views_Asc",
        "Lead_Count_Desc",
        "Lead_Count_Asc",
        "Reward_Issued_Total_Desc",
        "Reward_Issued_Total_Asc",
        "Member_Full_Name_Desc",
        "Member_Full_Name_Asc"
      ]
    },
    "date_from": {
      "description": "Only members created after this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "date_to": {
      "description": "Only members created before this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "offset": {
      "description": "Starting index, 0 based (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "count": {
      "description": "Results per page, 1-200 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Sharing, referral and reward statistics of one member over a time period: views, shares, referrals (pending / qualified / approved), reward amounts pending and issued, last share and activity dates. GET /api/memberstats/getsingle.

{
  "type": "object",
  "properties": {
    "member": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The member's email address, id, external id or referral code."
    },
    "time_period": {
      "description": "All (default), MonthToDate, LastMonth, Last7Days or Last30Days.",
      "type": "string",
      "enum": [
        "All",
        "MonthToDate",
        "LastMonth",
        "Last7Days",
        "Last30Days"
      ]
    }
  },
  "required": [
    "member"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List referrals (the people members referred), newest first by default, with status (pending, qualified, approved, denied), amount, the referring member, notes and dates. Filter by program, status, referring member, free-text query or created date. GET /api/referrals.

{
  "type": "object",
  "properties": {
    "program": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Program id, program name or program title."
    },
    "status": {
      "description": "Only referrals in this status.",
      "type": "string",
      "enum": [
        "pending",
        "qualified",
        "approved",
        "denied"
      ]
    },
    "member_id": {
      "description": "Only referrals made by this member id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "query": {
      "description": "A referral's email address, id, external id or referral code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "sort": {
      "description": "Sort order (default Create_Dt_Desc).",
      "type": "string",
      "enum": [
        "Create_Dt_Desc",
        "Create_Dt_Asc",
        "Amount_Desc",
        "Amount_Asc",
        "Qualified_Dt_Desc",
        "Qualified_Dt_Asc",
        "Closed_Dt_Desc",
        "Closed_Dt_Asc"
      ]
    },
    "date_from": {
      "description": "Only referrals created after this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "date_to": {
      "description": "Only referrals created before this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "offset": {
      "description": "Starting index, 0 based (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "count": {
      "description": "Results per page, 1-200 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One referral by id, email address or external id (at least one is required): status, amount, referring member, notes, custom fields and dates. GET /api/referral/single.

{
  "type": "object",
  "properties": {
    "referral_id": {
      "description": "The referral's id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "description": "The referral's email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "external_id": {
      "description": "The referral's external identifier.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List rewards, newest first by default: recipient, amount, status (Pending, Processing, Issued), payout type, eligibility and issue dates, the member and referral behind it. Filter by program, member, status, recipient query or created date. GET /api/rewards.

{
  "type": "object",
  "properties": {
    "program": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Program id, program name or program title."
    },
    "member_id": {
      "description": "Only rewards of this member id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "query": {
      "description": "The recipient's email address, id, external id or member referral code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "status": {
      "description": "Only rewards in this status.",
      "type": "string",
      "enum": [
        "Pending",
        "Processing",
        "Issued"
      ]
    },
    "sort": {
      "description": "Sort order (default Create_Dt_Desc).",
      "type": "string",
      "enum": [
        "Create_Dt_Desc",
        "Create_Dt_Asc",
        "Reward_Action_Desc",
        "Reward_Action_Asc",
        "Recipient_Name_Desc",
        "Recipient_Name_Asc",
        "Complete_Dt_Desc",
        "Complete_Dt_Asc"
      ]
    },
    "date_from": {
      "description": "Only rewards created after this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "date_to": {
      "description": "Only rewards created before this date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
    },
    "offset": {
      "description": "Starting index, 0 based (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "count": {
      "description": "Results per page, 1-200 (default 20).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Payouts that are owed but not yet transferred: recipient, program, number of rewards and total amount. Optionally for one recipient, and optionally including rewards whose eligibility date is still in the future. GET /api/payouts/pending.

{
  "type": "object",
  "properties": {
    "recipient_id": {
      "description": "Only the payouts owed to this recipient id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "include_ineligible": {
      "description": "Also include payouts for rewards with an eligibility date in the future (default false).",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Payout transactions already transferred to program participants (type, amount, date, status, destination, vendor errors) and the balance left in the account to cover pending payouts. Optionally for one recipient or one transaction. GET /api/payouts/transactions.

{
  "type": "object",
  "properties": {
    "recipient_id": {
      "description": "Only the transactions paid to this recipient id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "transaction_id": {
      "description": "Only this transaction id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a new member (advocate) in a referral program and returns the member with their referral code and share URL. Not idempotent: a repeat call may create a duplicate or fail. When send_confirmation_email is true Referral Rock emails the member the program's confirmation email, which is a message to a real person; the default is false. POST /api/members.

{
  "type": "object",
  "properties": {
    "program_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Program id to add the member to (see referralrock_list_programs)."
    },
    "first_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Member first name."
    },
    "email": {
      "type": "string",
      "minLength": 1,
      "maxLength": 254,
      "description": "Member email address."
    },
    "last_name": {
      "description": "Member last name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "phone": {
      "description": "Member phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "external_id": {
      "description": "Your own id for this member, to link it to another system.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "referral_code": {
      "description": "A custom referral code; Referral Rock generates one when left out.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "send_confirmation_email": {
      "description": "Email the member the program's confirmation email (default false; needs confirm: true).",
      "type": "boolean"
    },
    "confirm": {
      "description": "Must be true when send_confirmation_email is true: confirms an email goes to the member.",
      "type": "boolean"
    }
  },
  "required": [
    "program_id",
    "first_name",
    "email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: changes contact details of an existing member, or disables / re-enables the member (a disabled member can no longer take part in the programs). Only the fields you pass are changed. The member is found by id, referral code, or email / external id plus program_id or program_name; Referral Rock updates it only when it is uniquely identified. POST /api/members/update.

{
  "type": "object",
  "properties": {
    "member_id": {
      "description": "The member's id (preferred).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "referral_code": {
      "description": "The member's referral code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "email": {
      "description": "The member's current email address (needs program_id or program_name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "external_id": {
      "description": "The member's current external identifier (needs program_id or program_name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "program_id": {
      "description": "Program id; needed together with email or external_id (or give program_name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "program_name": {
      "description": "Program name; needed together with email or external_id (or give program_id).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "new_first_name": {
      "description": "New first name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "new_last_name": {
      "description": "New last name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "new_email": {
      "description": "New email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "new_phone": {
      "description": "New phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "new_external_id": {
      "description": "New external identifier.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "disabled": {
      "description": "true disables the member, false re-enables.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: adds a referral (a lead) to the program of the member who owns the given referral code, as if the lead had used that member's link. A status of qualified or approved can trigger the program's configured rewards for the member, which is a financial commitment, so leave status out (new referrals start as pending) unless you mean it. Not idempotent. POST /api/referrals.

{
  "type": "object",
  "properties": {
    "referral_code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "The referral code of the member who introduced the referral (see referralrock_list_members)."
    },
    "first_name": {
      "description": "Referral first name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "last_name": {
      "description": "Referral last name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "description": "Referral email address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "phone": {
      "description": "Referral phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "preferred_contact": {
      "description": "Preferred way to contact the referral.",
      "type": "string",
      "enum": [
        "email",
        "callMorning",
        "callAfternoon",
        "callEvening"
      ]
    },
    "external_id": {
      "description": "Your own unique id for the referral (an order or customer id), to find it again.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "amount": {
      "description": "Order amount / total tied to the referral.",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "company_name": {
      "description": "Company name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "note": {
      "description": "Private note tied to the referral.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "status": {
      "description": "Initial status (default pending). qualified / approved may trigger rewards and need confirm: true.",
      "type": "string",
      "enum": [
        "pending",
        "qualified",
        "approved",
        "denied"
      ]
    },
    "confirm": {
      "description": "Must be true when status is qualified or approved: confirms rewards may be issued.",
      "type": "boolean"
    }
  },
  "required": [
    "referral_code"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: changes the status, amount or notes of an existing referral. Moving a referral to qualified or approved can trigger the program's configured rewards for the referring member (a financial commitment that may be paid out automatically), and denied stops them: confirm with the user first. Only the fields you pass are changed. The referral is found by id, or by external id / email plus program_id or program_name. POST /api/referral/update.

{
  "type": "object",
  "properties": {
    "referral_id": {
      "description": "The referral's id (preferred).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "external_id": {
      "description": "The referral's external identifier (needs program_id or program_name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "description": "The referral's email address (needs program_id or program_name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "program_id": {
      "description": "Program id; needed together with external_id or email (or give program_name).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "program_name": {
      "description": "Program name; needed together with external_id or email (or give program_id).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "status": {
      "description": "New status.",
      "type": "string",
      "enum": [
        "pending",
        "qualified",
        "approved",
        "denied"
      ]
    },
    "amount": {
      "description": "New order amount / total (used for percentage rewards).",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "note": {
      "description": "New private note.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "public_note": {
      "description": "New public note.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "confirm": {
      "description": "Must be true when status is qualified or approved, or amount is set: confirms rewards may be issued or changed.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: reports a paying customer to Referral Rock. A customer whose email matches a pending referral turns that referral to approved, which triggers the program's configured rewards for the referring member (a financial commitment that may be paid out automatically). A customer with no matching referral is added as a pre-loaded member to every program that has Preload New Customers on. Returns the outcome per customer (ReferralApproved, MemberPreloaded, Skipped…). Not idempotent. POST /api/customerfeed.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "minLength": 1,
      "maxLength": 254,
      "description": "The customer's email address; the match key against pending referrals and members."
    },
    "external_id": {
      "description": "Your own id for this customer (for example a CRM id).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "first_name": {
      "description": "Customer first name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "last_name": {
      "description": "Customer last name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "phone": {
      "description": "Customer phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "amount": {
      "description": "Purchase amount; feeds percentage rewards (default 0).",
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000
    },
    "purchase_date": {
      "description": "Purchase date, ISO 8601 (default: now, UTC).",
      "type": "string",
      "maxLength": 40
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms a matching pending referral may be approved and its rewards issued."
    }
  },
  "required": [
    "email",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}