---
title: "Record a referral server-side"
method: POST
path: "/affiliate-referrals"
tags: ["Affiliates"]
---

# Record a referral server-side

`POST /affiliate-referrals`

## Request

- Base URL: `https://api.supersendtx.com`
- URL: `https://api.supersendtx.com/affiliate-referrals`
- Auth: HTTP bearer

Attribute a person to a partner without the browser snippet, e.g. from a signup handler that knows the referral code. Name the partner by `affiliate_id` or link `token`. The first partner to claim a person keeps them: a repeat call returns the existing referral with `created: false`. Self-referrals are recorded with `blocked_reason` and never earn. The program must be live and the partner active.

## Request body

- CreateAffiliateReferralRequest: Pass `affiliate_id` or `token`.
  - `affiliate_id` string
  - `token` string: A partner's link token (the `?via=` value)
  - `email` string, email, required
  - `stripe_customer_id` string: Ties later Stripe payments to this referral
  - `sub_id` string

## Response `200`

This person was already referred

- CreateAffiliateReferralResponse
  - `referral` AffiliateReferral, required
    - `object` 'affiliate_referral', required
    - `id` string, required
    - `affiliate_id` string, required
    - `status` 'pending_review' | 'lead' | 'trialing' | 'active' | 'cancelled' | 'refunded' | 'rejected', required
    - `source` 'link' | 'coupon' | 'manual' | 'api' | 'checkout' | 'partner', required
    - `email` string, email, nullable
    - `stripe_customer_id` string, nullable
    - `sub_id` string, nullable: The `sub` tag the partner put on the link
    - `blocked_reason` 'self_referral' | 'duplicate' | 'expired' | 'manual' | 'suspended', nullable: Set on flagged referrals, which never earn
    - `revenue_cents` integer
    - `currency` string, nullable
    - `converted_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `created` boolean, required: false when the person was already referred

## Other responses

- `201`: Referral created
- `400`: Validation error (`details.fields` names each bad field)
- `401`: Missing or invalid API key
- `403`: The API key is not full access, or the action is not allowed
- `404`: No active partner with that id or token
- `409`: The program is not live yet

---

[API](https://skmtc.dev/ranla/apis/supersend-tx-api.md) · [All operations](https://skmtc.dev/ranla/apis/supersend-tx-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranla/apis/supersend-tx-api/revisions/e3e782652f50?raw)