Create Referral

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",
    "external_user_id": null,
    "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"
  }
}

POST

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",
    "external_user_id": null,
    "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

string

required

The unique identifier of the affiliate who referred this customer. The affiliate must belong to your team.

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.

string

Your internal customer ID or identifier. Used to link the referral to a customer in your system.

string

Your internal subscription ID if this referral is for a subscription. Used to track subscription-based referrals.

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.

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.

string

Optional ISO 8601 timestamp to backdate the referral creation. If not provided, uses the current timestamp.

string

The customer’s name. Used to identify the referred customer.

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.

boolean

Always true for successful responses

object

The created referral object.

Show Data Object Properties

string

Unique identifier for the referral

string

The affiliate ID who referred this customer

string

The affiliate program ID

string | null

The customer’s email address

string | null

Your internal customer ID if provided

string | null

Your external user ID if this referral is linked to a user from your application

string | null

Your internal subscription ID if provided

string

The referral status (lowercase): lead, trialing, customer, active, canceled, rejected

string | null

The customer’s name if provided

object | null

Custom key-value data if provided

string

ISO 8601 timestamp of when the referral was created

string | null

ISO 8601 timestamp of when the referral was converted (set when status is not lead)

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",
    "external_user_id": null,
    "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"
  }
}

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Response

​Body Parameters

​Response

Body Parameters

Response