Get Referral

Retrieves a single referral by id, including its computed metrics.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Path Parameters

idRequiredstring

Referral id, discoverable via list_referrals

GET/v1/referrals/{id}

curl -X GET "https://api.3common.com/v1/referrals/string" \
  -H "Authorization: Bearer <token>"

Default Response

Response

{
  "data": {
    "id": "string",
    "hostId": "string",
    "label": "string",
    "type": "user",
    "event_id": "string",
    "pixel_id": "string",
    "apply_to_all_events": true,
    "newsletter_tracking_links": true,
    "createdAt": 0,
    "updatedAt": 0,
    "views": -9007199254740991,
    "revenue": -9007199254740991,
    "tickets": -9007199254740991,
    "event_name": "string",
    "newsletter_subject": "string",
    "category": "newsletter",
    "category_label": "string",
    "display_name": "string"
  }
}

TypeScript

export interface Response {
  data: {
    id: string;
    hostId: string;
    label: string;
    /**
     * Referral kind.
     * - user: generic per-host link (rare today)
     * - event: tied to one event id; revenue join keys off these
     * - facebook-pixel: fb pixel association, no view tracking
     */
    type: "user" | "event" | "facebook-pixel";
    event_id?: string;
    pixel_id?: string;
    apply_to_all_events?: boolean;
    /**
     * True when this referral was generated by the newsletter send flow
     */
    newsletter_tracking_links?: boolean;
    /**
     * Creation timestamp, ms since epoch
     */
    createdAt: number;
    /**
     * Last-updated timestamp, ms since epoch
     */
    updatedAt: number;
    /**
     * Count of view rows attached to this referral
     */
    views: number;
    /**
     * Sum of purchase view value, in cents
     */
    revenue: number;
    /**
     * Sum of purchase view ticket qty
     */
    tickets: number;
    /**
     * Resolved event title for event referrals. Absent when the event was deleted or never existed.
     */
    event_name?: string;
    /**
     * Resolved newsletter subject when newsletter_tracking_links=true (the label IS the newsletter id). Absent when the newsletter was deleted.
     */
    newsletter_subject?: string;
    /**
     * Machine-readable classification. For user-facing rendering use
     * 'category_label' instead. Derived from type + newsletter_tracking_links:
     * - "newsletter":     link auto-created by a newsletter send (type='event' AND newsletter_tracking_links=true)
     * - "event":          manual per-event tracking link
     * - "facebook-pixel": Meta pixel
     * - "user":           legacy per-host link
     */
    category: "newsletter" | "event" | "facebook-pixel" | "user";
    /**
     * Pre-formatted human-readable category. ALWAYS use this when
     * rendering the row's kind to a user — don't reformat 'category'
     * yourself.
     * - "Newsletter tracking link"
     * - "Event tracking link"
     * - "Meta Pixel"
     * - "User tracking link"
     */
    category_label: string;
    /**
     * Human-readable name for this referral. ALWAYS use this when
     * rendering the referral to a user — NEVER show 'label' directly,
     * because for newsletter referrals it's the newsletter id (an opaque
     * ObjectId). Resolution:
     * - newsletter referrals  → newsletter_subject (or "(deleted newsletter)" when the newsletter was removed)
     * - facebook-pixel       → pixel_id (or label when pixel_id missing)
     * - event / user         → label
     */
    display_name: string;
  };
}