:::endpoint POST /v1/affiliates/pre-registrations

Reserves a referral code for an email address and emails the recipient their link
and claim code.

## Parameters

| Parameter  | Type             | Description                                                    |
| ---------- | ---------------- | -------------------------------------------------------------- |
| `email`    | string, required | Where to send the claim code. Must be unique within your firm. |
| `metadata` | object, optional | Up to 20 string values of 500 characters. Returned unchanged.  |

## Request

```bash
curl -X POST https://api.proppertrading.com/v1/affiliates/pre-registrations \
  -H "Authorization: Bearer sk_live_a1b2c3d4_9f83c2e15b7a4d6e8091c3f5a7b9d1e2" \
  -H "Idempotency-Key: 8f14e45f-ea0d-4d1f-9c4b-3e11f0f2c0a1" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie@example.com",
    "metadata": { "name": "Jamie", "utm_source": "launch-page" }
  }'
```

## Response

`201 Created`

```json
{
    "data": {
        "id": "aff_pre_zd95p9x9prp3cga9thjusesr",
        "object": "affiliate_pre_registration",
        "email": "jamie@example.com",
        "referral_code": "0WWI7YCQ",
        "referral_url": "https://acmefunded.com/r/0WWI7YCQ",
        "status": "pending",
        "source": "api",
        "metadata": { "name": "Jamie", "utm_source": "launch-page" },
        "created_at": "2026-08-03T17:44:13+00:00",
        "expires_at": "2026-09-02T17:44:13+00:00",
        "claimed_at": null,
        "last_sent_at": "2026-08-03T17:44:13+00:00",
        "claim_code": "HR5QPH7NPP"
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}
```

:::danger claim_code is shown once
This is the only response that ever contains `claim_code`. Listing or retrieving
the reservation later will not repeat it. If it is lost, use
[resend](/docs/api/affiliates/resend) to email it again.
:::

## Errors

| Status | Code                        | Meaning                                    |
| ------ | --------------------------- | ------------------------------------------ |
| 400    | `pre_registration_disabled` | Turn pre-registration on in your dashboard |
| 400    | `missing_idempotency_key`   | Add an `Idempotency-Key` header            |
| 409    | `email_already_registered`  | That address already has a reserved code   |
| 422    | `validation_failed`         | See `errors` in the response               |

## Showing it to the visitor

Return both values to your page so the person can copy them right away. Do not
store the claim code in your own database unless you have to; it is a credential,
and we already email it.