Create Referral

Creates a referral link. For type="event", supply event_id; for type="facebook-pixel", supply pixel_id. Do not set newsletter_tracking_links — the b2b newsletter-send flow sets that server-side when it creates the referrals for an event-block.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Request Body

application/jsonRequired

labelRequiredstring

Display label. For newsletter referrals this is the newsletter id.

typeRequiredstring

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

Value in: "user" | "event" | "facebook-pixel"

event_idstring

Required for type="event". Scopes the referral to one event.

pixel_idstring

Required for type="facebook-pixel". The pixel id.

apply_to_all_eventsboolean

When true, this referral applies to every event on the host (rather than just event_id).

newsletter_tracking_linksboolean

Server-set by the /b2b/newsletters/:id/referrals flow; clients should not set this.

POST/v1/referrals/

curl -X POST "https://api.3common.com/v1/referrals/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "string",
    "type": "user",
    "event_id": "string",
    "pixel_id": "string",
    "apply_to_all_events": true,
    "newsletter_tracking_links": true
  }'

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
  }
}

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;
  };
}