> ## 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 Affiliate

> Create a new affiliate user

## Body Parameters

<ParamField body="name" type="string" required>
  The affiliate's full display name. Must be between 1 and 100 characters.
</ParamField>

<ParamField body="email" type="string" required>
  The affiliate's email address. Must be a valid email format. If a user with this email already exists, they will be linked to the affiliate account.
</ParamField>

<ParamField body="program_id" type="string" required>
  Program ID to associate affiliate with.
</ParamField>

<ParamField body="tracking_id" type="string">
  Custom tracking ID for the affiliate. Must contain only lowercase letters, numbers, and hyphens. Maximum 100 characters. If not provided, a tracking ID will be automatically generated from the affiliate's name. Must be unique within your team.
</ParamField>

<ParamField body="group_id" type="string">
  Optional affiliate group ID.
</ParamField>

<ParamField body="company_name" type="string">
  Company name for invoice. Maximum 100 characters.
</ParamField>

<ParamField body="country_code" type="string">
  2-letter ISO country code.
</ParamField>

<ParamField body="payout_method" type="string">
  Payout method (lowercase with underscores). Valid values: `paypal`, `wise`, `payoneer`, `paxum`, `webmoney`, `skrill`, `wire_transfer`, `bitcoin`, `ethereum`, `alipay`, `wechat`, `manual`, `none`.
</ParamField>

<ParamField body="payout_details" type="object">
  Payout details (fields vary by method, all snake\_case). The required fields depend on the `payout_method`:

  * **Email-based methods** (`paypal`, `wise`, `payoneer`, `paxum`, `skrill`): `email` (string, valid email)
  * **ID-based methods** (`webmoney`, `alipay`, `wechat`): `account_id` (string)
  * **Crypto methods** (`bitcoin`, `ethereum`): `address` (string, wallet address)
  * **Wire transfer** (`wire_transfer`): `bank_name`, `account_number`, `swift_code`, `iban`, `routing_number`, `account_name` (all strings)
  * **Manual** (`manual`): No details required
</ParamField>

<ParamField body="external_user_id" type="string">
  Your external user ID for linking referral users to your own user system. Useful for matching affiliates back to users in your application. Maximum 255 characters.
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value data for storing additional information about the affiliate. You can store any JSON-serializable data here (e.g., `{"plan": "pro", "signup_source": "landing_page"}`).
</ParamField>

## Response

The response includes the created affiliate object with the following fields:

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

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

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

    <ResponseField name="name" type="string">
      The affiliate's display name
    </ResponseField>

    <ResponseField name="email" type="string">
      The affiliate's email address
    </ResponseField>

    <ResponseField name="tracking_id" type="string">
      Unique tracking ID for the affiliate. If a custom `tracking_id` was provided in the request, it will be used. Otherwise, it's automatically generated from the name (with a random suffix if needed for uniqueness).
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the affiliate creation, always `"api"` for API-created affiliates
    </ResponseField>

    <ResponseField name="partnership_status" type="string">
      Partnership status with the program. Will be `"APPROVED"` for newly created affiliates. Can be `"PENDING"`, `"APPROVED"`, `"REJECTED"`, or `null`.
    </ResponseField>

    <ResponseField name="onboarding_completed" type="boolean">
      Whether the affiliate has completed their onboarding process. Always `false` for newly created affiliates.
    </ResponseField>

    <ResponseField name="program_id" type="string">
      The affiliate program ID the affiliate is assigned to
    </ResponseField>

    <ResponseField name="group_id" type="string | null">
      The affiliate group ID if assigned, otherwise `null`
    </ResponseField>

    <ResponseField name="external_user_id" type="string | null">
      Your external user ID if provided, otherwise `null`
    </ResponseField>

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

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.affonso.io/v1/affiliates" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Jane Smith",
      "email": "jane@example.com",
      "program_id": "cm7xutqbb0001yfkcrnpextmp",
      "company_name": "Jane LLC",
      "country_code": "US",
      "payout_method": "paypal",
      "payout_details": {
        "email": "jane@example.com"
      },
      "external_user_id": "user_123",
      "metadata": {
        "plan": "pro",
        "signup_source": "landing_page"
      }
    }'
  ```

  ```bash cURL (with custom tracking_id) theme={null}
  curl -X POST "https://api.affonso.io/v1/affiliates" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Jane Smith",
      "email": "jane@example.com",
      "program_id": "cm7xutqbb0001yfkcrnpextmp",
      "tracking_id": "janesmith-2024",
      "payout_method": "paypal",
      "payout_details": {
        "email": "jane@example.com"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "cmj8q1wau0003sb01lpvka478",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "tracking_id": "jane-smith",
      "source": "api",
      "partnership_status": "APPROVED",
      "onboarding_completed": false,
      "program_id": "cm7xutqbb0001yfkcrnpextmp",
      "group_id": null,
      "external_user_id": "user_123",
      "metadata": {
        "plan": "pro",
        "signup_source": "landing_page"
      },
      "created_at": "2024-01-25T09:15:00Z"
    }
  }
  ```

  ```json Response (with custom tracking_id) theme={null}
  {
    "success": true,
    "data": {
      "id": "cmj8q1wau0003sb01lpvka478",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "tracking_id": "janesmith-2024",
      "source": "api",
      "partnership_status": "APPROVED",
      "onboarding_completed": false,
      "program_id": "cm7xutqbb0001yfkcrnpextmp",
      "group_id": null,
      "external_user_id": null,
      "metadata": null,
      "created_at": "2024-01-25T09:15:00Z"
    }
  }
  ```
</ResponseExample>

## Notes

* To retrieve related data like promo codes, commission overrides, invoice details, and payout methods, use `GET /v1/affiliates/{id}?expand=promoCodes,commissionOverrides,invoiceDetails,payoutMethod`.
* If you provide a custom `tracking_id` that is already in use by another affiliate in your team, the API will return a `409 Conflict` error with the code `DUPLICATE_ERROR`.
* The `tracking_id` must contain only lowercase letters (a-z), numbers (0-9), and hyphens (-). Any other characters will result in a `400 Bad Request` validation error.