> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Referral

> Create a new referral or convert an existing click to a referral

## Body Parameters

<ParamField body="affiliate_id" type="string" required>
  The unique identifier of the affiliate who referred this customer. The affiliate must belong to your team.
</ParamField>

<ParamField body="email" type="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.
</ParamField>

<ParamField body="customer_id" type="string">
  Your internal customer ID or identifier. Used to link the referral to a customer in your system.
</ParamField>

<ParamField body="subscription_id" type="string">
  Your internal subscription ID if this referral is for a subscription. Used to track subscription-based referrals.
</ParamField>

<ParamField body="click_id" type="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`.
</ParamField>

<ParamField body="status" type="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.
</ParamField>

<ParamField body="created_at" type="string">
  Optional ISO 8601 timestamp to backdate the referral creation. If not provided, uses the current timestamp.
</ParamField>

<ParamField body="name" type="string">
  The customer's name. Used to identify the referred customer.
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value data for storing additional information about the referral. You can store any JSON-serializable data here.
</ParamField>

## Response

The response includes the created referral object.

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="object">
  The created referral object.

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the referral
    </ResponseField>

    <ResponseField name="affiliate_id" type="string">
      The affiliate ID who referred this customer
    </ResponseField>

    <ResponseField name="program_id" type="string">
      The affiliate program ID
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The customer's email address
    </ResponseField>

    <ResponseField name="customer_id" type="string | null">
      Your internal customer ID if provided
    </ResponseField>

    <ResponseField name="external_user_id" type="string | null">
      Your external user ID if this referral is linked to a user from your application
    </ResponseField>

    <ResponseField name="subscription_id" type="string | null">
      Your internal subscription ID if provided
    </ResponseField>

    <ResponseField name="status" type="string">
      The referral status (lowercase): `lead`, `trialing`, `customer`, `active`, `canceled`, `rejected`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The customer's name if provided
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value data if provided
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the referral was created
    </ResponseField>

    <ResponseField name="converted_at" type="string | null">
      ISO 8601 timestamp of when the referral was converted (set when status is not `lead`)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>