Referral Tools

Overview

The referral tools allow you to track and manage the complete referral lifecycle from initial click to conversion. All tools support both Markdown and JSON response formats.

Available Tools

Tool	Description	Permission
`affonso_list_referrals`	List referrals with filtering	`read:referrals`
`affonso_get_referral`	Get a single referral by ID	`read:referrals`
`affonso_create_referral`	Create a new referral/click	`write:referrals`
`affonso_update_referral`	Update referral status	`write:referrals`
`affonso_delete_referral`	Delete a referral	`delete:referrals`

Referral Types

Type	Description
`CLICK`	Initial click on affiliate link
`LEAD`	Signed up but not converted
`CONVERSION`	Completed purchase/signup
`REJECTED`	Referral was rejected
`CANCELLED`	Referral was cancelled

affonso_list_referrals

List and filter referrals across your program.

Parameters

number

default:"1"

Page number for pagination

number

default:"50"

Results per page (max 100)

string

Filter by affiliate ID

string

Filter by type: CLICK, LEAD, CONVERSION, REJECTED, CANCELLED

string

Filter from date (ISO 8601)

string

Filter to date (ISO 8601)

string

default:"markdown"

Response format: markdown or json

Example Prompts

List all referrals
Show conversions from last month
List referrals for affiliate aff_abc123
Show all pending leads
Get referrals between January 1 and January 31

Response

## Referrals (Page 1 of 5)

### ref_abc123
- **Type:** CONVERSION
- **Affiliate:** John Smith (aff_123)
- **Customer:** customer@example.com
- **Amount:** $99.00
- **Created:** Jan 15, 2024

### ref_def456
- **Type:** LEAD
- **Affiliate:** Jane Doe (aff_456)
- **Customer:** lead@example.com
- **Created:** Jan 14, 2024

---
Showing 2 of 50 referrals

{
  "referrals": [
    {
      "id": "ref_abc123",
      "type": "CONVERSION",
      "affiliateId": "aff_123",
      "affiliateName": "John Smith",
      "customerEmail": "customer@example.com",
      "amount": 9900,
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 50,
    "totalPages": 1
  }
}

affonso_get_referral

Get detailed information about a specific referral.

Parameters

string

required

The referral ID (starts with ref_)

string

default:"markdown"

Response format: markdown or json

Example Prompts

Get referral ref_abc123
Show details for referral ref_xyz789
What's the status of referral ref_pending123

Response

## Referral: ref_abc123

| Field | Value |
|-------|-------|
| Type | CONVERSION |
| Affiliate | John Smith (aff_123) |
| Customer | customer@example.com |
| Amount | $99.00 |
| Commission | $9.90 |
| Source | Direct Link |
| Created | Jan 15, 2024 |

### Timeline
1. **Click** - Jan 15, 2024 10:00 AM
2. **Lead** - Jan 15, 2024 10:05 AM
3. **Conversion** - Jan 15, 2024 10:15 AM

{
  "id": "ref_abc123",
  "type": "CONVERSION",
  "affiliateId": "aff_123",
  "affiliateName": "John Smith",
  "customerEmail": "customer@example.com",
  "amount": 9900,
  "commission": 990,
  "source": "direct",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "convertedAt": "2024-01-15T10:15:00.000Z"
}

affonso_create_referral

Create a new referral, typically representing a click or initial tracking event.

Parameters

string

required

The affiliate ID for this referral

string

default:"CLICK"

Referral type: CLICK, LEAD, CONVERSION

string

Customer’s email address

number

Transaction amount in cents (for conversions)

string

Your system’s reference ID

object

Additional custom data

string

default:"markdown"

Response format: markdown or json

Example Prompts

Track a click for affiliate aff_abc123
Create a conversion for aff_xyz with amount $150
Record a lead from customer@example.com for affiliate aff_123
Create a referral with external ID "order_12345"

Response

## Referral Created

| Field | Value |
|-------|-------|
| ID | ref_new123 |
| Type | CLICK |
| Affiliate | John Smith (aff_abc123) |
| Created | Jan 15, 2024 |

The referral is now being tracked.

affonso_update_referral

Update an existing referral’s status or information.

Parameters

string

required

The referral ID to update

string

New referral type

number

Updated transaction amount in cents

string

Updated customer email

string

default:"markdown"

Response format: markdown or json

Example Prompts

Convert referral ref_abc123 to a conversion with amount $99
Update referral ref_xyz to type LEAD
Change the amount on referral ref_123 to $150
Mark referral ref_456 as rejected

Response

## Referral Updated

**ref_abc123** has been updated:
- Type: LEAD → CONVERSION
- Amount: $0.00 → $99.00

A commission will be calculated automatically.

affonso_delete_referral

This is a destructive operation. The referral and associated data will be permanently deleted.

Parameters

string

required

The referral ID to delete

string

default:"markdown"

Response format: markdown or json

Example Prompts

Delete referral ref_abc123
Remove referral ref_test456

Response

## Referral Deleted

Referral **ref_abc123** has been permanently deleted.

Common Workflows

Track a Complete Conversion

"Create a click referral for affiliate aff_abc123"
"Update referral ref_xxx to type LEAD with email customer@example.com"
"Convert referral ref_xxx with amount $99"

Analyze Affiliate Performance

"List all conversions for affiliate aff_abc123 from last month"
"Show me the referral funnel for aff_xyz - how many clicks vs conversions?"

Error Handling

Error	Cause	Solution
`NOT_FOUND`	Referral ID doesn’t exist	Verify the ID is correct
`INVALID_AFFILIATE`	Affiliate ID not found	Check the affiliate exists
`INVALID_TRANSITION`	Invalid status change	Check allowed type transitions
`PERMISSION_DENIED`	Missing required scope	Check your API key permissions

Getting Started

Setup

Tools

Overview

Available Tools

Referral Types

affonso_list_referrals

Parameters

Example Prompts

Response

affonso_get_referral

Parameters

Example Prompts

Response

affonso_create_referral

Parameters

Example Prompts

Response

affonso_update_referral

Parameters

Example Prompts

Response

affonso_delete_referral

Parameters

Example Prompts

Response

Common Workflows

Track a Complete Conversion

Analyze Affiliate Performance

Error Handling

​Overview

​Available Tools

​Referral Types

​affonso_list_referrals

​Parameters

​Example Prompts

​Response

​affonso_get_referral

​Parameters

​Example Prompts

​Response

​affonso_create_referral

​Parameters

​Example Prompts

​Response

​affonso_update_referral

​Parameters

​Example Prompts

​Response

​affonso_delete_referral

​Parameters

​Example Prompts

​Response

​Common Workflows

​Track a Complete Conversion

​Analyze Affiliate Performance

​Error Handling

Overview

Available Tools

Referral Types

affonso_list_referrals

Parameters

Example Prompts

Response

affonso_get_referral

Parameters

Example Prompts

Response

affonso_create_referral

Parameters

Example Prompts

Response

affonso_update_referral

Parameters

Example Prompts

Response

affonso_delete_referral

Parameters

Example Prompts

Response

Common Workflows

Track a Complete Conversion

Analyze Affiliate Performance

Error Handling