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

# Invite Affiliates

> Create invite links, manage affiliate approvals, and grow your affiliate program.

Once your program is set up and tracking is installed, you need affiliates. AgentRef supports two channels for affiliate recruitment: **invite links** (you reach out directly) and the **marketplace** (affiliates discover you).

This page covers invite links and affiliate lifecycle management.

## Create an invite link

Invite links are unique URLs you share with potential affiliates. When someone visits the link, they can sign up and join your program.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.agentref.co/api/v1/programs/PROGRAM_ID/invites \
    -H "Authorization: Bearer ak_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Partner outreach - March",
      "isPublic": false,
      "usageLimit": 50,
      "expiresInDays": 30
    }'
  ```

  ```javascript Node.js theme={null}
  import { AgentRef } from 'agentref';

  const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' });

  const invite = await client.programs.createInvite('PROGRAM_ID', {
    name: 'Partner outreach - March',
    isPublic: false,
    usageLimit: 50,
    expiresInDays: 30,
  });

  console.log(invite.token); // Share this link with affiliates
  ```

  ```python Python theme={null}
  from agentref import AgentRef

  client = AgentRef(api_key="ak_live_YOUR_KEY")

  invite = client.programs.create_invite(
      "PROGRAM_ID",
      name="Partner outreach - March",
      is_public=False,
      usage_limit=50,
      expires_in_days=30,
  )

  print(invite.token)  # Share this link with affiliates
  ```
</CodeGroup>

### Invite options

| Option           | Type    | Default | Description                                                                                                                      |
| ---------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string  | –       | Internal label for the invite. Not shown to affiliates. Max 100 characters.                                                      |
| `email`          | string  | –       | If set, the invite is tied to a specific email address. Only that email can claim it.                                            |
| `isPublic`       | boolean | `false` | Whether anyone with the link can use it, or only the specified email.                                                            |
| `usageLimit`     | integer | –       | Maximum number of times the invite can be claimed. Range: 1–1,000.                                                               |
| `expiresInDays`  | integer | –       | Days until the invite expires. Range: 1–365.                                                                                     |
| `trackingCode`   | string  | –       | Pre-assign a custom tracking code to the affiliate (e.g., `partner-sarah`). Alphanumeric, hyphens, underscores. 3–50 characters. |
| `skipOnboarding` | boolean | `false` | Skip the onboarding flow when the affiliate claims the invite. Useful for automated integrations.                                |

## Public vs. private invites

**Private invites** (`isPublic: false`) are intended for specific people. If you include an `email`, only that email address can claim the invite. This is the best approach for one-on-one outreach to influencers, partners, or existing customers.

**Public invites** (`isPublic: true`) can be claimed by anyone with the link. Set a `usageLimit` and `expiresInDays` to control usage. This is useful for embedding an "Become an affiliate" link on your website or sharing in newsletters.

<Tip>
  For open enrollment on your website, consider listing your program on the [marketplace](/merchant-guide/marketplace) instead. It gives affiliates a professional discovery experience and handles applications automatically.
</Tip>

## List invites for a program

<CodeGroup>
  ```bash cURL theme={null}
  curl https://www.agentref.co/api/v1/programs/PROGRAM_ID/invites \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  const invites = await client.programs.listInvites('PROGRAM_ID');
  console.log(invites);
  ```

  ```python Python theme={null}
  invites = client.programs.list_invites("PROGRAM_ID")
  print(invites)
  ```
</CodeGroup>

<Info>
  Invite revocation is currently exposed through Merchant MCP as `revoke_invite` and in the dashboard workflow. The REST SDK can create and list program invites, but it does not expose a revoke method yet.
</Info>

## Applications and approval

When someone joins through an invite or applies from the marketplace, their approval path depends on your program settings.

### Auto-approve

With `autoApproveAffiliates: true`, eligible applicants are approved immediately and become affiliate memberships. They can start sharing links right away.

### Manual review

With `autoApproveAffiliates: false`, applicants enter the applications queue. Review applications from the dashboard or through the Applications API:

<CodeGroup>
  ```bash List applications theme={null}
  curl "https://www.agentref.co/api/v1/applications?programId=PROGRAM_ID&status=pending" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```bash Approve application theme={null}
  curl -X POST "https://www.agentref.co/api/v1/applications/APPLICATION_ID/approve" \
    -H "Authorization: Bearer ak_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: approve-application-001" \
    -d '{"note": "Relevant audience and complete profile."}'
  ```

  ```bash Decline application theme={null}
  curl -X POST "https://www.agentref.co/api/v1/applications/APPLICATION_ID/decline" \
    -H "Authorization: Bearer ak_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: decline-application-001" \
    -d '{"note": "Not a fit for this program."}'
  ```
</CodeGroup>

Use `POST /api/v1/applications/{id}/block` when an application should be blocked from future review.

## Affiliate lifecycle

Every affiliate goes through a defined set of states:

```mermaid theme={null}
graph LR
    A[invited or marketplace apply] --> B[application pending]
    B -->|Approve| C[affiliate active]
    B -->|Decline| E[application declined]
    B -->|Block| D[blocked]
    C -->|Misconduct| D
    D -->|Unblock affiliate| C
```

| Status                  | Description                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Invited**             | An invite has been created but not yet claimed.                                                                                                        |
| **Application pending** | The applicant is waiting for merchant review.                                                                                                          |
| **Active**              | The affiliate is approved and can generate referral links, drive traffic, and earn commissions.                                                        |
| **Blocked**             | The affiliate has been blocked. Their referral links stop tracking and no new commissions are generated. Existing pending commissions may be rejected. |

### Unblock an affiliate

If you blocked an affiliate by mistake, you can unblock them:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.agentref.co/api/v1/affiliates/AFFILIATE_ID/unblock \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  await client.affiliates.unblock('AFFILIATE_ID');
  ```

  ```python Python theme={null}
  client.affiliates.unblock("AFFILIATE_ID")
  ```
</CodeGroup>

## List affiliates

View all affiliates across your programs or filter by program:

<CodeGroup>
  ```bash cURL theme={null}
  # All affiliates
  curl https://www.agentref.co/api/v1/affiliates \
    -H "Authorization: Bearer ak_live_YOUR_KEY"

  # Filter by program
  curl https://www.agentref.co/api/v1/programs/PROGRAM_ID/affiliates \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  // All affiliates
  const affiliates = await client.affiliates.list();

  // By program
  const programAffiliates = await client.programs.listAffiliates('PROGRAM_ID');
  ```

  ```python Python theme={null}
  # All affiliates
  affiliates = client.affiliates.list()

  # By program
  program_affiliates = client.programs.list_affiliates("PROGRAM_ID")
  ```
</CodeGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Marketplace" icon="store" href="/merchant-guide/marketplace">
    List your program in the public marketplace for organic affiliate discovery.
  </Card>

  <Card title="Conversions" icon="chart-line" href="/merchant-guide/conversions">
    Understand how conversions are tracked and attributed.
  </Card>
</CardGroup>