Genius Referrals API

Use this skill to inspect, manage, test, or report on a Genius Referrals referral program through the Genius Referrals API.

Boundaries

• Never store API tokens in the skill.
• Use GR_API_TOKEN from the environment or a user-approved credential source only.
• Send the token as X-Auth-Token; never put it in a URL.
• Default to read-only actions until the target environment, account slug, and intended change are clear.
• Treat production writes, payouts, redemption updates, bonus force actions, and deletes as high-impact. Ask for explicit confirmation before running them.
• Prefer QA or a non-production account for tests.

Environment

Default base URL: https://api.geniusreferrals.com

Optional environment variables:

• GR_API_TOKEN: Genius Referrals API token.
• GR_API_BASE_URL: API base URL override.
• GR_ACCOUNT_SLUG: default account slug.

Workflow

1. Confirm the requested task category: read/report, create/update, payout/redemption, delete, or docs lookup.
2. Identify the environment and account slug. Use GR_API_BASE_URL and GR_ACCOUNT_SLUG when available.
3. Verify authentication with GET /test-authentication before making account-scoped changes.
4. For read-only tasks, call the narrowest endpoint and summarize relevant fields only.
5. For write tasks, prepare a dry-run summary first: method, path, account slug, payload keys, expected impact, rollback or cleanup option.
6. For high-impact tasks, get explicit approval before execution.
7. After execution, report status code, endpoint, resource identifiers, and any next action.

Common Tasks

• List accounts: GET /accounts
• Inspect account: GET /accounts/{account_slug}
• List advocates: GET /accounts/{account_slug}/advocates
• Create advocate or referral candidate: POST /accounts/{account_slug}/advocates
• Update advocate: PATCH /accounts/{account_slug}/advocates/{advocate_token}
• Link referral: POST /accounts/{account_slug}/advocates/{advocate_token}/referrals
• Get share links: GET /accounts/{account_slug}/advocates/{advocate_token}/share-links
• List bonuses: GET /accounts/{account_slug}/bonuses
• Bonus checkup: GET /accounts/{account_slug}/bonuses/checkup
• Force bonus: POST /accounts/{account_slug}/bonuses/force after explicit approval only.
• List redemption requests: GET /accounts/{account_slug}/redemption-requests
• Update redemption request: PATCH /accounts/{account_slug}/redemption-requests/{redemption_request_id} after explicit approval.
• Run reports: use /reports/* endpoints with the required date/account filters from the docs.

Local Helper

Use scripts/gr_api.py when available. It uses only Python stdlib and should be run with python3.

Examples:

GR_API_TOKEN=... python3 scripts/gr_api.py GET /test-authentication
GR_API_TOKEN=... GR_ACCOUNT_SLUG=my-account python3 scripts/gr_api.py GET '/accounts/{account_slug}/advocates' --query limit=10
GR_API_TOKEN=... python3 scripts/gr_api.py PATCH '/accounts/{account_slug}/advocates/{advocate_token}' --account my-account --path-param advocate_token=abc123 --json '{"status":"active"}'

Filter Notes

The docs use filter with | between clauses and :: between field and value.

Example:

filter=name::Jane|status::active

For advocates, documented filter fields include fullname, name, lastname, email, advocate_token, advocate_code, bonus_exchange_method_slug, campaign_slug, can_refer, is_referral, from, to, created, status, status_date_from, status_date_to, is_email_confirmed, campaign_contract_slug, advocate_referrer_token, and fraudulent.

Verification

Before considering a task complete:

• Authentication was checked for API operations.
• Target base URL and account slug were stated.
• Mutating calls include method/path/payload summary.
• High-impact calls include explicit approval evidence.
• Returned status and resource identifiers were reported.