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

# Partner signup

> Turn your own users into partners from inside your app, with a referral link ready to share.

One API call enrolls a user as a partner and creates their referral link. No separate portal signup.

 Your app
POST /v2/partners
 Tolt

Created in Tolt

**partner**part\_8fKq2LmZ…emailsam\@example.comgroupDefaultstatusactive

Ready to share

**link**lnk\_4DwKp9Xm…param"ref"value"sam"urlacme.com/?ref=sam

## Create the partner

Pass the user's email and your `program_id`. Tolt creates the partner in the program's default group (or the `group_id` you pass) and builds a link slug from their name.

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data: partner } = await tolt.partners.create({
  email: "sam@example.com",
  program_id: "prg_Yr4sPdAkHw2dJq7bFaCx9eLm",
  first_name: "Sam",
  last_name: "Rivera",
  link: { value: "sam" },
});

const { param, value } = partner.link;
const shareUrl = `https://acme.com/?${param}=${value}`;
```

```python Python theme={"system"}
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

partner = client.partners.create(
    email="sam@example.com",
    program_id="prg_Yr4sPdAkHw2dJq7bFaCx9eLm",
    first_name="Sam",
    last_name="Rivera",
    link={"value": "sam"},
).data

link = partner.link
share_url = f"https://acme.com/?{link.param}={link.value}"
```

```bash cURL theme={"system"}
curl -X POST https://platform.tolt.com/v2/partners \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "program_id": "prg_Yr4sPdAkHw2dJq7bFaCx9eLm",
    "first_name": "Sam",
    "last_name": "Rivera",
    "link": { "value": "sam" }
  }'
```

The response is the partner (`status: "active"`) with its `link` attached: `{ id, param: "ref", value: "sam" }`.

Store `data.id` on your user record. You need it to show their [dashboard](/guides/refer-a-friend), pull their [stats](/guides/reporting) and change their status.

> **Options and edge cases**
>
> * **Link slug.** Leave out `link` and Tolt slugs the name (or the email before the `@`). `link.param` defaults to your program's first URL parameter. Values are lowercased and must be unique per parameter.
> * **Duplicates.** The same email in the same program, or a link value already taken, returns `409 already_exists`. Check `errors[0].field`: `email` means they're already a partner, so look them up with `GET /v2/partners?search=sam@example.com`; `link.value` means the slug is taken, so pick another or leave out `link`.
> * **Welcome email.** Pass `"notify_partner": true` to send the program's welcome email (only if it is enabled and the partner is active).

## Choose active or pending

Sam Rivera part\_8fKq2LmZ…AppliedPendingDay 0Approved…/approve ActiveDay 1Rejected…/reject RejectedDay 1Suspended…/suspend SuspendedDay 90

Approve returns any partner to active.

New partners are `active` by default and can earn right away. Pass `"status": "pending"` to review them first; you then approve or reject them from the dashboard or the API.

## Approve, reject or suspend

Status changes are actions, not field edits. Each returns the updated partner and fires a `partner.updated` webhook.

```ts TypeScript theme={"system"}
await tolt.partners.approve({ id: "part_8fKq2LmZx7RtYw3nVbHc5dPj" });
await tolt.partners.reject({
  id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  rejection_note: "Not a fit for our audience.",
});
await tolt.partners.suspend({
  id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
  suspension_reason: "Traffic under review.",
});
```

```python Python theme={"system"}
client.partners.approve(id="part_8fKq2LmZx7RtYw3nVbHc5dPj")
client.partners.reject(
    id="part_8fKq2LmZx7RtYw3nVbHc5dPj",
    rejection_note="Not a fit for our audience.",
)
client.partners.suspend(
    id="part_8fKq2LmZx7RtYw3nVbHc5dPj",
    suspension_reason="Traffic under review.",
)
```

```bash cURL theme={"system"}
ID=part_8fKq2LmZx7RtYw3nVbHc5dPj
curl -X POST "https://platform.tolt.com/v2/partners/$ID/approve" \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

Partners are never deleted. Suspend or reject them instead.

## Approve in bulk

Clear a queue of applications with up to 100 ids per call. Each id succeeds or fails on its own. If a request fails partway with a server error, the ids before it are already applied, so check their state before retrying.

```ts TypeScript theme={"system"}
const { data: pending } = await tolt.partners.list({
  status: "pending",
  limit: 100,
});

const { data: result } = await tolt.partners.bulkApprove({
  ids: pending.map((p) => p.id),
});
// Per-id detail is in result.results
console.log(result.succeeded, result.failed);
```

```python Python theme={"system"}
pending = client.partners.list(status="pending", limit=100).items

result = client.partners.bulk_approve(ids=[p.id for p in pending]).data
print(result.succeeded, result.failed)
```

```bash cURL theme={"system"}
curl -X POST https://platform.tolt.com/v2/partners/bulk/approve \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "part_8fKq2LmZx7RtYw3nVbHc5dPj",
      "part_2Rw7KdNq9XmTb4LcVz6pHs1y"
    ]
  }'
```

`POST /v2/partners/bulk/reject` takes the same `ids` plus an optional shared `rejection_note`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.