Skip to main content
POST
/
v1
/
referrals
curl -X POST "https://api.affonso.io/v1/referrals" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_id": "aff_123abc",
    "email": "newcustomer@example.com",
    "customer_id": "cust_456",
    "status": "customer",
    "name": "John Doe",
    "metadata": {
      "plan": "enterprise",
      "source": "webinar"
    }
  }'

{
  "success": true,
  "data": {
    "id": "ref_abc123",
    "affiliate_id": "aff_123abc",
    "program_id": "prog_789xyz",
    "email": "newcustomer@example.com",
    "customer_id": "cust_456",
    "subscription_id": null,
    "status": "customer",
    "name": "John Doe",
    "metadata": {
      "plan": "enterprise",
      "source": "webinar"
    },
    "created_at": "2024-01-20T15:30:00Z",
    "converted_at": "2024-01-20T15:30:00Z"
  }
}

​
Body Parameters

​
affiliate_id
string
required
The unique identifier of the affiliate who referred this customer. The affiliate must belong to your team.
​
email
string
required
The customer’s email address. Must be a valid email format. If a referral with this email already exists for the program, the request will fail with a conflict error.
​
customer_id
string
Your internal customer ID or identifier. Used to link the referral to a customer in your system.
​
subscription_id
string
Your internal subscription ID if this referral is for a subscription. Used to track subscription-based referrals.
​
click_id
string
Optional click ID to convert an existing click to a referral. If provided, the click will be updated to a referral with the specified status. The click must belong to your team and have status CLICK.
​
status
string
default:"lead"
The initial referral status. Valid values: lead, trialing, customer, active, canceled, rejected. Defaults to lead. If set to any value other than lead, converted_at will be automatically set.
​
created_at
string
Optional ISO 8601 timestamp to backdate the referral creation. If not provided, uses the current timestamp.
​
name
string
The customer’s name. Used to identify the referred customer.
​
metadata
object
Custom key-value data for storing additional information about the referral. You can store any JSON-serializable data here.

​
Response

The response includes the created referral object.
​
success
boolean
Always true for successful responses
​
data
object
The created referral object.
curl -X POST "https://api.affonso.io/v1/referrals" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_id": "aff_123abc",
    "email": "newcustomer@example.com",
    "customer_id": "cust_456",
    "status": "customer",
    "name": "John Doe",
    "metadata": {
      "plan": "enterprise",
      "source": "webinar"
    }
  }'

{
  "success": true,
  "data": {
    "id": "ref_abc123",
    "affiliate_id": "aff_123abc",
    "program_id": "prog_789xyz",
    "email": "newcustomer@example.com",
    "customer_id": "cust_456",
    "subscription_id": null,
    "status": "customer",
    "name": "John Doe",
    "metadata": {
      "plan": "enterprise",
      "source": "webinar"
    },
    "created_at": "2024-01-20T15:30:00Z",
    "converted_at": "2024-01-20T15:30:00Z"
  }
}