TriportRPC
DashboardDocs

POST /v1/referrals/code — Set custom referral slug

POSThttps://api.triport.io/v1/referrals/code

Create or update the authenticated user's custom referral code (slug).

———

Every account automatically gets a uid referral code derived from its user ID. This endpoint lets a signed-in user pick a friendlier, human-readable custom code (kind = custom) to share instead.

The call is an upsert: the first request creates the custom code, and any later request replaces the slug. The submitted value is normalized server-side (lowercased and trimmed) before validation and storage, so MyCode and mycode both resolve to mycode. A user has at most one active custom code; the existing uid code keeps working alongside it.

To remove a custom code, send DELETE /v1/referrals/code — the uid code remains active.

This route is part of the user-facing referral console and is protected by the session cookie set at login. There is no API-key form for it.

Parameters

Request body

slugstringrequired
Desired custom code. Normalized to lowercase and trimmed before validation. Must be 3–32 characters, contain only a-z, 0-9, and -, and may not start or end with -. Reserved words (e.g. admin) are rejected.

Response

200 OK

codeobject
The created or updated referral code.
code.IDstring (UUID)
Identifier of the code row.
code.UserIDstring (UUID)
Owner of the code.
code.Codestring
The normalized slug as stored and shared.
code.Kindstring
Always custom for this endpoint (the other kind is uid).
code.CreatedAtstring (RFC 3339)
When the code was created.
code.DisabledAtstring (RFC 3339) | null
null while active; set when the code is disabled via DELETE.

Errors

Codeerror valueWhen it happens
400invalid_jsonRequest body is missing or not valid JSON.
400slug_invalidSlug fails the format rules: wrong length (outside 3–32), disallowed characters, or a leading/trailing -.
401unauthenticatedNo valid session cookie.
409slug_reservedSlug is on the reserved/blocked list (e.g. admin).
409slug_takenSlug is already in use by another user.

All errors use the shared error envelope — see errors.md for the full shape and handling guidance.

Examples

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/referrals/code", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include", // send the session cookie
  body: JSON.stringify({ slug: "trip-with-me" }),
});


if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error); // e.g. "slug_taken"
}


const { code } = await res.json();
console.log(code.Code); // "trip-with-me"

TypeScript SDK (@triport/sdk)

import { TriportClient } from "@triport/sdk";


const client = new TriportClient({ baseUrl: "https://api.triport.io" });


const { code } = await client.referrals.setSlug({ slug: "trip-with-me" });
console.log(code.Code, code.Kind); // "trip-with-me" "custom"

Python (triport-sdk)

from triport import TriportClient


client = TriportClient(base_url="https://api.triport.io")


code = client.referrals.set_slug(slug="trip-with-me")
print(code["Code"], code["Kind"])  # trip-with-me custom

Notes

  • Slug rules: length 3–32, charset [a-z0-9-], no leading or trailing -. Input is lowercased and trimmed before these checks run, so casing and surrounding whitespace never cause a rejection on their own.
  • Idempotent upsert: repeating the request with the same slug is safe; sending a new slug replaces the previous custom code.
  • Removing the slug: DELETE /v1/referrals/code disables the custom code (soft delete) and returns {"ok": true}; the uid code continues to work.
  • Related: GET /v1/referrals/me returns the current primary_code and custom_slug alongside referral stats.